feat: launch and recover OpenCode in a managed container

dries commented

2026-07-18 00:16:43 +02:00

Owner

Parent

What to build

Deliver the first complete optional container-runtime path for one project: select container mode on an owning host, ensure a labeled one-per-project OpenCode container, recover it after an ocman restart, and create same-directory and worktree sessions through its authenticated host-loopback endpoint. Native tmux mode remains the default.

This tracer bullet follows #384: every managed project gets an isolated persistent OpenCode database, and host-wide reads come from the planned API-fed ocman read model. It must not share or bind-mount the host OpenCode database. Project/worktree source mounts may initially retain identical absolute paths rather than adding path translation.

Acceptance criteria

A host-local setting selects native or container OpenCode runtime; remote hosts apply their own setting locally.
The runtime supports the project's documented container engine and reports a clear unavailable capability when it is missing.
Ocman chooses a collision-free host port, publishes it only on 127.0.0.1, and starts OpenCode on a fixed internal port with an externally reachable container bind address.
Managed containers have deterministic labels for ownership, canonical project identity, runtime version, and recovery; correctness does not depend on a container name alone.
Project and ocman worktree paths are mounted read-write at identical absolute paths without mounting unrelated sibling repositories.
A project-scoped persistent OpenCode data volume is created without exposing any host/global OpenCode data directory.
Launch injects authenticated API configuration and the scoped worktree external_directory permission.
Same-directory and worktree session creation, messages, SSE, prompts, autoapprove, and git-visible edits work through the managed endpoint.
Ocman restart recovers healthy labeled containers by runtime inspection; stale records and stopped/broken containers are handled deterministically.
Native and managed container instances cannot both become the selected managed instance for one project.
Failed startup cleans up partial resources and returns actionable diagnostics.
The container pins an exact OpenCode version/image digest; contract/integration tests verify the required API plus runtime arguments, labels, ports, mounts, environment, ensure idempotency, recovery, failure cleanup, and remote owner execution.
The runtime boundary is reflected in architecture documentation.

Blocked by

## Parent #375 ## What to build Deliver the first complete optional container-runtime path for one project: select container mode on an owning host, ensure a labeled one-per-project OpenCode container, recover it after an ocman restart, and create same-directory and worktree sessions through its authenticated host-loopback endpoint. Native tmux mode remains the default. This tracer bullet follows #384: every managed project gets an isolated persistent OpenCode database, and host-wide reads come from the planned API-fed ocman read model. It must not share or bind-mount the host OpenCode database. Project/worktree source mounts may initially retain identical absolute paths rather than adding path translation. ## Acceptance criteria - [ ] A host-local setting selects native or container OpenCode runtime; remote hosts apply their own setting locally. - [ ] The runtime supports the project's documented container engine and reports a clear unavailable capability when it is missing. - [ ] Ocman chooses a collision-free host port, publishes it only on `127.0.0.1`, and starts OpenCode on a fixed internal port with an externally reachable container bind address. - [ ] Managed containers have deterministic labels for ownership, canonical project identity, runtime version, and recovery; correctness does not depend on a container name alone. - [ ] Project and ocman worktree paths are mounted read-write at identical absolute paths without mounting unrelated sibling repositories. - [ ] A project-scoped persistent OpenCode data volume is created without exposing any host/global OpenCode data directory. - [ ] Launch injects authenticated API configuration and the scoped worktree `external_directory` permission. - [ ] Same-directory and worktree session creation, messages, SSE, prompts, autoapprove, and git-visible edits work through the managed endpoint. - [ ] Ocman restart recovers healthy labeled containers by runtime inspection; stale records and stopped/broken containers are handled deterministically. - [ ] Native and managed container instances cannot both become the selected managed instance for one project. - [ ] Failed startup cleans up partial resources and returns actionable diagnostics. - [ ] The container pins an exact OpenCode version/image digest; contract/integration tests verify the required API plus runtime arguments, labels, ports, mounts, environment, ensure idempotency, recovery, failure cleanup, and remote owner execution. - [ ] The runtime boundary is reflected in architecture documentation. ## Blocked by - #376 - #377 - #384