antpath 0.1.0 → 0.1.1

package/references/implementation-plan.md

@@ -1,527 +1,430 @@
----
-title: antpath implementation plan
-status: proposed
-scope: sdk-only MVP
----
-
-# antpath implementation plan
-
-## Goal
-
-Build the SDK-only MVP for antpath with test-first development: a TypeScript SDK that runs code-defined Templates on Claude Managed Agents, using caller-held provider credentials, typed credential inputs, provider-side vaults, queued user messages, event streaming, output downloads, and manual cleanup.
-
-## Acceptance criteria
-
-- A user can define a secret-free Template in TypeScript.
-- A user can create a Client with their provider key.
-- A user can run a Template with typed variables and credentials.
-- The SDK creates all required provider resources per run.
-- The SDK sends queued user messages, one at a time, when the session is idle.
-- The SDK aborts on any provider error or terminated state.
-- The SDK resolves completion as the first idle state after all queued messages are sent.
-- The SDK can stream events, wait for completion, terminate, list files, download a file, download all outputs, read usage, return a final result, and cleanup.
-- The SDK never persists or logs provider keys or MCP credential values.
-- Unit tests cover Template parsing, variable resolution, credential validation, provider request mapping, run state transitions, output handling, and cleanup.
-- Component integration tests cover interactions between SDK modules using fake providers and local fixtures.
-- Recorded API integration tests replay sanitized responses captured from real Claude API calls and are reproducible with scripts.
-- Live e2e tests exercise the real Claude Managed Agents lifecycle and are gated behind local credentials.
-
-## Phase 1: Repository and package foundation
-
-Create the TypeScript package foundation.
-
-Deliverables:
-
-- package manager configuration;
-- TypeScript configuration;
-- lint/format/test commands;
-- source/test directory layout;
-- public package entrypoint;
-- typed error base classes;
-- test fixtures and fake provider harness;
-- four test commands: unit, component integration, recorded API integration, and live e2e;
-- fixture recording/sanitization scripts for real API responses.
-
-Recommended structure:
-
-```text
-src/
-  index.ts
-  client.ts
-  template/
-  credentials/
-  providers/
-    anthropic/
-  run/
-  files/
-  skills/
-  utils/
-test/
-  unit/
-  integration/
-    components/
-    api-recorded/
-    live/
-  fixtures/
-    api-recordings/
-references/
-scripts/
-  record-api-fixtures.ts
-  sanitize-api-fixtures.ts
-```
-
-Validation:
-
-- `npm test` or equivalent test command passes.
-- test commands exist for all four layers.
-- TypeScript build emits declarations.
-
-## Phase 2: Public SDK types
-
-Define the public API before provider implementation.
-
-Deliverables:
-
-- `AntpathClient`;
-- `Template`;
-- `RunOptions`;
-- `RunHandle`;
-- `RunResult`;
-- `RunStatus`;
-- `RunEvent`;
-- `UsageSummary`;
-- `OutputManifest`;
-- `CleanupPolicy`;
-- typed credential unions.
-
-Initial API shape:
-
-```ts
-const client = new AntpathClient({
-  anthropicApiKey: process.env.ANTHROPIC_API_KEY
-});
-
-const template = defineTemplate({
-  name: "example",
-  model: "claude-sonnet-4-6",
-  system: "You are a focused automation agent.",
-  messages: ["Do the task: {{task}}"],
-  variables: {
-    task: string()
-  },
-  mcpServers: {
-    linear: {
-      url: "https://mcp.linear.app/mcp",
-      auth: requiredStaticBearer(),
-      tools: { allow: ["list_issues"] }
-    }
-  },
-  outputs: {
-    recommendedPath: "/antpath/outputs"
-  }
-});
-
-const handle = await client.run(template, {
-  variables: { task: "Summarize open issues" },
-  credentials: {
-    linear: { type: "static_bearer", token: process.env.LINEAR_API_KEY! }
-  }
-});
-
-const result = await handle.wait();
-await handle.downloadOutputs("./outputs");
-await handle.cleanup();
-```
-
-Validation:
-
-- Compile-time tests assert supported and unsupported credential shapes.
-- Runtime schema tests reject invalid Template and run inputs.
-- Public types are defined test-first with type tests before implementation.
-
-## Phase 3: Template compiler
-
-Implement a strict compiler from user Template to resolved, provider-neutral internal configuration.
-
-Deliverables:
-
-- immutable Template snapshot/hash;
-- variable declaration and resolution;
-- escaping for literal placeholders;
-- strict unresolved variable failures;
-- secret boundary enforcement;
-- MCP declaration normalization;
-- tool allow/deny normalization;
-- environment package/setup normalization;
-- output configuration normalization.
-
-Validation:
-
-- unresolved variables fail before provider calls;
-- escaped placeholders remain literal;
-- secrets cannot be supplied through variables;
-- Template hash is stable for semantically identical inputs;
-- Template edits produce a different hash.
-- Recorded fixtures do not include resolved secret values.
-
-## Phase 4: Credential validation
-
-Implement typed credential validation independent of provider calls.
-
-Deliverables:
-
-- `static_bearer` credential type;
-- `oauth_access_token` credential type;
-- Template credential requirements;
-- run-time credential matching by MCP server key;
-- redacted error messages;
-- no credential values in logs/errors/result objects.
-
-Validation:
-
-- missing required credentials fail before provider calls;
-- unsupported arbitrary headers fail with explicit out-of-scope error;
-- credential values are redacted in snapshots, errors, and debug output.
-- redaction is tested in unit, component integration, and recorded API fixture sanitization.
-
-## Phase 5: Anthropic Managed Agents adapter
-
-Build the provider adapter as the only MVP backend.
-
-Deliverables:
-
-- provider client wrapper;
-- create Environment per run;
-- upload local skills/resources;
-- create inline skills where provider supports them;
-- create Agent with model, system prompt, MCP servers, skills, tools, permission policies;
-- create per-run Vault and Credentials;
-- create Session;
-- send user messages;
-- stream/list events;
-- retrieve status/session metadata;
-- terminate session;
-- list/download session-scoped files;
-- retrieve usage/cost where provider exposes it;
-- cleanup created resources.
-
-Provider invariants:
-
-- MCP tools must not reach provider with an approval-required policy.
-- Enabled MCP tools must be explicitly allow/deny configured.
-- Credentials are submitted only to provider vault APIs, never persisted locally beyond active process memory.
-- Created provider IDs are captured for cleanup and debugging.
-
-Validation:
-
-- fake provider tests assert exact request order and payloads;
-- recorded API integration tests assert adapter parsing against sanitized real provider responses;
-- errors from each create step trigger correct cleanup state;
-- cleanup is idempotent where possible;
-- provider IDs are retained even after partial failures.
-
-## Phase 6: Run state machine
-
-Implement deterministic orchestration around provider events.
-
-Deliverables:
-
-- `RunController`;
-- event stream consumer;
-- queued message scheduler;
-- timeout controller;
-- termination controller;
-- local status transitions;
-- final result builder.
-
-State-machine rules:
-
-- Send first message after Session creation.
-- On idle with queued messages remaining, send next message.
-- On idle with no queued messages remaining, succeed.
-- On any provider error, fail and do not send further messages.
-- On terminated, fail unless termination was user-requested.
-- On timeout, terminate and mark timed out.
-
-Validation:
-
-- table-driven tests for event sequences;
-- component integration tests cover event stream plus queued message scheduling;
-- duplicate/replayed events do not corrupt state;
-- queued messages are sent exactly once;
-- abort prevents later queued messages;
-- timeout cannot race into success.
-
-## Phase 7: Run handle API
-
-Expose the MVP handle methods.
-
-Deliverables:
-
-- `status()`;
-- `streamEvents()`;
-- `wait()`;
-- `listFiles()`;
-- `downloadFile()`;
-- `downloadOutputs()`;
-- `cleanup()`;
-- `terminate()`;
-- `usage()`;
-- `result()`.
-
-Behavior:
-
-- `wait()` resolves once the run reaches terminal SDK state.
-- `streamEvents()` yields provider events plus SDK lifecycle events.
-- `downloadOutputs()` downloads all session-scoped files by default.
-- `cleanup()` is manual and can be called after success, failure, or termination.
-- `cleanup()` reports skipped/failed cleanup operations rather than hiding them.
-
-Validation:
-
-- methods have deterministic behavior before, during, and after terminal states;
-- cleanup can be retried safely;
-- file downloads preserve names and avoid unsafe path traversal.
-- live e2e test covers the happy path from Template to cleanup.
-
-## Phase 8: Output download subsystem
-
-Implement local output handling without antpath storage.
-
-Deliverables:
-
-- session-scoped file listing;
-- safe local path mapping;
-- download all files by default;
-- optional filters/globs;
-- optional `/antpath/outputs` convention in prompts/config;
-- local output manifest;
-- checksum/size metadata when feasible.
-
-Validation:
-
-- path traversal filenames are sanitized;
-- duplicate filenames are handled deterministically;
-- partial download failures are reported clearly;
-- downloaded output manifest contains no secrets.
-- recorded API fixtures cover session-scoped file listing and download metadata.
-
-## Phase 9: Skill packaging
-
-Support local uploads and inline skills.
-
-Deliverables:
-
-- local skill path validation;
-- package/zip local skill directory;
-- upload skill artifact/resource per run;
-- inline skill declaration support;
-- variable resolution in skill content/config;
-- skill resource cleanup tracking.
-
-Validation:
-
-- missing local paths fail before provider calls;
-- packaging is deterministic;
-- large/unsupported skill inputs fail with actionable errors;
-- inline and local skills can be combined.
-
-## Phase 10: Cleanup and orphan handling
-
-Implement explicit cleanup as a first-class handle operation.
-
-Deliverables:
-
-- cleanup policy model;
-- manual default;
-- provider resource cleanup ordering;
-- vault/credential cleanup;
-- environment/agent/session/file cleanup where supported;
-- cleanup state reporting;
-- orphan recovery inputs.
-
-Cleanup order should prefer removing credentials first, then optional file/session resources, then Agent/Environment where safe.
-
-Validation:
-
-- cleanup works after success, failure, timeout, and partial provider creation failure;
-- cleanup failures are returned with provider IDs and redacted messages;
-- calling cleanup twice is safe;
-- orphan recovery can accept persisted provider IDs from a previous result.
-- live e2e cleanup verifies provider vault/session/resource cleanup behavior where provider APIs allow it.
-
-## Phase 11: Observability and safe logging
-
-Add structured, redacted observability suitable for SDK users.
-
-Deliverables:
-
-- event hooks/callbacks;
-- debug logger interface;
-- redaction utility;
-- structured SDK lifecycle events;
-- provider request metadata without secrets;
-- error taxonomy.
-
-Validation:
-
-- tests prove secret values are never emitted through logs/events/errors;
-- debug logs include enough provider IDs and state to diagnose failures.
-
-## Phase 12: Documentation and examples
-
-Create user-facing SDK docs and runnable examples.
-
-Deliverables:
-
-- quickstart;
-- Template guide;
-- credentials guide;
-- MCP guide;
-- skills guide;
-- cleanup/orphan guide;
-- output download guide;
-- examples for static bearer and OAuth access-token MCP credentials.
-
-Validation:
-
-- examples compile;
-- docs state MVP non-goals and accepted risks.
-
-## Phase 13: Release readiness
-
-Prepare the SDK for first external use.
-
-Deliverables:
-
-- package metadata;
-- changelog;
-- versioning policy;
-- README;
-- API reference generation if practical;
-- CI workflow once repository hosting is established.
-
-Validation:
-
-- clean install works;
-- build/test pass from a fresh checkout;
-- package dry-run includes only intended files.
-
-## Test strategy
-
-Use test-first development for every phase. Start each feature by adding or updating the narrowest failing test in the appropriate layer, then implement only enough code to pass it.
-
-Use a fake provider for most tests. Do not rely on live provider calls for the core state machine.
-
-### Layer 1: Unit tests
-
-Purpose: verify pure logic and small state transitions with no provider, filesystem, or network dependency.
-
-Coverage:
-
-- Template compiler;
-- variable resolution and escaping;
-- credential parser;
-- redaction utilities;
-- state reducer/state-machine transitions;
-- safe local path mapping;
-- cleanup plan construction.
-
-Command:
-
-```text
-npm run test:unit
-```
-
-### Layer 2: Component integration tests
-
-Purpose: verify interactions between SDK components using fake providers, fake clocks, and local fixtures.
-
-Coverage:
-
-- Client + Template compiler + credential validator;
-- RunController + fake provider event stream;
-- queued message scheduling;
-- output downloader + fake file service;
-- cleanup manager + fake provider resources;
-- logger/event hooks with redaction.
-
-Command:
-
-```text
-npm run test:integration:components
-```
-
-### Layer 3: Recorded API integration tests
-
-Purpose: verify provider adapter behavior against sanitized responses captured from real Claude API calls, without requiring network access during normal CI.
-
-Requirements:
-
-- Real API responses are captured by explicit scripts.
-- Recordings are sanitized before being committed.
-- Secret values, request headers, API keys, bearer tokens, OAuth tokens, and raw sensitive prompts are never stored.
-- Fixtures are deterministic and versioned by provider API/beta header.
-- Tests fail if fixture sanitization leaves secret-shaped values.
-
-Commands:
-
-```text
-npm run fixtures:record:anthropic
-npm run fixtures:sanitize
-npm run test:integration:api
-```
-
-### Layer 4: Live e2e tests
-
-Purpose: verify the full real Claude Managed Agents lifecycle using a local credential.
-
-Coverage:
-
-- create Environment;
-- create Agent;
-- create Vault/Credential when needed;
-- create Session;
-- send queued messages;
-- observe idle completion;
-- list/download session-scoped files;
-- retrieve usage/status where available;
-- terminate if needed;
-- cleanup if configured or explicitly requested.
-
-Rules:
-
-- Live tests are never part of default CI.
-- Live tests require `.env.local` with `ANTHROPIC_API_KEY`.
-- Live tests must use low-cost prompts, strict timeouts, and cleanup guards.
-- Live tests must not print the key or provider auth headers.
-
-Command:
-
-```text
-npm run test:e2e:live
-```
-
-Key invariants:
-
-- no provider call before Template and credentials are fully parsed;
-- no secret value appears in logs, errors, Template snapshots, result objects, or manifests;
-- no secret value appears in recorded API fixtures;
-- every created provider resource is tracked for cleanup;
-- message queue sends each message at most once;
-- cleanup is manual by default and retryable;
-- output download never writes outside the requested local directory.
-
-## Backlog plan
-
-After MVP:
-
-1. Add cloud metadata sync and dashboard.
-2. Add encrypted run-scoped key support for guaranteed cleanup.
-3. Add OpenAI adapter.
-4. Add provider Environment caching by Template hash.
-5. Add cost/token/iteration caps.
-6. Add OAuth refresh credentials.
-7. Add arbitrary MCP headers through an antpath MCP proxy.
-8. Add Template registry and sharing.
-9. Add artifact retention service.
+---
+title: antpath implementation plan
+status: accepted
+scope: platform MVP
+---
+
+# antpath implementation plan
+
+## Goal
+
+Convert antpath from an SDK-only package into a TypeScript workspace containing:
+
+- a platform SDK in `packages/sdk`;
+- a dashboard app in `apps/dashboard`;
+- a worker service in `apps/worker`;
+- shared packages for types, schema, configuration, redaction, and database helpers as needed.
+
+The platform must submit, dispatch, observe, store metadata for, capture outputs from, and clean up Claude Managed Agents runs while preserving tenant isolation and secret boundaries.
+
+Implementation is test-driven. Each behavior starts with the narrowest failing test that proves the desired invariant.
+
+## Acceptance criteria
+
+- The repository is an npm workspace and the current SDK is moved to `packages/sdk`.
+- Dashboard and worker app folders exist with build/test integration.
+- Auth.js authenticates dashboard users.
+- SDK API tokens authenticate programmatic clients.
+- Workspaces are the tenant boundary.
+- BFF/server actions scope every dashboard/API operation by workspace membership or API-token scope.
+- Supabase service-role credentials are never exposed to browser/client bundles.
+- Supabase Postgres stores durable run, attempt, provider resource, event, output, cleanup, usage, workspace, membership, and provider connection metadata.
+- Provider keys are stored encrypted through Supabase Vault and resolved only by trusted server/worker code.
+- Run submission idempotency is enforced by workspace and request hash.
+- Workers claim due runs with leases and `FOR UPDATE SKIP LOCKED`.
+- Multiple workers can run concurrently without duplicate lifecycle ownership.
+- Worker polling recovers from missed `NOTIFY`, worker restart, deploy, and expired leases.
+- Worker creates per-run provider resources and journals them for cleanup.
+- Worker polls provider status and events and stores only redacted metadata.
+- Output capture writes configured files to private Supabase Storage within per-file, per-run, and workspace quotas.
+- BFF returns signed output links only after workspace authorization.
+- Cleanup runs after terminal provider state and output capture.
+- Reconciliation can recover intended provider resources after partial worker crashes.
+- User deletion is pending/soft until cleanup and storage deletion are complete.
+- Exact tier/cap values are configurable through environment variables with conservative defaults and run-level snapshots.
+- Tests follow the accepted taxonomy: deterministic unit tests (including fakes and sanitized recorded snapshots), live external-system integration tests with no skip flags, and top-to-bottom live e2e tests.
+
+## Phase 1: Workspace foundation
+
+Create the workspace structure without changing runtime behavior.
+
+Deliverables:
+
+- Root npm workspace configuration.
+- Current SDK moved to `packages/sdk`.
+- `apps/dashboard` placeholder.
+- `apps/worker` placeholder.
+- Shared TypeScript config/build/test commands.
+- Existing SDK exports preserved or intentionally migrated with compatibility notes.
+- Root validation commands:
+  - `npm run lint`
+  - `npm test`
+  - `npm run build`
+
+TDD gate:
+
+- Add tests or CI command checks proving the moved SDK still builds/tests from the root workspace.
+
+Validation:
+
+- Clean install works from root.
+- Existing SDK tests still pass from root and package scope.
+- Build emits SDK declarations.
+
+## Phase 2: Shared contracts and configuration
+
+Define shared platform contracts before implementing dashboard/worker behavior.
+
+Deliverables:
+
+- Shared run status and cleanup status types.
+- Shared error taxonomy.
+- Shared redaction helpers and secret wrapper.
+- Shared Template/platform submission request schemas.
+- Environment config parser with required-secret validation and conservative defaults.
+- Plan/cap config defaults for:
+  - max run duration;
+  - workspace/user/token concurrency;
+  - polling intervals and jitter;
+  - provider token-bucket rates;
+  - retry backoffs;
+  - lease duration/renewal threshold;
+  - max attempts;
+  - cleanup retries;
+  - output caps;
+  - storage caps;
+  - signed-link TTL;
+  - free user allowance.
+
+TDD gate:
+
+- Unit tests for env parsing, missing required env failure, optional fallback defaults, cap snapshot values, redaction, and status transitions.
+
+Validation:
+
+- Missing required secrets/connectivity config fails service startup.
+- Missing optional config falls back to conservative low limits.
+
+## Phase 3: Database foundation
+
+Create the durable source of truth.
+
+Deliverables:
+
+- Migration framework.
+- Tables:
+  - `users`;
+  - `workspaces`;
+  - `workspace_memberships`;
+  - `api_tokens`;
+  - `provider_connections`;
+  - `runs`;
+  - `run_attempts`;
+  - `provider_resources`;
+  - `run_events`;
+  - `output_objects`;
+  - `cleanup_attempts`;
+  - `usage_ledger`.
+- Constraints:
+  - unique `(workspace_id, idempotency_key)` on runs;
+  - request-hash conflict handling;
+  - unique `(run_attempt_id, provider_event_id)` on events;
+  - foreign keys for workspace and attributed user where practical.
+- DB query helpers for tenant-scoped access.
+
+TDD gate:
+
+- Add failing database/security integration tests for migrations, idempotency, lease claim behavior, event dedupe, usage ledger idempotency, and cross-workspace access denial.
+
+Validation:
+
+- Migrations apply from a clean database.
+- Concurrent claims use `FOR UPDATE SKIP LOCKED`.
+- Event and usage ledger writes are transactional.
+
+## Phase 4: Auth, BFF, and SDK API-token access
+
+Establish the authorization boundary.
+
+Deliverables:
+
+- Auth.js dashboard authentication.
+- User mirror or Auth.js adapter integration.
+- Workspace membership resolution.
+- Workspace switch/active workspace model.
+- Hashed SDK API tokens with scopes, creator, revocation, and last-used tracking.
+- Shared authorization helper for Auth.js sessions and API tokens.
+- BFF/server-action routes for run submission/read/update operations.
+- Browser/client bundle boundary preventing service-role import.
+
+TDD gate:
+
+- Add failing tests for membership-scoped queries, cross-workspace denial, API-token scope enforcement, revoked token rejection, attributed user freezing, and no browser service-role imports.
+
+Validation:
+
+- Dashboard reads and mutates only authorized workspace data.
+- SDK token cannot access another workspace.
+- Service-role credentials are server/worker only.
+
+## Phase 5: Platform SDK client
+
+Turn the SDK into the programmatic client for the platform while preserving Template ergonomics where practical.
+
+Deliverables:
+
+- SDK client for platform API base URL and API token.
+- Submit run API.
+- Get run status/detail API.
+- List metadata events API.
+- List outputs API.
+- Create signed output link API.
+- Cancel run API.
+- Delete run API.
+- Typed errors for auth, quota, validation, conflict, not found, and provider/platform failures.
+- Compatibility path from existing Template definitions to platform submission requests.
+
+TDD gate:
+
+- Type/contract tests for public SDK API and runtime tests with fake platform responses.
+
+Validation:
+
+- SDK never accepts or stores provider keys for platform runs.
+- SDK handles idempotency conflict, unauthorized, quota, and terminal states deterministically.
+
+## Phase 6: Worker claim loop and state machine
+
+Implement durable lifecycle ownership independent of provider details.
+
+Deliverables:
+
+- Polling loop for due runs.
+- Optional Postgres `NOTIFY` listener for fast wakeup.
+- Lease claim/release helpers.
+- Lease-guarded status update helper.
+- Per-workspace/provider-key rate limit hooks.
+- Fair due-run ordering across workspaces.
+- Cancellation/delete request checks before side effects.
+- Timeout handling.
+- Error classification.
+- Retry/backoff scheduling through `next_check_at`.
+
+TDD gate:
+
+- Add failing component and database tests for concurrent fake workers, expired lease reclaim, lease-token update failures, cancellation races, timeout races, and polling fallback after missed `NOTIFY`.
+
+Validation:
+
+- Multiple workers do not process the same run step.
+- Expired leases recover.
+- Worker restart leaves no required in-memory state.
+
+## Phase 7: Fake provider lifecycle harness
+
+Prove worker behavior with deterministic provider boundaries before live provider integration.
+
+Deliverables:
+
+- Fake provider implementing create resources, create session, send event, retrieve status, list events, list files, download file, and cleanup.
+- Fake storage adapter.
+- Fake Vault adapter.
+- Table-driven lifecycle tests.
+
+TDD gate:
+
+- Add component tests for happy path, provider errors, terminal states, duplicate events, output capture, cleanup failures, and retryable failures.
+
+Validation:
+
+- Core run lifecycle is correct without network calls.
+- Duplicate/replayed provider events do not double-count usage.
+
+## Phase 8: Claude provider adapter
+
+Adapt existing Claude Managed Agents provider code for the platform worker.
+
+Deliverables:
+
+- Provider client wrapper for worker.
+- Create Environment per run.
+- Upload skills/resources as needed.
+- Create Agent with model/system/MCP/skills/tool policy.
+- Create provider Vault/Credentials for MCP credentials.
+- Create Session.
+- Send initial user event.
+- Retrieve session status.
+- List session events with cursor/filter where available.
+- List/download session files.
+- Cleanup/archive/delete resources.
+- Provider metadata naming/tagging for reconciliation.
+- Provider error classification.
+
+TDD gate:
+
+- Add sanitized recorded provider snapshot unit tests for parsing and cleanup behavior before live e2e.
+- Verify exact Claude events pagination/filter semantics and document bounded fallback if needed.
+
+Validation:
+
+- No approval-required tool policy reaches the provider.
+- Provider IDs are persisted for cleanup.
+- Sanitized fixtures contain no secrets.
+
+## Phase 9: Provider resource journaling and reconciliation sweeper
+
+Close resource leak windows.
+
+Deliverables:
+
+- Pre-insert intended `provider_resources` rows before provider side effects where possible.
+- Deterministic provider names/metadata with antpath workspace/run/attempt identifiers.
+- Sweeper for expired leases and unfinished intended resources.
+- Orphan matching by provider list/search APIs where available.
+- Reschedule recoverable runs.
+- Cleanup orphaned resources.
+
+TDD gate:
+
+- Add tests that simulate worker crashes after provider create succeeds but before provider id persistence.
+
+Validation:
+
+- Sweeper can attach or cleanup recoverable resources.
+- Cleanup remains idempotent after partial failures.
+
+## Phase 10: Output capture and Supabase Storage
+
+Capture configured outputs safely.
+
+Deliverables:
+
+- Output policy from Template/run request.
+- Provider file metadata inspection.
+- Per-file and per-run caps.
+- Streaming download with hard byte cap and abort.
+- Private Supabase Storage upload.
+- Deterministic plus unguessable storage path policy if required.
+- `output_objects` metadata.
+- Workspace storage quota accounting.
+- Per-user attribution from run row.
+- Signed-link BFF action/API.
+
+TDD gate:
+
+- Add failing tests for quota checks before download, unknown-size streaming caps, storage metadata, signed-link authorization, and cross-workspace denial.
+
+Validation:
+
+- Oversized outputs do not OOM the worker.
+- BFF only creates signed links for authorized workspace users/tokens.
+
+## Phase 11: Cleanup, deletion, and retention
+
+Make cleanup and deletion first-class state machines.
+
+Deliverables:
+
+- Cleanup ordering:
+  - provider credentials/vaults;
+  - session files/session where supported;
+  - agent/archive;
+  - environment/archive/delete;
+  - uploaded provider file resources;
+  - local storage only on user deletion.
+- Cleanup retry/backoff.
+- `cleanup_attempts` records.
+- Cleanup state separate from user-facing run terminal state.
+- User `pending_delete` flow.
+- Workspace deletion flow.
+- Provider key revocation behavior.
+
+TDD gate:
+
+- Add tests for cleanup after success, failure, timeout, cancellation, partial provider creation, duplicate cleanup calls, key revocation, and pending-delete races.
+
+Validation:
+
+- Cleanup failures surface actionable redacted errors.
+- Hard deletion only happens after cleanup/storage deletion succeeds.
+
+## Phase 12: Minimal dashboard
+
+Build the tenant-scoped monitoring surface.
+
+Deliverables:
+
+- Sign-in/out.
+- Workspace switcher.
+- Runs list.
+- Run detail page.
+- Status, timestamps, attributed user, template hash, provider IDs where safe, usage, cleanup state, and redacted metadata events.
+- Output list and signed-link actions.
+- Cancel/delete actions.
+- Quota/cap warnings.
+
+TDD gate:
+
+- Add component or integration tests for tenant-scoped data loading through BFF only and role/scope behavior for actions.
+
+Validation:
+
+- Dashboard cannot read another workspace's runs or outputs.
+- Dashboard displays cleanup retry/failure separately from run success/failure.
+
+## Phase 13: Observability and operations
+
+Make the platform operable for future agents.
+
+Deliverables:
+
+- Structured worker logs.
+- Redacted error reporting.
+- Run lifecycle metrics.
+- Worker health endpoint.
+- Queue depth/due run metrics.
+- Cleanup retry/dead-letter visibility.
+- Reconciliation summary logs.
+- Admin-only recovery tools if needed.
+
+TDD gate:
+
+- Add tests proving logs/events/errors cannot serialize secret wrappers and include enough non-secret identifiers for diagnosis.
+
+Validation:
+
+- Worker `/health` reports readiness.
+- Operational traces include run id, workspace id, phase, attempt id, provider resource ids where safe, and cleanup status.
+
+## Phase 14: Live-gated e2e and release readiness
+
+Verify the complete lifecycle only when credentials are intentionally present.
+
+Deliverables:
+
+- Live e2e command guarded by explicit env flag.
+- Low-cost Claude Managed Agents fixture Template.
+- Cleanup in `finally`.
+- Release/readiness docs.
+- Updated README and examples for platform SDK usage.
+
+TDD gate:
+
+- Live e2e is not a TDD driver for core logic, but must prove final integration before release.
+
+Validation:
+
+- Full submit -> provider session -> metadata poll -> output capture -> signed link -> cleanup works.
+- Default `npm run lint`, `npm test`, and `npm run build` pass.
+
+## Backlog
+
+- Provider webhooks as wakeup/reconciliation accelerator.
+- SSE live event stream for richer dashboard UI.
+- Supabase Realtime with explicit Auth.js-to-Supabase authorization design.
+- Agent/Environment caching by Template/config hash.
+- Additional provider adapters.
+- Runtime human approval flow if product scope changes.
+- Advanced billing and plan management.
+- Cloud Template registry.
+- Curated MCP adapter catalog.