feat(cli): agentworkforce agent --mode sandbox (SPEC scaffold)

[khaliqgant]

Adds the workforce side of interactive persona sandbox sessions per SPEC.md.

Opened as a draft — the workforce-side scaffold is complete and its own tests pass, but production interactive launch depends on published Relay SDK exports (@agent-relay/sdk/fleet, @agent-relay/sdk/attach) that are not yet released. The lazy dependency boundary throws an actionable error at runtime until upstream ships, and no shell fallback or fabricated version bump was introduced.

Summary

• personaToSandboxParams — pure function in packages/persona-kit, deterministic error snapshots
• launchInteractiveSandbox — socket-backed interactive launcher in packages/deploy with detach/stop lifecycle handling
• sandbox-shared.ts — extracted mint/mount/teardown so handler-mode and interactive-mode share auth resolution and idempotent cleanup
• CLI: `--mode local | sandbox`, plus `--byo-sandbox`, `--sandbox-provider`, `--sandbox-id`, `--attach-mode`
• Deploy: `dev` mode renamed to `local` with a deprecated `dev` alias for one release
• Repo-wide `no-agent-relay-shell` guard so nothing in workforce packages shells out to `agent-relay`

Validation (from `impl/validation.md`)

• `pnpm install / build / typecheck / lint` — all green
• Persona mapper: 11 tests pass
• Deploy suite: 292 passed, 1 skipped (opt-in live Daytona smoke) — includes real UNIX-socket byte piping, attach timing, stop/detach, cleanup errors
• Local-surface: 14 pass
• CLI parser/dispatch/runtime-picker: 127 pass
• Root `no-agent-relay-shell` scan: passes
• Pre-existing failures unrelated to this diff: 14 runtime tests need Node ≥26.3.1 (host is 22), 30 existing CLI invocation/permission tests, existing broker-log tests

Blockers before merge (from `impl/upstream-blockers.md`)

1. Relay SDK subpaths. `@agent-relay/sdk@12.1.0` does not export `./fleet` or `./attach`. Upstream Relay PR must publish these, and consumers here must bump.
2. `FleetNodeAttachProxy` shape. Upstream currently exposes `brokerUrl`, `apiKey`, `requestTimeoutMs`, `close()` — not the `socketPath` / `finished` contract this PR consumes. Relay needs to supply the terminal-to-UNIX-socket adapter, harness exec/exit handling, and the fleet-spawn wrapper.
3. Cloud `readonlyPaths` enforcement. Cloud must accept and enforce `readonlyPaths` with chmod-444 semantics. Forwarding paths in contract tests does not prove live enforcement; needs the extended `1630-scoped-relayfile-sandbox-mount` roundtrip.
4. Full-repo test gate. Passes for this diff's tests. Pre-existing failures under Node 22 need triage separately.

Before rollout: publish Relay's exports and request/response types, bump workforce consumers, run the live 1630 roundtrip, pass the opt-in Daytona smoke.

Provenance

Written by `codex` (gpt-6-astra) under the `wire-up-sandbox-session` v1 relayflow at `AgentWorkforce/relayflows/examples/wire-up-sandbox-session/wire-up.workflow.ts`. Planner was `claude-sonnet-5`. The flow's `tests` gate correctly failed closed on real test regressions and auto-triggered a repair pass before the host OS ran out of memory mid-repair; the subsequent `critique` (claude-opus-5) and `open-pr` steps did not run. This PR was opened manually after reviewing Codex's own `impl/summary.md`, `impl/validation.md`, and `impl/upstream-blockers.md`.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UDeYnpfKVNvep3SuokVobP

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}