Backend Deep Dive

Implemented executor

The Fastify app composes config, runtime, storage, metadata, locks, cleanup, runtime manager, workspace sync, and job executor services. Swagger/OpenAPI is registered at /docs; route groups cover health, sessions, execution, and jobs.

JobExecutor performs the key transaction-like sequence:

1. Validate timeout, CPU, and memory limits.
2. Serialize work with a per-session lock.
3. Require the session and create/mark the job running.
4. Acquire or hydrate a runtime lease.
5. Capture a before-manifest.
6. Prepare restricted Python or Bash execution.
7. Run inside the runtime with timeout and environment.
8. Diff workspace changes and persist them.
9. Complete or fail the metadata record.

On failure it attempts to flush workspace changes before recording the job failure.

Runtime manager

SessionRuntimeManager reconciles unknown running sandboxes, stale workspaces, dirty leases, and storage hydration during startup. It treats the workspace as a durable mirror: stage files before execution and persist changed/deleted files after execution.

Planned product backend

The plan calls for a separate Python backend for auth, threads, ownership, presigned URLs, metadata, and stream proxying. That boundary should remain distinct from the executor.