SPIKE: run standalone vm-agent in Cloudflare Sandbox

[simple-agent-manager]

Summary

Productionizes the Cloudflare Container instant-session path in PR #1544 while keeping the PR draft-only for human staging review.

This branch turns the proven spike into the user-facing flow:

• Adds runtime (vm or cf-container) to agent profiles and skills, including D1 migration 0089 and shared API/web types.
• Adds runtime resolution so explicit profile runtime wins, the sandbox kill switch disables cf-container, BYO-cloud users stay on VM by default, and zero-config/platform users can get instant cf-container sessions.
• Extracts shared sandbox/container helpers and adds the authenticated POST /api/projects/:projectId/sessions/start instant-session launcher.
• Removes the admin-only cf-vm-agent/start spike launcher.
• Wires the project chat UI to start plain new cf-container chats through the instant-session path, with runtime controls in profile editing and composer messaging.

Draft/merge policy: do not merge. The PR intentionally remains draft and labeled needs-human-review until Raphaël tests or explicitly clears it.

Validation

• pnpm lint
• pnpm typecheck
• pnpm test
• Additional validation run (if applicable)
• If this PR changes candidate selection for a sweep/cron/alarm loop (WHERE clause, status set, join, or equivalent), expected candidate volume and worst-case per-candidate cost are stated in the summary or validation notes (see .claude/rules/47-control-loop-io-budget.md)

Additional validation:

• pnpm build
• pnpm --filter @simple-agent-manager/api exec vitest run tests/unit/cf-container-runtime-contract.test.ts tests/unit/services/agent-profiles.test.ts
• pnpm --filter @simple-agent-manager/web exec vitest run tests/unit/pages/project-chat.test.tsx tests/unit/components/agent-profiles.test.tsx
• pnpm --filter @simple-agent-manager/web exec playwright test tests/playwright/project-chat-composer-audit.spec.ts - 21 tests passed across iPhone SE, iPhone 14, and desktop.
• pnpm quality:observability-noise - no significant log noise detected; D1 subcheck skipped because OBSERVABILITY_DB_ID was not configured, Workers telemetry skipped with 403.

No sweep/cron/alarm candidate-selection behavior was changed; the checked item is N/A because this PR does not add or alter a control-loop candidate query.

Staging Verification (REQUIRED for all code changes - merge-blocking)

All checkboxes below are mandatory for any PR that changes runtime code (.ts, .tsx, .go, etc.). Write N/A: docs-only ONLY if the PR contains zero runtime code changes. See .claude/rules/13-staging-verification.md.

• Staging deployment green - Deploy Staging workflow triggered manually and passed for this branch
• Live app verified via Playwright - logged into app.sammy.party (staging) using test credentials and actively tested the application
• Existing workflows confirmed working - deploy-staging smoke tests passed and the live project chat surface loaded without unexpected console errors during Playwright verification
• New feature/fix verified on staging - a real cf-container instant chat session started, connected, streamed assistant output, persisted transcript rows, and exposed the workspace WebSocket proxy
• Infrastructure verification completed - cf-container virtual node registered, heartbeat confirmed, node/workspace account-map records were running and healthy
• Mobile and desktop verification notes added for UI changes

Staging Verification Evidence

Deploy-staging run 28980055879 passed: deploy job green in 7m38s and smoke-tests green in 2m1s.

Live staging verification used https://api.sammy.party and https://app.sammy.party with the primary Playwright smoke user on project 01KTKXZ4ZZAT6MJFXRW1ZTQ7RB (serverspresentation2025/hono). A temporary explicit cf-container profile 01KX1Y8TRGH01BA0ZXM3ZHBSC7 was created for the test and deleted afterward.

The instant-session API returned 201 in 16,674 ms for session 291d3716-4a74-4158-b744-c825649f326d, workspace 01KX1Y90YX0450Q081DP9MH752, node 01KX1Y90SCV0X04N58V7W65KPR, and ACP session 01KX1Y9A9P2884SAX3TX15DHTX. Runtime decision was { runtime: 'cf-container', reason: 'explicit-cf-container' }.

Measured timings: setup 10,831 ms, install 7,879 ms, agentReady/heartbeat wait 174 ms, workspaceCreate 642 ms, acpSessionCreate 642 ms, acpSessionStart 288 ms.

Browser verification observed the expected notification/session WebSockets plus the workspace ACP proxy WebSocket at wss://ws-01kx1y90yx0450q081dp9mh752.sammy.party/agent/ws?.... A direct browser WebSocket open to the workspace ACP proxy path succeeded in 2,191 ms.

Transcript verification found 4 persisted messages (user, user, assistant, assistant); assistant chunks SA + M_CF_CONTAINER_SMOKE_OK combined to SAM_CF_CONTAINER_SMOKE_OK. The final staging screenshot showed the assistant marker rendered in the live UI.

Account-map verification: node status running, healthStatus healthy, vmLocation cf-container, cloudProvider cloudflare, vmSize standard-1, lastHeartbeatAt 2026-07-08T22:42:25.962Z; workspace status running with populated nodeId.

Evidence was also posted in PR comment #1544 (comment) and appended to SAM idea 01KWY8E8W1J4F3AC3QAETT2RAT.

UI Compliance Checklist (Required for UI changes)

• Mobile-first layout verified
• Accessibility checks completed
• Shared UI components used or exception documented
• Playwright visual audit run locally - mock data scenarios (normal, long text, empty, many items, error, special chars) tested at mobile (375x667) and desktop (1280x800); no horizontal overflow; screenshots in .codex/tmp/playwright-screenshots/ (see .claude/rules/17-ui-visual-testing.md)

UI evidence: tests/playwright/project-chat-composer-audit.spec.ts passed 21 tests across iPhone SE, iPhone 14, and desktop. The live staging chat screenshot for session 291d3716-4a74-4158-b744-c825649f326d showed the streamed assistant marker without layout overlap or console errors.

End-to-End Verification (Required for multi-component changes)

• Data flow traced from user input to final outcome with code path citations (see .claude/rules/10-e2e-verification.md)
• Capability test exercises the complete happy path across system boundaries
• All spec/doc assumptions about existing behavior verified against code (not just "read the code")
• If any gap exists between automated test coverage and full E2E, manual verification steps documented below

Data Flow Trace

• Profile/runtime config flows through D1 migration apps/api/src/db/migrations/0089_agent_profile_runtime.sql, schema/types in apps/api/src/db/schema.ts, shared profile field mapping in apps/api/src/services/profile-fields.ts, profile services in apps/api/src/services/agent-profiles.ts, and web profile controls in apps/web/src/components/agent-profiles/ProfileFormDialog.tsx.
• Runtime selection is centralized in apps/api/src/services/workspace-runtime.ts, combining sandbox availability, explicit profile/skill runtime, and user/platform credential source.
• Web chat launch starts in apps/web/src/hooks/useProjectChatState.ts, calls apps/web/src/lib/api/sessions.ts:startInstantChatSession, and posts to apps/api/src/routes/chat-start.ts.
• apps/api/src/routes/chat-start.ts authenticates project/repo access, resolves runtime, and calls apps/api/src/services/instant-session.ts:launchInstantSession for cf-container sessions.
• apps/api/src/services/instant-session.ts creates the Sandbox, virtual node, workspace, ACP session, and start event, reusing helpers from apps/api/src/services/sandbox.ts and the existing workspace/session/project-data services.
• The live session returns to the existing project chat UI, where session WebSockets and the workspace ACP WebSocket proxy carry streaming assistant output back to the transcript.

Untested Gaps

The complete cf-container happy path was manually verified on staging with a real container, workspace WebSocket proxy, ACP session, and persisted transcript. Automated coverage exercises the runtime contract, agent-profile persistence, API service launch sequencing with mocked boundaries, and web chat/profile UI; Cloudflare Sandbox cold-start behavior remains live-infrastructure-only.

Post-Mortem (Required for bug fix PRs)

N/A: not a bug fix. This is productionization of an existing feasibility spike.

What broke

N/A: not a bug fix.

Root cause

N/A: not a bug fix.

Class of bug

N/A: not a bug fix.

Why it wasn't caught

N/A: not a bug fix.

Process fix included in this PR

N/A: not a bug fix.

Post-mortem file

N/A: not a bug fix.

Specialist Review Evidence (Required for agent-authored PRs)

If local subagents were used during Phase 5, list every reviewer below. Do NOT merge until every row shows PASS or ADDRESSED. If any reviewer could not complete (timeout, workspace killed, error), you MUST add the needs-human-review label and stop - do not self-merge. See .claude/rules/25-review-merge-gate.md.

• All local reviewers completed and findings addressed before merge
• If any reviewer did NOT complete: needs-human-review label added and merge deferred to human

The specialist table is complete. The PR still intentionally has needs-human-review because the user explicitly requested staging-first human testing and no production merge.

Reviewer	Status	Outcome
cloudflare-specialist	PASS	Reviewed D1 migration/runtime/CF container path; no blocking Cloudflare architecture findings after staging verification.
security-auditor	PASS	Auth, project/repo gates, token handling, and secret redaction reviewed; no critical findings.
constitution-validator	PASS	Checked configurable runtime decisions and hardcoded-value risks; no Principle XI blockers.
test-engineer	PASS	Focused API/web coverage plus broad local gates passed; no blocking coverage gaps beyond live Sandbox behavior documented above.
ui-ux-specialist	PASS	Composer/profile UI reviewed with Playwright mobile/desktop visual audit; no blocking UI findings.
task-completion-validator	PASS	Cross-checked task checklist, implementation diff, validation, staging evidence, and draft-PR handoff; PASS for do-not-merge handoff.

Exceptions (If any)

• Scope: PR remains draft and labeled needs-human-review after all agent-side work.
• Rationale: User explicitly asked to test on staging first and not merge to production.
• Expiration: Raphaël completes review/testing and explicitly authorizes clearing the label or merging.

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

N/A: no external API contract was changed. Cloudflare Sandbox/Container behavior had already been validated by the existing spike in this PR; this pass productionized SAM's own API, UI, runtime resolver, and staging verification flow.

Codebase Impact Analysis

Affected paths span apps/api (D1 migration, profile/skill schema, runtime resolver, chat-start route, instant-session and sandbox services), apps/web (chat launch hook, sessions API helper, profile runtime controls, composer runtime messaging), packages/shared profile/runtime types, and task tracking under tasks/active. The change also removes the admin-only cf-container launcher from apps/api/src/routes/admin-sandbox.ts.

Documentation & Specs

Task-tracking documentation was updated in tasks/active/2026-07-08-cf-container-vm-agent-standalone-spike.md with implementation status, validation notes, staging evidence, PR/idea links, and the do-not-merge handoff. No public www documentation was updated because this is a draft PR pending Raphaël's staging review.

Constitution & Risk Check

Checked Constitution Principle XI / no hardcoded values, auth/project-boundary risks, container/runtime gating, migration safety, and UI verification obligations. Main risks are live Cloudflare Sandbox behavior, ephemeral cf-container runtime expectations, and draft human-review gating; those are covered by SANDBOX_ENABLED, explicit runtime resolution tests, staging verification, and the retained needs-human-review label.

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing sam/execute-task-using-skill-2cs1ky (9315ebb) with main (1820a29)}

[simple-agent-manager]

Spike resumed — recovered lost fix + root-caused the real agent-start blocker (2026-07-08)

Picked up where the prior session left off. The prior session's "cannot push" was a misdiagnosis (it inspected the gh/GH_TOKEN app token, which reports push:false and can't hit /user, and concluded pushing was impossible — but git push uses the separate git-credential-sam helper, which works; this whole branch's commits prove it). Filed idea 01KX0T7WJ3V8583YXAFMT749YM to harden that so agents stop misreading it.

What was actually wrong (and it was NOT the binary)

The recurring Agent start failed: fork/exec /usr/local/bin/claude-agent-acp: no such file or directory was misleading. Go's forkExec runs chdir(cmd.Dir) before execve; a missing working directory fails with ENOENT, and Go reports it against cmd.Path (the binary) even though the binary is fine.

Root cause: deriveContainerWorkDirForRepo() returns /workspaces/<repo> (devcontainer convention). In docker/devcontainer mode the devcontainer CLI creates that path; in standalone (cf-container) mode nothing does, so /workspaces/hono never exists. Proven in the live container:

cd /workspace && /usr/local/bin/claude-agent-acp --version   -> RUNS_from_/workspace
cd /workspaces/hono                                           -> No such file or directory

The binary always existed, was valid (#!/usr/bin/env node, node present), and ran fine from an existing cwd. Two of my earlier attempts (an ENOENT retry, and pre-baking the adapter into the image) treated the wrong layer — the retry was reverted; the image-bake was kept only as a launch-time optimization (already-installed fast path).

The fix

startLocalProcess now MkdirAlls the work dir before exec (standalone owns the local filesystem; LocalLauncher only; docker path unchanged). Regression test added: a not-yet-created nested work dir is created and the process runs in it.

Verified on staging (new binary, fresh cf-container launch)

• Standalone vm-agent boots in CF Sandbox, migrations, virtual cf-container node register + heartbeats (D1: node running, agent_ready_at + last_heartbeat_at set).
• Launch timings (claude-code): setup ~9.2s, vm-agent install ~6.6s, agent-ready ~0.15s, workspace-create ~0.9s, ACP create ~0.2s, ACP start ~0.3s, HTTP 200 in ~11s.
• Agent now STARTS and RUNS (the whole point): ACP local agent process started, command=claude-agent-acp, pid=151 — no ENOENT. It generated output: 3 messages queued in the vm-agent outbox.

Final remaining blocker (narrow, control-plane wiring)

The agent's 3 generated messages don't reach the chat because the standalone message reporter has no auth token:

messagereport: send batch failed  error="no auth token"  count:3

workspaceCallbackToken(workspaceID) returns the workspace runtime's CallbackToken, but in the standalone cf-vm-agent/start flow the per-workspace message reporter is never handed the workspace callback token (empty, not a 401). This is a distinct standalone callback-auth wiring gap (cf. rule 34) — the next fix. Once the reporter is given the workspace callback token (and setTokenAllReporters is triggered after createWorkspaceOnNode), the agent's messages should persist to the chat session and the full transcript will land.

Commits on this branch

• 0feca6eac recover lost 717d78e99 (local ACP adapter install) — verified working
• 5ee0f7ea9 pre-bake claude-agent-acp into sandbox image (optimization)
• 190d83ce3 revert the misdiagnosed ENOENT-retry
• 82272ca5c real fix: create standalone ACP work dir before exec + regression test

Still draft / needs-human-review. WS-proxy RTT through the container DO was already measured by the prior session (~39ms round-trip once open). Next: fix the message-reporter token, then capture the full chat transcript.

[simple-agent-manager]

✅ Full stack working end-to-end (2026-07-08)

A standalone vm-agent in a Cloudflare Container now completes a real chat session with tool calls and working git credentials. Verified on staging with a fresh cf-container launch:

Prompt: "Run: git ls-remote --heads https://github.com/serverspresentation2025/hono.git — then reply with how many remote branches there are and list their short names."

Result (persisted to the chat session, 13 messages):

• Agent used the Bash tool (tool_use + tool_result persisted)
• git ls-remote authenticated and succeeded, returning real refs:
  • refs/heads/main
  • refs/heads/sam/build-tiny-static-project-01kqr4
  • refs/heads/sam/continue-project-small-follow-01kqr4
• Agent replied: "There are 3 remote branches: main, sam/build-tiny-static-project-01kqr4, sam/continue-project-small-follow-01kqr4"
• Workspace status running, no error.

Four control-plane/wiring gaps fixed to get here (each surfaced only after the previous)

1. Message reporter had no auth token (server.go) — the boot-time reporter is created before the workspace callback token exists, and standalone mode skips bootstrap's setTokenAllReporters, so getOrCreateReporter's fast path returned a tokenless reporter → "no auth token" → chat never persisted. Now refreshes the token from the workspace runtime on access.
2. git-token 404 (admin-sandbox.ts) — the spike workspace was inserted without installationId, so /:id/git-token returned 404 "Workspace has no GitHub installation". Now inherits the project's installation.
3. Workspace marked error by node-ready re-dispatch (node-lifecycle.ts) — when the cf-container node reported ready, the node-ready handler re-dispatched the pending workspace via createWorkspaceOnNode without lightweight, hitting a 409 profile conflict with the boot runtime (lightweight=true) and marking the workspace error → the messages endpoint then rejected output with "Workspace is error, not active". Now excludes vm_location='cf-container' from re-dispatch.
4. No git credential helper in standalone (standalone_git.go, main.go) — the per-session GH_TOKEN is injected into the agent env, but git had no credential helper (bootstrap's setup is skipped and targets docker-host addresses), so git ls-remote prompted for a username and failed. Now installs a GitHub-scoped git-credential-sam that serves GH_TOKEN and registers it via git config --system. Behavioral tests included.

Plus the earlier agent-start fix (82272ca5c, create the standalone work dir before exec) and the recovered adapter-install fix (0feca6eac).

Full commit list on this branch

• 0feca6eac recover lost 717d78e99 (local ACP adapter install)
• 5ee0f7ea9 pre-bake claude-agent-acp into sandbox image (optimization)
• 190d83ce3 revert misdiagnosed ENOENT-retry
• 82272ca5c create standalone ACP work dir before exec (real agent-start fix)
• b0b06313a standalone message reporter token
• b1829b133 workspace installationId for git-token
• 4be52e11e don't re-dispatch cf-container workspaces on node-ready
• 46333c5c5 standalone git credential helper

Still draft / needs-human-review per the spike instructions. The core feasibility question (standalone vm-agent → register → heartbeat → full chat with tools + git, WS proxied through the container DO) is now answered YES.

[simple-agent-manager]

CF container productionized-path validation - 2026-07-08

Branch sam/execute-task-using-skill-2cs1ky is pushed through 9315ebbf0.

Commit summary:

• 59ef1607b is the last main implementation/test commit for the productionized cf-container path.
• aede0760a records the final task/staging evidence.
• 9315ebbf0 hardens standalone command paths for SonarCloud by using fixed /usr/bin/git and /bin/sh paths instead of resolving through mutable PATH.

Local gates passed after the productionized runtime wiring:

• pnpm test
• pnpm typecheck
• pnpm lint (existing warning backlog only)
• pnpm build
• focused API/web tests and Playwright composer audit

Additional post-Sonar hardening validation:

• GITHUB_EVENT_NAME=pull_request GITHUB_EVENT_PATH=/tmp/pr1544-event.json pnpm quality:preflight passed against the updated PR body.
• cd packages/vm-agent && PATH="/tmp/go1.25.0/bin:$PATH" go test ./internal/server -run "TestStandaloneGitCredentialHelper" passed.
• cd packages/vm-agent && PATH="/tmp/go1.25.0/bin:$PATH" go test ./internal/acp passed.
• Broad go test ./internal/server ./internal/acp compiled the server package but hit an unrelated Docker-dependent server test because Docker is unavailable in this workspace; the touched server test and full acp package passed.

Specialist review summary:

• Cloudflare/security/constitution/test/UI reviews found no local blockers.
• Task-completion validation is PASS for the requested draft-PR handoff after staging verification.
• quality:specialist-review is expected to fail while the PR has needs-human-review; that label is intentionally retained because Raphaël asked to test staging first and not merge to production.

Staging verification:

• Deploy workflow 28980055879 passed: deploy job 7m38s with health check; smoke-tests 2m1s.
• Live API/browser verification used https://api.sammy.party and https://app.sammy.party.
• POST /api/projects/01KTKXZ4ZZAT6MJFXRW1ZTQ7RB/sessions/start returned 201 in 16,674 ms with { runtime: 'cf-container', reason: 'explicit-cf-container' }.
• Session 291d3716-4a74-4158-b744-c825649f326d; workspace 01KX1Y90YX0450Q081DP9MH752; virtual node 01KX1Y90SCV0X04N58V7W65KPR; ACP session 01KX1Y9A9P2884SAX3TX15DHTX.
• Timings: setup 10,831 ms; install 7,879 ms; agent-ready/heartbeat wait 174 ms; workspace create 642 ms; ACP session create 642 ms; ACP session start 288 ms.
• Account-map verification showed virtual node running / healthy, vmLocation='cf-container', cloudProvider='cloudflare', vmSize='standard-1', heartbeat 2026-07-08T22:42:25.962Z, and workspace nodeId populated.
• Browser verification loaded the live chat with no unexpected console errors and rendered assistant marker SAM_CF_CONTAINER_SMOKE_OK.
• Browser observed notification, ProjectData session, and workspace ACP sockets. Direct browser open to wss://ws-01kx1y90yx0450q081dp9mh752.sammy.party/agent/ws?... succeeded in 2,191 ms.
• Transcript persisted 4 messages (user, user, assistant, assistant); assistant chunks combined to SAM_CF_CONTAINER_SMOKE_OK.
• pnpm quality:observability-noise completed with no significant noise detected; D1 subcheck skipped because OBSERVABILITY_DB_ID was unset and Workers telemetry skipped with API 403.

The same staging evidence was appended to SAM idea 01KWY8E8W1J4F3AC3QAETT2RAT.

Per the spike constraint, this PR remains draft, labeled needs-human-review, and unmerged.

[sonarqubecloud]

Quality Gate passed

Issues
19 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
3.0% Duplication on New Code

See analysis details on SonarQube Cloud