refactor: make OpenCode instance lifecycle runtime-neutral

dries commented

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

Owner

Copy link

Parent

#375

What to build

Make ocman the authoritative owner of each managed project OpenCode instance while preserving native tmux behavior. EnsureProjectOpencode remains the host-local orchestration seam, but launch returns a reachable endpoint and opaque runtime identity instead of requiring a later lsof lookup and tmux-specific result.

This prefactor must correct existing lifecycle gaps: concurrent ensures, manual duplicate launches, stale tmux sessions, health verification, restart routing, and recovery of managed native instances after ocman restarts. Container support is not part of this ticket.

Acceptance criteria

Concurrent ensure calls for one canonical project root launch at most one instance and all callers receive the same healthy endpoint.
Sequential ensure calls reuse the healthy managed instance.
Manual and automatic launch paths cannot create competing managed instances for the same project.
A stale tmux session without a healthy OpenCode API does not suppress relaunch.
Launch reports a reachable endpoint and runtime-neutral instance reference directly; tmux metadata is optional observability data.
Runtime health verifies the expected OpenCode API rather than listener presence alone.
Restart is owner-routed through hostsvc.Host and works for local and remote native instances.
Managed native instances can be recovered after an ocman restart without trusting stale persisted identifiers.
Native tmux mode remains behaviorally compatible for existing users.
Capabilities distinguish OpenCode launch availability from tmux UI availability.
Concurrency, stale-instance, restart, recovery, and duplicate-launch regression tests cover the public seams.
Architecture and one-instance-per-project documentation describe the runtime-neutral lifecycle.

Blocked by

None - can start immediately.

## Parent #375 ## What to build Make ocman the authoritative owner of each managed project OpenCode instance while preserving native tmux behavior. `EnsureProjectOpencode` remains the host-local orchestration seam, but launch returns a reachable endpoint and opaque runtime identity instead of requiring a later `lsof` lookup and tmux-specific result. This prefactor must correct existing lifecycle gaps: concurrent ensures, manual duplicate launches, stale tmux sessions, health verification, restart routing, and recovery of managed native instances after ocman restarts. Container support is not part of this ticket. ## Acceptance criteria - [ ] Concurrent ensure calls for one canonical project root launch at most one instance and all callers receive the same healthy endpoint. - [ ] Sequential ensure calls reuse the healthy managed instance. - [ ] Manual and automatic launch paths cannot create competing managed instances for the same project. - [ ] A stale tmux session without a healthy OpenCode API does not suppress relaunch. - [ ] Launch reports a reachable endpoint and runtime-neutral instance reference directly; tmux metadata is optional observability data. - [ ] Runtime health verifies the expected OpenCode API rather than listener presence alone. - [ ] Restart is owner-routed through `hostsvc.Host` and works for local and remote native instances. - [ ] Managed native instances can be recovered after an ocman restart without trusting stale persisted identifiers. - [ ] Native tmux mode remains behaviorally compatible for existing users. - [ ] Capabilities distinguish OpenCode launch availability from tmux UI availability. - [ ] Concurrency, stale-instance, restart, recovery, and duplicate-launch regression tests cover the public seams. - [ ] Architecture and one-instance-per-project documentation describe the runtime-neutral lifecycle. ## Blocked by None - can start immediately.

dries added the

labels

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

dries referenced this issue

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

feat: launch and recover OpenCode in a managed container #378

dries referenced this issue

2026-07-18 00:18:34 +02:00

epic: optionally run managed OpenCode instances in containers #375

dries referenced this issue

2026-07-19 10:30:55 +02:00

spec: runtime-neutral OpenCode instance lifecycle (#376) #388

dries referenced this issue

2026-07-19 10:32:45 +02:00

ocruntime package + native tmux runtime (#376) #389

dries referenced this issue

2026-07-19 10:33:00 +02:00

reshape ensure seam + hardened lifecycle body (#376) #390

dries referenced this issue

2026-07-19 10:33:09 +02:00

persisted managed-instance registry + probe-on-recovery (#376) #391

dries referenced this issue

2026-07-19 10:33:17 +02:00

RestartProjectOpencode host method + gRPC routing (#376) #392

dries referenced this issue

2026-07-19 10:33:26 +02:00

frontend: gate launch UI on OpencodeLaunch capability (#376) #393

dries referenced this issue

2026-07-19 10:33:34 +02:00

docs: runtime-neutral lifecycle in architecture + one-instance prose (#376) #394

dries referenced this issue from a commit

2026-07-19 15:26:40 +02:00

feat: add ocruntime package with native tmux runtime

dries referenced this issue from a commit

2026-07-19 15:26:40 +02:00

feat: add owner-routed RestartProjectOpencode (#392)

dries referenced this issue from a commit

2026-07-19 15:26:40 +02:00

docs: describe runtime-neutral opencode lifecycle (#394)

dries referenced this issue

2026-07-19 18:57:26 +02:00

fix: route new-session launch through managed opencode lifecycle #396

dries commented

2026-07-20 10:21:48 +02:00

Author

Owner

Copy link

Resolved. The runtime-neutral lifecycle landed on main (squash 39cf7a5, PRs #390–#394) with follow-up fixes #395, #396, #397.

Acceptance criteria:

Concurrent ensures collapse via singleflight to one instance/shared endpoint (TestEnsureProjectOpencode_Concurrent)
Sequential ensures reuse the healthy instance (TestEnsureProjectOpencode_ReusesHealthyInstance)
Manual + automatic launch share the single EnsureProjectOpencode seam
Stale tmux session without a healthy API relaunches (TestEnsureProjectOpencode_StaleRelaunch)
Launch returns a reachable Endpoint + runtime-neutral ocruntime.Instance; tmux is observability metadata
Health is an API probe (GET {endpoint}/config), not listener presence
Owner-routed RestartProjectOpencode works local + remote (restart_test.go, platform_roundtrip_test.go)
Recovery re-probes persisted rows, discards dead ones (managed_opencode table v35, TestEnsureProjectOpencode_RecoversFromStore)
Native tmux mode behaviorally compatible
HostCaps.OpencodeLaunch capability split from Tmux (#393)
Concurrency/stale/restart/recovery/duplicate regression tests cover the seams
Architecture + one-instance-per-project docs updated (#394)

Container support (#375) remains out of scope for this ticket.

Resolved. The runtime-neutral lifecycle landed on `main` (squash 39cf7a5, PRs #390–#394) with follow-up fixes #395, #396, #397. Acceptance criteria: - [x] Concurrent ensures collapse via singleflight to one instance/shared endpoint (TestEnsureProjectOpencode_Concurrent) - [x] Sequential ensures reuse the healthy instance (TestEnsureProjectOpencode_ReusesHealthyInstance) - [x] Manual + automatic launch share the single EnsureProjectOpencode seam - [x] Stale tmux session without a healthy API relaunches (TestEnsureProjectOpencode_StaleRelaunch) - [x] Launch returns a reachable Endpoint + runtime-neutral ocruntime.Instance; tmux is observability metadata - [x] Health is an API probe (GET {endpoint}/config), not listener presence - [x] Owner-routed RestartProjectOpencode works local + remote (restart_test.go, platform_roundtrip_test.go) - [x] Recovery re-probes persisted rows, discards dead ones (managed_opencode table v35, TestEnsureProjectOpencode_RecoversFromStore) - [x] Native tmux mode behaviorally compatible - [x] HostCaps.OpencodeLaunch capability split from Tmux (#393) - [x] Concurrency/stale/restart/recovery/duplicate regression tests cover the seams - [x] Architecture + one-instance-per-project docs updated (#394) Container support (#375) remains out of scope for this ticket.

dries closed this issue

2026-07-20 10:21:53 +02:00

No Branch/Tag specified