suaveplan/openspec/archive/2026-05-27-api-sandbox-vm-host-bridge/tasks.md

Tasks — Sandbox VM Host Bridge

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work
• 0.2 If any worktrees exist under .claude/worktrees/, account for each
• 0.3 Confirm MANIFEST.md package count matches find packages -maxdepth 3 -name package.json
• 0.4 §0a Sync: worktree-isolated agents fast-forward to orchestrator-supplied SHA

1. New shared types in api-types

• 1.1 packages/api-stack/api/api-types/src/sandbox-bridge/sandbox-bridge.types.ts — SerializedRequest, SerializedResponse, SerializedHeaders, SerializedPrincipal, SerializedTenant. Zero runtime.
• 1.2 Sibling .md, index.ts, .test.ts.
• 1.3 ./sandbox-bridge subpath added to api-types package.json exports.

2. Bridge package scaffold

• 2.1 packages/api-stack/api/api-sandbox-vm-host-bridge/ with package.json, tsconfig.lib.json, vite.config.ts, vitest.config.ts, README.md.
• 2.2 Deps: @suaveplan/api-sandbox-vm, @suaveplan/api-host, @suaveplan/api-types, @suaveplan/error, tslib, zod.

3. Implementation (feature folders)

• 3.1 src/bridge/bridge.ts — createSandboxedVmPluginModule({ sandbox, manifest, registry }) factory.
• 3.2 src/marshal/marshal-request.ts — host RequestContext → SerializedRequest.
• 3.3 src/marshal/marshal-response.ts — SerializedResponse → host Response.
• 3.4 src/error-codes/error-codes.ts — 5 SAND_VM_BRIDGE codes + SandboxVmBridgeError with public constructor.
• 3.5 src/lifecycle/lifecycle.ts — start/dispose forwarders with idempotency.
• 3.6 src/route-discovery/route-discovery.ts — bridge.registerRoute capability + registry-capture + non-empty enforcement.
• 3.7 src/instruments/instruments.ts — bridge-level OTel counters (requests-marshalled, marshal-failures, handler-rejections, invocation-duration histogram).
• 3.8 Paired .md per implementation file (≥200 words, 6 sections).

4. Conformance harness

• 4.1 src/testing/vm-host-bridge-conformance/vm-host-bridge-conformance.ts — runVmHostBridgeConformance({ buildBridge }) with 5 invariants.
• 4.2 Sibling .md, .types.ts, .test.ts, index.ts.
• 4.3 Re-export via ./testing subpath.

5. Tests

• 5.1 Real vm-sandbox + bridged-plugin integration test in tests/integration/full-flow.test.ts.
• 5.2 100% istanbul coverage on touched modules.
• 5.3 Public-constructor lint clean.
• 5.4 bunx --bun turbo lint typecheck test:coverage --filter=@suaveplan/api-sandbox-vm-host-bridge green.

6. Archive

• 6.1 Fold delta into openspec/specs/api-sandbox-vm-host-bridge/spec.md.
• 6.2 Move folder → openspec/archive/2026-05-27-api-sandbox-vm-host-bridge/.
• 6.3 Refresh MANIFEST.md.