@allbluecn/web-app 0.12.0 → 0.12.3

package/src/server/ai-gateway/sandbox/__tests__/harness-sandbox.test.ts

@@ -0,0 +1,170 @@
+// @vitest-environment node
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+const mocks = vi.hoisted(() => {
+  const withSandbox = vi.fn()
+  const defineSandbox = vi.fn((config: unknown) => config)
+  const sandboxPolicyFor = vi.fn()
+  const resolveSandboxProvider = vi.fn()
+  const prismaInstanceStore = vi.fn()
+  const pgLockStore = vi.fn()
+  return {
+    withSandbox,
+    defineSandbox,
+    sandboxPolicyFor,
+    resolveSandboxProvider,
+    prismaInstanceStore,
+    pgLockStore,
+  }
+})
+
+vi.mock("@tanstack/ai-sandbox", async (importOriginal) => {
+  const original = await importOriginal<typeof import("@tanstack/ai-sandbox")>()
+  return {
+    ...original,
+    defineSandbox: mocks.defineSandbox,
+    withSandbox: mocks.withSandbox,
+  }
+})
+vi.mock("../policy", () => ({
+  sandboxPolicyFor: mocks.sandboxPolicyFor,
+  SANDBOX_DEFAULT_POLICY_LEVEL: "readonly",
+  isSandboxPolicyLevel: () => true,
+}))
+vi.mock("../provider", () => ({
+  resolveSandboxProvider: mocks.resolveSandboxProvider,
+}))
+vi.mock("../instance-store", () => ({
+  prismaInstanceStore: mocks.prismaInstanceStore,
+}))
+vi.mock("../../locks/pg-lock", () => ({
+  pgLockStore: mocks.pgLockStore,
+}))
+
+import { InMemoryRunStore } from "@tanstack/ai"
+import { InMemoryLockStore } from "@tanstack/ai/locks"
+import { buildSandboxMiddleware } from "../harness-sandbox"
+
+const RUNS = new InMemoryRunStore()
+
+function baseParams(overrides: Record<string, unknown> = {}) {
+  return {
+    threadId: "thread-1",
+    policyLevel: "readonly" as const,
+    runs: RUNS,
+    ...overrides,
+  }
+}
+
+describe("buildSandboxMiddleware 装配", () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.unstubAllEnvs()
+    delete process.env.DEPLOY_TARGET
+    mocks.resolveSandboxProvider.mockResolvedValue({ provider: { name: "mock" } })
+    mocks.defineSandbox.mockImplementation((config: unknown) => config)
+    mocks.prismaInstanceStore.mockReturnValue({ store: "prisma" })
+    mocks.pgLockStore.mockReturnValue({ lock: "pg" })
+    mocks.sandboxPolicyFor.mockImplementation((level: string) => ({ policy: level }))
+    mocks.withSandbox.mockReturnValue({ middleware: "sandbox" })
+  })
+
+  afterEach(() => vi.unstubAllEnvs())
+
+  it("defineSandbox 以 thread 级 key 派生实例 id，并绑定生命周期与 diff 事件", async () => {
+    await buildSandboxMiddleware(baseParams())
+
+    const definition = mocks.defineSandbox.mock.calls[0][0] as Record<string, unknown>
+    expect(definition.id).toBe("thread:thread-1")
+    expect(definition.provider).toEqual({ name: "mock" })
+    expect(definition.policy).toEqual({ policy: "readonly" })
+    expect(definition.lifecycle).toEqual({
+      reuse: "thread",
+      destroyOnComplete: false,
+      keepAlive: "30m",
+    })
+    expect(definition.fileEvents).toEqual({ diff: true })
+  })
+
+  it("withSandbox 无条件拿到 instances / locks / runs——runs 与 chat persistence 同一实例", async () => {
+    await buildSandboxMiddleware(baseParams())
+
+    const options = mocks.withSandbox.mock.calls[0][1] as Record<string, unknown>
+    expect(options.instances).toEqual({ store: "prisma" })
+    expect(options.locks).toEqual({ lock: "pg" })
+    expect(options.runs).toBe(RUNS)
+  })
+
+  it.each(["readonly", "workspace-write", "full"] as const)(
+    "policyLevel %s 原样下传给策略派生（不静默降级）",
+    async (level) => {
+      await buildSandboxMiddleware(baseParams({ policyLevel: level }))
+      expect(mocks.sandboxPolicyFor).toHaveBeenCalledWith(level)
+    },
+  )
+
+  it("DEPLOY_TARGET=desktop 时用进程内锁，否则用 PG advisory lock", async () => {
+    vi.stubEnv("DEPLOY_TARGET", "desktop")
+    await buildSandboxMiddleware(baseParams())
+    expect(mocks.pgLockStore).not.toHaveBeenCalled()
+    const desktopLocks = (mocks.withSandbox.mock.calls[0][1] as Record<string, unknown>).locks
+    expect(desktopLocks).toBeInstanceOf(InMemoryLockStore)
+  })
+
+  it("非 desktop 部署用 PG advisory lock 串行化 resume-or-create", async () => {
+    vi.stubEnv("DEPLOY_TARGET", "vercel")
+    await buildSandboxMiddleware(baseParams())
+    expect(mocks.pgLockStore).toHaveBeenCalledTimes(1)
+    const locks = (mocks.withSandbox.mock.calls[0][1] as Record<string, unknown>).locks
+    expect(locks).toEqual({ lock: "pg" })
+  })
+
+  it("传 durabilityFactory 时装配 delivery 持久化并 detach（多实例 durable runs）", async () => {
+    const adapter = { append: vi.fn(), read: vi.fn() }
+    const factory = { resumeAdapter: vi.fn(() => adapter) }
+    await buildSandboxMiddleware(baseParams({ durabilityFactory: factory }))
+
+    const options = mocks.withSandbox.mock.calls[0][1] as { durability?: unknown }
+    expect(factory.resumeAdapter).toHaveBeenCalledTimes(1)
+    expect(options.durability).toEqual({
+      adapter,
+      attach: false,
+      detachOnDisconnect: true,
+    })
+  })
+
+  it("不传 durabilityFactory 时无 durability 键（desktop 合法的 destroy-on-disconnect 形态）", async () => {
+    await buildSandboxMiddleware(baseParams())
+    const options = mocks.withSandbox.mock.calls[0][1] as Record<string, unknown>
+    expect(options).not.toHaveProperty("durability")
+    // snapshots 已始终装配（含 memory checkpoint store + artifacts/blobs store 骨架）
+    expect(options).toHaveProperty("snapshots")
+  })
+
+  it("workspace 显式传入才带 workspace 键（P3b 前保持最小配置面）", async () => {
+    await buildSandboxMiddleware(baseParams())
+    expect(mocks.defineSandbox.mock.calls[0][0]).not.toHaveProperty("workspace")
+
+    await buildSandboxMiddleware(baseParams({ workspace: { localPath: "/tmp/ws" } }))
+    expect((mocks.defineSandbox.mock.calls[1][0] as Record<string, unknown>).workspace).toEqual({
+      localPath: "/tmp/ws",
+    })
+  })
+
+  it("hooks.onError 只输出 message（避免完整 Error 对象进日志）", async () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {})
+    try {
+      await buildSandboxMiddleware(baseParams())
+      const hooks = (mocks.defineSandbox.mock.calls[0][0] as { hooks: unknown }).hooks as {
+        onError: (err: unknown) => void
+      }
+      hooks.onError(new Error("sandbox exploded"))
+      hooks.onError("plain string failure")
+      expect(spy).toHaveBeenNthCalledWith(1, "[sandbox]", "sandbox exploded")
+      expect(spy).toHaveBeenNthCalledWith(2, "[sandbox]", "plain string failure")
+    } finally {
+      spy.mockRestore()
+    }
+  })
+})

package/src/server/ai-gateway/sandbox/__tests__/instance-store.test.ts

@@ -0,0 +1,130 @@
+import { prisma } from "@allbluecn/database"
+import { type SandboxInstanceRecord } from "@tanstack/ai-sandbox"
+import { afterAll, beforeAll, describe, expect, it } from "vitest"
+
+import { prismaInstanceStore } from "../instance-store"
+
+/**
+ * 真库测试：SandboxInstanceStore 三不变量 + 往返一致性。
+ *
+ * testkit 未导出 instance-store 的 conformance 套件（conformance.d.ts 只有
+ * journal/takeover/reaper/durable-run-fields/checkpoint-* 六个），故手写守护。
+ *
+ * skip sqlite 分支：sandbox_instances 在双 schema 同构，desktop 本可跑，但项目
+ * 只有 psql 测试环境（与 pg-stream.test.ts 保持一致）。
+ */
+
+const PREFIX = `itest:${process.pid}:${Date.now()}`
+
+function makeRecord(key: string, extra: Partial<SandboxInstanceRecord> = {}) {
+  return {
+    key,
+    provider: "docker",
+    providerSandboxId: "sbx-test",
+    threadId: "thread-test",
+    updatedAt: 1_765_000_000_000,
+    ...extra,
+  } satisfies SandboxInstanceRecord
+}
+
+describe.skipIf(
+  !process.env.DATABASE_URL || process.env.DATABASE_PROVIDER === "sqlite",
+)("prismaInstanceStore（真库，三不变量）", () => {
+  const store = prismaInstanceStore()
+
+  beforeAll(async () => {
+    await prisma.sandboxInstance.deleteMany({
+      where: { key: { startsWith: PREFIX } },
+    })
+  })
+
+  afterAll(async () => {
+    await prisma.sandboxInstance.deleteMany({
+      where: { key: { startsWith: PREFIX } },
+    })
+  })
+
+  it("get 不存在的 key 返回 null，不抛错", async () => {
+    await expect(store.get(`${PREFIX}:nope`)).resolves.toBeNull()
+  })
+
+  it("upsert 后 get 往返一致（含 optional 字段）", async () => {
+    const record = makeRecord(`${PREFIX}:roundtrip`, {
+      latestSnapshotId: "snap-1",
+      latestRunId: "run-1",
+      updatedAt: 1_765_111_111_111,
+    })
+    await store.upsert(record)
+
+    expect(await store.get(record.key)).toEqual(record)
+  })
+
+  it("upsert 省略 optional 字段时显式清空旧值（全量替换不变量）", async () => {
+    const key = `${PREFIX}:clear`
+    await store.upsert(
+      makeRecord(key, { latestSnapshotId: "snap-old", latestRunId: "run-old" }),
+    )
+    // 无 snapshot 的创建路径：不传 latestSnapshotId / latestRunId
+    await store.upsert(makeRecord(key, { updatedAt: 1_765_222_222_222 }))
+
+    expect(await store.get(key)).toEqual(
+      makeRecord(key, { updatedAt: 1_765_222_222_222 }),
+    )
+
+    // 直查数据库确认是 NULL 而非 API 层的 undefined 转换——若实现用 undefined
+    // （Prisma 会跳过该字段保留旧值）而非 null，这里会失败。
+    const row = await prisma.sandboxInstance.findUnique({ where: { key } })
+    expect(row?.latestSnapshotId).toBeNull()
+    expect(row?.latestRunId).toBeNull()
+  })
+
+  it("同一 key 重复 upsert 是幂等覆盖", async () => {
+    const key = `${PREFIX}:idempotent`
+    await store.upsert(makeRecord(key, { providerSandboxId: "sbx-a" }))
+    await store.upsert(makeRecord(key, { providerSandboxId: "sbx-b" }))
+
+    expect(await store.get(key)).toEqual(
+      makeRecord(key, { providerSandboxId: "sbx-b" }),
+    )
+  })
+
+  it("updatedAt 往返为 epoch ms（BigInt 列，store 出口转 number）", async () => {
+    const key = `${PREFIX}:timestamp`
+    const ts = 1_765_333_333_333
+    await store.upsert(makeRecord(key, { updatedAt: ts }))
+
+    // DB 层：Prisma BigInt 列返回 JS bigint（int8 承载 epoch ms，int4 装不下）
+    const row = await prisma.sandboxInstance.findUnique({ where: { key } })
+    expect(row?.updatedAt).toBe(BigInt(ts))
+
+    // 契约层：SandboxInstanceStore 出口必须是 number
+    const got = await store.get(key)
+    expect(got?.updatedAt).toBe(ts)
+    expect(typeof got?.updatedAt).toBe("number")
+  })
+
+  it("delete 后 get 返回 null", async () => {
+    const key = `${PREFIX}:deleted`
+    await store.upsert(makeRecord(key))
+    await store.delete(key)
+
+    await expect(store.get(key)).resolves.toBeNull()
+    const row = await prisma.sandboxInstance.findUnique({ where: { key } })
+    expect(row).toBeNull()
+  })
+
+  it("delete 不存在的 key 是 no-op，不抛错", async () => {
+    await expect(store.delete(`${PREFIX}:ghost`)).resolves.toBeUndefined()
+    await expect(store.delete(`${PREFIX}:ghost`)).resolves.toBeUndefined()
+  })
+
+  it("不同 key 互不干扰", async () => {
+    const first = makeRecord(`${PREFIX}:a`, { latestSnapshotId: "snap-a" })
+    const second = makeRecord(`${PREFIX}:b`, { latestRunId: "run-b" })
+
+    await Promise.all([store.upsert(first), store.upsert(second)])
+
+    expect(await store.get(first.key)).toEqual(first)
+    expect(await store.get(second.key)).toEqual(second)
+  })
+})

package/src/server/ai-gateway/sandbox/__tests__/local-process.test.ts

@@ -0,0 +1,316 @@
+// @vitest-environment node
+import { describe, it, expect } from "vitest"
+import os from "node:os"
+import path from "node:path"
+import fs from "node:fs/promises"
+import { localProcessSandbox } from "../local-process"
+
+describe("localProcessSandbox（desktop host 执行）", () => {
+  async function makeRoot(): Promise<string> {
+    return fs.mkdtemp(path.join(os.tmpdir(), "sb-test-"))
+  }
+
+  it("exec 跑命令并回 stdout/exitCode", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      const h = await sb.create({ id: "test-1" })
+      expect(h.id).toBe("test-1")
+      expect(h.provider).toBe("local-process")
+      const r = await h.process.exec("echo hi")
+      expect(r.stdout.trim()).toBe("hi")
+      expect(r.exitCode).toBe(0)
+      expect(r.stderr).toBe("")
+      await sb.destroy({ id: "test-1" })
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it("fs 写读列目录 + mkdir/remove/rename/exists/lstat", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      const h = await sb.create({ id: "fs-1" })
+      await h.fs.write("hello.txt", "hello world")
+      expect(await h.fs.read("hello.txt")).toBe("hello world")
+      expect(await h.fs.readBytes("hello.txt")).toEqual(
+        new TextEncoder().encode("hello world"),
+      )
+      await h.fs.mkdir("sub")
+      await h.fs.write("sub/nested.txt", "n")
+      const list = await h.fs.list(".")
+      const names = list.map((x) => x.name).sort()
+      expect(names).toEqual(["hello.txt", "sub"])
+      expect(list.find((x) => x.name === "sub")?.type).toBe("dir")
+      expect(list.find((x) => x.name === "hello.txt")?.type).toBe("file")
+      const subList = await h.fs.list("sub")
+      expect(subList.map((x) => x.name)).toEqual(["nested.txt"])
+      expect(await h.fs.exists("hello.txt")).toBe(true)
+      expect(await h.fs.exists("missing.txt")).toBe(false)
+      const stat = await h.fs.lstat?.("hello.txt")
+      expect(stat?.type).toBe("file")
+      expect((stat as { size?: number } | undefined)?.size).toBeGreaterThan(0)
+      await h.fs.rename("hello.txt", "renamed.txt")
+      expect(await h.fs.exists("renamed.txt")).toBe(true)
+      expect(await h.fs.exists("hello.txt")).toBe(false)
+      await h.fs.remove("sub")
+      expect(await h.fs.exists("sub")).toBe(false)
+      await h.fs.remove("renamed.txt")
+      expect(await h.fs.exists("renamed.txt")).toBe(false)
+      await sb.destroy({ id: "fs-1" })
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it("capabilities() 如实声明 + name 为 local-process", () => {
+    const sb = localProcessSandbox({ root: "/tmp/x" })
+    expect(sb.name).toBe("local-process")
+    expect(sb.capabilities()).toMatchObject({
+      fs: true,
+      exec: true,
+      env: true,
+      ports: false,
+      backgroundProcesses: true,
+      writableStdin: true,
+      killableProcesses: true,
+      snapshots: false,
+      networkPolicy: false,
+      durableFilesystem: true,
+      fork: false,
+    })
+    expect(sb.restoreSnapshot).toBeUndefined()
+  })
+
+  it("id sanitize 拒绝路径穿越与非法字符，空则回退 UUID", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      await expect(sb.create({ id: "../outside" })).rejects.toThrow()
+      await expect(sb.create({ id: "/abs" })).rejects.toThrow()
+      await expect(sb.create({ id: "a b" })).rejects.toThrow()
+      await expect(sb.create({ id: "a/b" })).rejects.toThrow()
+      await expect(sb.create({ id: "" })).rejects.toThrow()
+      await expect(sb.resume({ id: "../evil" })).rejects.toThrow()
+      const h = await sb.create({})
+      expect(h.id).toMatch(/^[a-zA-Z0-9._:-]+$/)
+      expect(path.isAbsolute(h.workspaceRoot ?? "")).toBe(true)
+      await sb.destroy({ id: h.id })
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it("exec 拒绝逃出 workdir 的 cwd（路径边界）", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      const h = await sb.create({ id: "escape-1" })
+      await expect(h.process.exec("echo hi", { cwd: "../outside" })).rejects.toThrow(
+        /路径越界|越界|escape/,
+      )
+      await expect(h.fs.read("../../etc/passwd")).rejects.toThrow()
+      await expect(h.fs.write("../../evil.txt", "x")).rejects.toThrow()
+      await expect(h.fs.mkdir("../evil-dir")).rejects.toThrow()
+      await expect(h.fs.list("..")).rejects.toThrow()
+      await h.fs.mkdir("sub")
+      const r = await h.process.exec("echo inside", { cwd: "sub" })
+      expect(r.stdout.trim()).toBe("inside")
+      await sb.destroy({ id: "escape-1" })
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it("resume 不存在的沙箱 → null", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      await expect(sb.resume({ id: "never-existed" })).resolves.toBeNull()
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it("resume 存在的沙箱 → 返回 handle（工作目录可恢复）", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      const first = await sb.create({ id: "resume-1" })
+      await first.fs.write("x.txt", "y")
+      const second = await sb.resume({ id: "resume-1" })
+      expect(second?.id).toBe("resume-1")
+      expect(await second?.fs.read("x.txt")).toBe("y")
+      await sb.destroy({ id: "resume-1" })
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it("spawn 后 kill 可终止（killableProcesses=true 兑现）", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      const h = await sb.create({ id: "kill-1" })
+      const proc = await h.process.spawn("sleep 30")
+      expect(proc.pid).toBeGreaterThan(0)
+      await new Promise((r) => setTimeout(r, 300))
+      await proc.kill("SIGTERM")
+      const exitCode = await proc.wait()
+      expect(exitCode).not.toBe(0)
+      expect(exitCode).toBeGreaterThan(128)
+      await sb.destroy({ id: "kill-1" })
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  }, 15_000)
+
+  it("spawn 可读 stdout（AsyncIterable<string>）", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      const h = await sb.create({ id: "spawn-out" })
+      const proc = await h.process.spawn("echo spawned")
+      const chunks: string[] = []
+      for await (const c of proc.stdout) {
+        expect(typeof c).toBe("string")
+        chunks.push(c)
+      }
+      const exitCode = await proc.wait()
+      expect(chunks.join("")).toContain("spawned")
+      expect(exitCode).toBe(0)
+      await sb.destroy({ id: "spawn-out" })
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it("stdin.write 可向进程发送数据", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      const h = await sb.create({ id: "stdin-1" })
+      const proc = await h.process.spawn("cat")
+      await proc.stdin.write("hello stdin\n")
+      await proc.stdin.end()
+      const chunks: string[] = []
+      for await (const c of proc.stdout) chunks.push(c)
+      const exitCode = await proc.wait()
+      expect(chunks.join("")).toContain("hello stdin")
+      expect(exitCode).toBe(0)
+      await sb.destroy({ id: "stdin-1" })
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it("env.set + exec 环境变量生效；per-call env 覆盖 sandbox env", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      const h = await sb.create({ id: "env-1", env: { FOO: "bar" } })
+      await h.env.set({ MYVAR: "hello" })
+      const r1 = await h.process.exec("echo $MYVAR $FOO")
+      expect(r1.stdout.trim()).toBe("hello bar")
+      const r2 = await h.process.exec("echo $FOO", { env: { FOO: "override" } })
+      expect(r2.stdout.trim()).toBe("override")
+      const r3 = await h.process.exec("echo $FOO")
+      expect(r3.stdout.trim()).toBe("bar")
+      await sb.destroy({ id: "env-1" })
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it("exec 失败命令 exitCode 非零 + stderr", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      const h = await sb.create({ id: "fail-1" })
+      const r = await h.process.exec("sh -c 'echo err >&2; exit 3'")
+      expect(r.exitCode).toBe(3)
+      expect(r.stderr).toContain("err")
+      await sb.destroy({ id: "fail-1" })
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it("ports.connect / snapshot / fork / git 显式抛不支持", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      const h = await sb.create({ id: "cap-1" })
+      expect(h.snapshot).toBeUndefined()
+      expect(h.fork).toBeUndefined()
+      await expect(h.ports.connect(3000)).rejects.toThrow(/不支持|unsupported/i)
+      await expect(h.git.status()).rejects.toThrow(/不支持|unsupported/i)
+      await expect(
+        h.git.clone({ url: "http://x" }),
+      ).rejects.toThrow(/不支持|unsupported/i)
+      await sb.destroy({ id: "cap-1" })
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it("AbortSignal 取消 exec", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      const h = await sb.create({ id: "abort-1" })
+      const ac = new AbortController()
+      setTimeout(() => ac.abort(), 200)
+      await expect(
+        h.process.exec("sleep 30", { signal: ac.signal }),
+      ).rejects.toBeDefined()
+      await sb.destroy({ id: "abort-1" })
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  }, 5_000)
+
+  it("AbortSignal 取消 spawn → wait() 非零退出", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      const h = await sb.create({ id: "abort-2" })
+      const ac = new AbortController()
+      setTimeout(() => ac.abort(), 200)
+      const proc = await h.process.spawn("sleep 30", { signal: ac.signal })
+      const exitCode = await proc.wait()
+      expect(exitCode).not.toBe(0)
+      await sb.destroy({ id: "abort-2" })
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  }, 5_000)
+
+  it("destroy 清理 live 状态；resume 后返回 null", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      const h = await sb.create({ id: "del-1" })
+      await h.fs.write("keep.txt", "data")
+      await sb.destroy({ id: "del-1" })
+      expect(await sb.resume({ id: "del-1" })).toBeNull()
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it("workspaceRoot 指向真实工作目录；exec 默认 cwd 落在 workdir 内", async () => {
+    const root = await makeRoot()
+    try {
+      const sb = localProcessSandbox({ root })
+      const h = await sb.create({ id: "cwd-1" })
+      expect(h.workspaceRoot).toBe(path.join(root, "cwd-1"))
+      const r = await h.process.exec("pwd")
+      expect(r.stdout.trim()).toBe(path.join(root, "cwd-1"))
+      await sb.destroy({ id: "cwd-1" })
+    } finally {
+      await fs.rm(root, { recursive: true, force: true })
+    }
+  })
+})