Spike OpenShell integration and select the correct Forge boundary

[eshulman2]

Problem

OpenShell may provide useful filesystem, process, egress, and model-credential controls, but its gateway and compute-driver architecture does not necessarily map cleanly to Forge's SandboxDriver, which currently represents direct execution via Podman or Kubernetes.

Committing to an OpenShellDriver before validating lifecycle, workspace, review polling, cancellation, credential, and deployment behavior could create a second orchestration layer or duplicate OpenShell's own compute abstraction. OpenShell is also currently alpha.

Goal

Run a time-boxed integration spike and select the correct Forge integration boundary before committing to production implementation.

Questions to answer

• Should OpenShell be a SandboxDriver, a service used by ContainerRunner, or the runtime underneath a driver?
• Can Forge's existing container image and entrypoint run unchanged?
• How are the live workspace and .forge review-cycle files synchronized?
• Can timeout, cancellation, cleanup, and orphan recovery meet Forge semantics?
• Can model credentials be mediated for every Forge backend without entering the agent environment?
• How does OpenShell deploy with local Podman and production Kubernetes/OpenShift?
• Which capabilities are enforced versus merely configured, and how can Forge verify them?
• What operational dependency, availability, versioning, and upgrade risks follow from alpha status?

Spike deliverables

• one end-to-end Forge implementation task through OpenShell
• an architecture decision record comparing the three integration options
• a minimal default-deny policy for inference and required package access
• observed behavior for workspace changes, review-cycle polling, logs, timeout, cancellation, and cleanup
• credential visibility test from inside the sandbox
• recommendation: adopt, defer, or reject, with production-readiness gaps
• follow-up implementation issues based on the chosen boundary

Acceptance criteria

• The spike uses a real OpenShell environment, not only mocks.
• No production driver is added until the ADR selects the integration boundary.
• Results distinguish OpenShell guarantees from Forge-owned validation.
• Podman and Kubernetes remain supported regardless of the recommendation.
• OpenShell's alpha status and operational risks are recorded explicitly.

Dependencies

• Make sandbox runner pluggable with different execution drivers #30 / PR Make sandbox runner pluggable with Kubernetes driver support #243 is useful for comparison but the spike may begin independently.
• Define sandbox driver capabilities and execution requirements #265 defines the minimal driver capability vocabulary.

Estimate

AI-assisted: 3–5 engineering days for the spike and ADR. Production implementation is estimated afterward.