Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
OpenCode on Runtime Generations: Adapter Design
Status: implemented on the core contract at 32f655d2e. The sections below
are the Phase 1 design. Their line references are to
refactor/runtime-generations at 1eec27fab.
How the implementation differs from the Phase 1 design
- The adapter's generation set is
OpenCodeRuntimeinclient_manager.py. - The core has no idle hook.
stop(generation, force)declines a graceful stop while the process still has requests in flight or native run markers. The set then retries it on the next release or sweep. - Leases are core bindings plus an adapter timer. Their expiry is persisted in the generation record. A release is routed by lease id to the runtime holding the lease, even after a disabled backend's agent was unregistered while that lease drains. Only a lease that no runtime has adopted yet goes to the registered agent, which adopts it first. Each lease's TTL covers the longest its holder may legitimately need. For the provider probe, that is the directory-bootstrap ceiling plus the probe's own timeout.
- Adoption keeps the newest adopted generation whose recorded digest equals the current spec as current. Every other adopted generation retires and stops once its restored work drains.
renew_runtime(config, config_save=True)renews nothing. Everyagents.opencodefield is read per turn except the CLI path, and the CLI path's binary identity is already a spec input. Credential flows, manual Restart, and installs bump the renewal epoch.- A forced refresh cancels running work and retires every generation. This is the coordinator's interrupt path, kept until it is deleted.
- Adoption skips generations that a runtime of this controller process is
starting or has attached. Those belong to the runtime of an OpenCode backend
that was disabled and enabled again, and that runtime stops them itself. The
process keeps this ownership in memory, marking an adopted generation only
once a runtime attaches it, so an adoption cut short leaves the rest to its
retry. The record has no
owner_pid, and adoption writes nothing except the conversion of a legacy record. Adoption applies resource governance to each adopted generation, as a start does. - Disabling OpenCode is the user's own interruption (owner decision,
2026-10-03). The core interrupts the backend's turns and Activities with the
disabled notice, unregisters the agent, and awaits
shutdown_runtime(settle_reason="backend_disabled"). That call stops every generation at once with a forcedstop_all, and each forced stop settles the work bound to its process with that reason. The core's backend-wide interrupt is only the fast path: it may fail, and a retry after OpenCode is enabled again skips it, so the adapter's own settlement is the guaranteed one. A turn that raced the disable fails with the localizederror.agentRuntimeRetired. Re-enabling builds a new agent. Every other configuration change still renews in place without interrupting anything. - A controller that starts with OpenCode disabled stops the servers a crashed
controller recorded, through
stop_recorded_servers_sync(), the same function asvibe stop. It honors ownership here, process identity, and the desktop foreign-Runtime refusal. Their durable polls stay durable until OpenCode is enabled again. - A UI lease release reaches the runtime holding the lease, even after its agent was unregistered, or else the registered agent, which adopts first.
- Explicit shutdown stops only the generations a runtime of this controller
started or adopted (
stop_owned_generations_sync()). Another desktop Runtime's generations, sharing this state directory, keep running. - Bindings, and so leases, count as active runtime work, so maintenance such as a CLI replacement waits for a leased sequence between its requests.
- Work outside a turn (
current_server()and UI leases) is admitted the way a turn is. It waits while a native migration drains the backend, and counts as active until it is bound. - A restored poll bound to a generation other than the one it names is rewritten to name the generation it is bound to.
- See section 12 for the lifecycle invariants and the audit.
- A record that cannot be parsed is kept and never counted as dead. Its process may still run on a port that nothing else records.
- A failed record write never leaves a record protecting less than its process runs. A run marker or lease is persisted before its work starts. A turn clears its run marker together with its durable poll, so when the write fails both stay and a later restore retries. Any other change that only releases protection takes effect at once. If its write fails, the record stays stale until the next sweep rewrites it. A crash before that sweep only keeps the process until the stale lease expires, or until adoption drops a marker that no durable poll backs.
vibe stopforgets every record whose process already ended, with its overlay copy, as shutdown and adoption do.- The renewal epoch is persisted under
runtime/opencode/renew_epoch. A generation retired by a renewal therefore never serves again after a crash. - Readiness and adoption accept a listener that is the spawned process or one
of its descendants, as with npm shims and Windows
.cmdwrappers. - The two-version gate in section 11 passed (RUNTIME-GEN-OBS-020), so a version change can coexist.
- Status, abort, and prompts are confirmed to be per process (RUNTIME-GEN-OBS-021).
Worked example
A user replaces the openrouter API key in Settings while session S1 runs a
long OpenCode turn on generation G1.
- The save writes
~/.config/opencode/opencode.jsonand signals the controller, which advances the snapshot. Nothing stops. S2sends a message. Its turn computes the launch spec. The user-config digest differs fromG1's, andS1is bound toG1. The core therefore startsG2on a new port (serialized), marksG1retiring, and bindsS2toG2.- Every call for
S2's run goes toG2's port: prompt, status polls, steering, and abort.S1's calls keep going toG1's port. Both processes write the one SQLite database. S1's turn ends. Its run marker is cleared inG1's record and its binding is released.G1is now idle and retiring, so it is stopped: the process tree is killed and the record deleted.S1's next turn binds toG2and continues the same native session from the shared database.
Facts this design relies on
- Verified by the orchestrator: two servers can share one OpenCode home. This
covers the WAL database, cross-server continuation, and concurrent prompts.
Simultaneous fresh starts fail with
database is locked. - Verified here (hermetic probe, OpenCode 1.18.33, temporary
HOMEand XDG directories):opencode serve --port=0listens on the default 4096, not on an ephemeral port. Avibe must choose each port itself. - Verified here: a second
opencode serveon a port that is already taken exits at once withServeError, and the first stays healthy. A health probe on that port right after a spawn can therefore be answered by the other process. - Verified here: on macOS, psutil 7.2.2
Process.net_connections()proves that a same-user process is listening on a port. - From the code: the adapter has no SSE event stream. Live turns and restored
polls poll over HTTP through the server object they are handed
(
agent.py:1869-1881,agent.py:3027,poll_loop.py:922). "Per-generation event streams" therefore means handing each poll its own generation. - Assumed, not probed:
/session/status, abort, andprompt_asyncact on each process's in-memory run state, while sessions and messages live in the shared database. The design does not depend on this, because every call for a live run goes to that run's generation.
1. Objects
OpenCodeServerClient (server.py)
The HTTP surface for one base URL. It holds everything at
server.py:2206-2873:
- directory readiness and sessions;
- prompts, messages, status, and abort;
- catalogs, auth, and OAuth;
- diagnostics and the config readers.
It also holds the loop-aware HTTP session (server.py:516-548). It is built
from base_url, request_timeout_seconds, and model_hub_provider_ids
(which feed _public_opencode_catalog). It owns no process and has no
ensure_running. The UI process uses it directly with a leased URL.
OpenCodeGeneration(OpenCodeServerClient) (server.py)
One opencode serve process. Its state:
- identity:
generation_id,pid,process_created_at,port; - launch:
spec(digest and a non-secret summary),record_path, andcaller_context_path; - work:
active_run_sessions, the in-flight request count, and persisted leases; - the activation
identity; _processwhen this controller started it;- the observed-exit state for resource diagnostics, moved from
server.py:306-380.
Its methods:
mark_run_active/mark_run_inactive: the record read-modify-write fromserver.py:1006-1049and1125-1165, without the overlay-reservation parameter;request_scope: the counter fromserver.py:1051-1061, without the pending-restart branch.
It subclasses the client, so every consumer that takes a "server" keeps working unchanged:
_SteeringAwareOpenCodeServer(agent.py:189-707);- the poll loop;
OpenCodeSessionManager(session.py:212,338,407,448).
OpenCodeGenerations (client_manager.py)
This replaces OpenCodeClientManager (client_manager.py:1-55). It is the
adapter half of the core generation set for the single unit
opencode:instance:
launch_spec(snapshot) -> OpenCodeLaunchSpec(section 5);start_generation(spec) -> OpenCodeGeneration(section 2.3);stop_generation(generation, force)andgeneration_idle(generation)(section 4);can_coexist = True;adopt_recorded()(section 2.2),generation(id), andgenerations().
2. Processes and records
2.1 Generation record
Each record lives at
paths.get_runtime_dir() / "opencode" / "generations" / f"{generation_id}.json"
and is written with write_atomic (mode 0600).
{
"schema": 1,
"generation_id": "ocg_<16 hex>",
"pid": 123,
"process_created_at": 1790000000.12,
"host": "127.0.0.1",
"port": 52123,
"started_at": 1790000000.0,
"spec_digest": "<sha256>",
"binary": {"path": "/abs/opencode", "version": "1.18.33"},
"caller_context_path": "/abs/runtime/opencode_caller_context.json",
"model_hub_overlay_hash": "<sha256> | null",
"model_hub_overlay_provider_ids": ["..."],
"active_run_sessions": ["ses_..."],
"leases": {"lease_id": 1790000960.0}
}
- The record is written right after spawn, as
_write_pid_fileis today (server.py:2052-2056). A crash during start therefore leaves a record that adoption cleans up. - Run-marker and lease changes update it under the generation's own lock.
- It is deleted only after the process is proven gone.
2.2 Adoption after a controller restart
adopt_recorded() runs once, lazily, before whichever comes first of the
first acquire, restore_active_polls, prepare_runtime_restart, or an
ownership snapshot. For each record:
- Prove ownership. The pid is alive, and
runtime.process_create_time(pid)equalsprocess_created_at(today's_pid_file_proves_owned_server,server.py:382-393). The command line isopencode serve ... --port=<port>(server.py:1566-1569). - Check health and the port.
/global/healthanswers on the recorded port, and psutil shows this pid listening on it. This replaces the Linux-only/procwalk atserver.py:1572-1616. - Proven and healthy: adopt it with its recorded spec and attach an
activation identity. Reconcile
active_run_sessionsagainst the durable active polls that name this generation. This generalizesserver.py:735-780. - Proven but unhealthy: terminate its tree (
server.py:1701-1793) and delete the record, as_cleanup_orphaned_managed_serverdoes today (server.py:1833-1846). - Not proven (dead or reused pid): delete the record and never send a signal.
An adopted generation becomes current only when an acquire's desired spec equals its spec. The newest match wins, and every other adopted generation retires.
The released shape is logs/opencode_server.json, which every released
version writes (server.py:1080-1117). Adoption converts a proven, live
legacy server into a record whose spec_digest is "legacy", so it never
becomes current. The record keeps that file's active_run_sessions, and the
legacy file is then deleted.
- Trust follows today's rules for that file: the birth identity when it is
present, otherwise the command line and port, as in
terminate_instance_sync(server.py:2129-2179). - A legacy file with a dead pid is deleted.
- Load fixtures cover each released shape: with and without
process_created_at,caller_context_path, and the overlay fields.
Unrecorded opencode serve processes are never adopted. Today's port scan
(_find_opencode_serve_pids, server.py:1628-1684) exists only because the
port is fixed.
2.3 Starting a generation
start_generation(spec) runs under the core's per-backend start serialization.
The start includes the wait for health, so one start's migration never
overlaps another's.
ensure_plugin_installed()(caller_context.py:128-134).Port. Bind
127.0.0.1:0in Python, read the port, close the socket, and pass--port=<port>. Never pass--port=0.Environment. Use today's launch environment (
server.py:2011-2038):- the desktop role, EXA, and external Skills off;
server_environment()andAVIBE_OPENCODE_MODEL_HUB;- in Hub mode,
OPENCODE_CONFIG_CONTENTfrom the spec's overlay, andOPENCODE_CONFIGpointing at a per-generation copy<generation_id>.overlay.json(mode 0600).
The copy replaces the shared overlay path, because
prepare_opencode_overlayrewrites the shared file for every new overlay (model_hub.py:1281-1291) while older generations still run with that path.Spawn the process, write the record, and apply resource governance (
server.py:1119-1123).Readiness. The generation is ready when
/global/healthis healthy and psutil shows this pid listening on the port. If the process exits first, another process took the port, so pick a new port and retry, up to three attempts. A timeout reaps the process, as atserver.py:2074-2090.Attach the activation identity with
registry.attach("opencode", f"opencode:{generation_id}"). Each generation has its own resource key, so a reused port can never alias an older identity.
When a start fails, OpenCodeGenerations keeps the failed pid.
_resource_failure_for_server (agent.py:987-1037) uses it to attribute the
failure to cgroup pressure, as it does today.
3. Routing
Binding map
OpenCodeAgent._session_generations: dict[str, OpenCodeGeneration] is keyed
by base_session_id.
- Set: when a turn's acquire returns, or when a restored poll resolves its generation.
- Popped: wherever
_active_requestsand the request session are popped (agent.py:1301-1304,3123-3125).
Every session-scoped lookup that today calls _get_server() or
_client_manager._server_manager reads this map instead:
| Call site | Today | New |
|---|---|---|
| Turn start | _get_server(), then configure_model_hub_overlay, then ensure_running (agent.py:1356-1365) |
spec = launch_spec(snapshot), then binding = await generations.acquire(spec), then server = binding.generation |
| Caller-context path | caller_context_binding_path() from the singleton PID file (agent.py:1366, server.py:405-410) |
server.caller_context_path from the record |
| Activation identity | _attach_server_activation (agent.py:887-908) |
server.identity, attached at start or adoption |
| Run marker | Singleton, with an overlay reservation (agent.py:1748-1755) |
server.mark_run_active(session_id) |
| Durable active poll | add_active_poll (agent.py:1760-1779) |
The same call, plus processing_indicator["opencode_generation_id"]. That bag already carries other OpenCode keys, so storage does not change. |
| Prompt and poll | _SteeringAwareOpenCodeServer(server, state) (agent.py:1869) |
Unchanged; server is now the generation |
| Turn end | _retire_active_poll(server, ...) (agent.py:2037-2044, 2086-2100) |
Unchanged, then binding.release() |
| Superseding a running request | _get_server() abort and wait_for_session_idle (agent.py:1266-1274) |
The old task's generation |
| Steering | _client_manager._server_manager (agent.py:2176) |
state.generation, a new _OpenCodeSteerState field set at agent.py:1827 and 2991 |
| Steer reconciliation | Singleton (agent.py:2369) |
The bound generation. Finding a part is a database read, so an unbound session falls back to the current generation. |
/stop and clear_sessions |
_get_server() (agent.py:2478, 2517) |
The generation captured from the map before awaiting the task |
_abort_active_request |
_get_server() (agent.py:2538, 2546) |
The bound generation. With no binding there is no native run, so skip. |
| Restore | _get_server() (agent.py:2635, 2951; poll_loop.py:922) |
The resolved generation, passed explicitly as run_restored_poll_loop(poll_info, server) |
| Activation resolvers | Singleton identity (agent.py:942-964) |
The bound generation's identity, else the current generation's, else None |
Durable active-poll recovery
restore_active_polls (agent.py:2598-2911) resolves each poll's generation
in this order:
- If
processing_indicator["opencode_generation_id"]names an adopted generation, use it. - If the key is missing (the released shape), use the adopted generation
whose
active_run_sessionslists the session. In practice this is the converted legacy record. - Otherwise no live process owns the run. Verification reads use a lease on
the current generation, as a dead server is handled today. The existing
session_still_activelogic then settles the run.
The restored task binds _session_generations, re-marks the run on that
generation (agent.py:2951-2953), and gets
_SteeringAwareOpenCodeServer(generation, state) (agent.py:3027).
Caller context
The binding file stays one file keyed by native session id
(caller_context.py:114, 202-337). That is safe across generations: a
session is active on at most one generation, and unbinding checks a token
(caller_context.py:282-306).
- Each generation launches with
server_environment()and records that path. - A turn uses its own generation's recorded path (
agent.py:1669,2758). - The plugin source digest is a spec input. A plugin change starts a new generation instead of refusing turns.
4. Retire when drained, the cap, and serialized starts
generation_idle(G) uses adapter evidence only. G is idle when all of these
hold:
- it has no live binding (turns, restored polls, or controller-side leases);
- its in-flight request count is zero;
- its
active_run_sessionsis empty after reconciliation; - its record holds no unexpired lease (UI leases, section 6).
A per-generation ownership snapshot would list only the sessions bound to that generation. That list is empty exactly when the conditions above hold, and unbound sessions acquire the current generation, so the snapshot cannot veto retiring a generation.
Exclusive operations still use ownership snapshots.
runtime_ownership_snapshots() (agent.py:1097-1159) returns one target per
generation with that generation's bound sessions. The current generation's
target keeps include_all_backend_sessions=True, so durable work that has not
acquired a generation still blocks migration_guard, as it does today.
stop_generation(G, force):
- Not forced: call
registry.retire_if_current(G.identity, lambda: generation_idle(G)), which replaces the predicate atagent.py:910-940. If it refuses, keepGrunning. Otherwise close the HTTP session, terminate the tree, and delete the record and the overlay copy. - Forced (the cap, migration, or an explicit stop):
- Mark the sessions bound to
Gas interrupted by a runtime update. - Cancel their request tasks with
_cancel_active_requests(agent.py:1225-1253), filtered toG. The cancellation handler then emits the standard runtime-update notice instead of removing the ack silently. This mirrors_user_stopped_sessions(agent.py:765,2118-2123). - Retire the durable polls, terminate the tree, and delete the record.
- Mark the sessions bound to
The core owns the cap of three and the serialized starts. The adapter declares
can_coexist = True.
Other lifecycle cases:
- Backend disabled. The core interrupts the backend's work, unregisters
the agent, and awaits
OpenCodeAgent.shutdown_runtime(settle_reason=...), which stops every generation at once and settles the work bound to each with that reason. - Native migration.
retire_for_native_migration(agent.py:1086-1089,server.py:550-593) strictly stops every generation. It refuses while any generation has requests or runs, and keeps today's ownership proofs. - Controller shutdown.
terminate_all_generations_sync()covers tracked generations and records. It replacesterminate_instance_syncatcontroller.py:2386-2393.
5. Launch spec
OpenCodeLaunchSpec holds digest, binary_path, overlay, and a summary.
Two specs are equal when their digests are equal. The digest is the sha256 of
canonical JSON over these inputs:
| Input | Source | Notes |
|---|---|---|
| Binary identity | resolve_cli_path on the snapshot's agents.opencode.cli_path |
Covers the realpath and (st_dev, st_ino, st_size, st_mtime_ns). Every install writes the file anew, so the stat signature changes on any upgrade or reinstall, including an in-place one. The version (<binary> --version, cached per stat signature) goes into the generation's record only, so the digest stays a pure function of the snapshot. |
| Hub overlay | overlay.content_hash and provider_ids; None in Direct mode |
The same overlay object the turn resolves its model with. A Hub/Direct switch therefore changes the spec. |
| Managed policy | _MANAGED_RUNTIME_POLICY_REVISION (server.py:72) |
A bump now starts a new generation instead of refusing turns. |
| Caller-context plugin | sha256 of PLUGIN_SOURCE |
|
| User config | The global files OpenCode loads: get_opencode_config_paths() plus XDG {config.json, opencode.json, opencode.jsonc} |
Each file contributes its canonical parsed JSON with $schema removed, its raw bytes when it cannot be parsed, or an absence marker. OpenCode may insert $schema on load, and that must not start new generations. |
| Credentials | Normalized auth.json |
Each provider maps to its type, plus its key for api and wellknown entries, plus stable non-secret OAuth identity fields. OAuth access, refresh, and expires are excluded. OpenCode rewrites them whenever it refreshes a token, so a raw digest would start a new generation after every refresh. |
| Renew epoch | The core | Set by manual Restart, and by an Avibe-initiated OAuth success (section 6). |
Snapshot discipline. A turn should load the Model Hub configuration once. Today there are three loads:
turn_mode(agent.py:1348-1355,model_hub.py:931-932);prepare_opencode_overlay(model_hub.py:1177-1178);resolve_opencode_overlay_launch, for unlisted models (model_hub.py:1085).
Proposal: pass the core snapshot's Model Hub configuration into
prepare_opencode_overlay(config) and
resolve_opencode_overlay_launch(overlay, model, config), and derive the turn
mode as direct when the overlay is None, hub otherwise. The overlay
digest and the model resolution then come from one load. model_hub.py is
shared, so this needs core agreement.
One snapshot per launch. _prepare_launch() reads every mutable launch
input in one synchronous step, before its first await. That covers the Model Hub
snapshot, the CLI path, the renewal epoch, the binary identity, and the user
config and credential digests (OpenCodeRuntime.launch_inputs()). The policy
revision and plugin source are constants of the Avibe build. The overlay is
derived from that Hub snapshot, and the spec is a pure function of the
snapshot and the overlay (compute_launch_spec(inputs, overlay)). Turns,
restored polls, current_server(), leases, and adoption all use this one
path. A save or renewal that lands while the overlay is prepared therefore
changes nothing about that launch: it stays on the generation its snapshot
names, starts no spare generation, and the next launch moves. After the
snapshot, only the generation's HTTP request timeout is read live; it is a
client setting, not a process input.
The same snapshot carries the agents.opencode settings object the CLI path
was read from (OpenCodeLaunchInputs.settings). After admission, the turn
reads no live agents.opencode field:
| Read | Disposition |
|---|---|
default_provider and default_reasoning_effort (model resolution in _run_turn) |
taken from the admission settings |
active_turn_timeout_seconds and error_retry_limit (run_prompt_poll) |
taken from the admission settings |
the same two in run_restored_poll_loop |
read once when the restore starts; a restored poll has no earlier admission |
request_timeout_seconds (a generation's HTTP client) |
read when the generation starts; always 60 from to_app_config, not a user setting |
controller.config.language |
not an agents.opencode field |
| channel and scope overrides | out of scope: a recorded follow-up, as for Codex |
Check-to-spawn window. Files are digested before the spawn. If a save lands in between, the generation loads files newer than its label says. The next turn sees the mismatch and starts one more generation. A generation never runs files older than its label.
6. The UI process stops launching servers
Today these UI-process paths call ensure_running:
vibe/api.py:5902-5908: model options;vibe/api.py:11666-11697(_opencode_get_server): providers (12030), model save (12591), and auth deletion (12934);core/agent_auth_service.py:3524-3566(_opencode_server): Web OAuth (3602,3667,3697) and the provider probe (3227).
None of them may launch a server after this change. Instead, they lease a
generation from the controller over control IPC (core/internal_server.py,
vibe/internal_client.py):
POST /internal/opencode/generation-leaseswith{purpose, ttl_seconds}. The controller captures the snapshot, computes the launch spec, and acquires with a lease, which is a core binding with a TTL. It returns{lease_id, generation_id, base_url, model_hub_provider_ids, expires_at}. It returns 404 when OpenCode is disabled, and 503 when the Hub engine is down or the start fails.POST /internal/opencode/generation-leases/{lease_id}/release.
The lease expiry is persisted in the generation record. A controller restart therefore keeps an OAuth flow's generation alive; today the UI's own server also survives a controller restart.
The UI helper is async with internal_client.opencode_generation(purpose, ttl) as server, which yields an OpenCodeServerClient. The controller-side
AgentAuthService uses the agent's local lease with the same shape.
| Flow | Change |
|---|---|
| Options, providers, model save, auth deletion | One lease per call (a 60 s request window), released in finally. Outside the controller a lease lasts LEASED_REQUEST_TIMEOUT_SECONDS longer than the window it is asked for, timed from before the controller grants it, and the leased client's request timeout is at most that constant. The client starts no request that its timeout could carry past the lease, so the controller never stops a generation under a running UI request; the TTL only stays behind a UI process that died holding the lease. _opencode_lease returns None only when OpenCode is disabled; a lease an enabled OpenCode cannot give raises, so no caller takes an unavailable runtime for a disabled one. Options and providers report the error. Model save fails closed, since it needs the live catalog to refuse a built-in duplicate. Auth deletion reports "OpenCode is unavailable" instead of "disabled". |
| Web OAuth | One lease from _start_opencode_oauth_web through the waiter. Authorize, the pasted-callback forward, and wait_provider_oauth must reach the same process, because the pending OAuth lives in its memory. The TTL is the flow timeout plus 60 s. The lease is released in the waiter's finally and in _terminate_web_flow. A success renews OpenCode. |
| Provider probe | One lease for the probe. Drop its mark_run_active and mark_run_inactive calls (agent_auth_service.py:3332, 3509), which today write the controller's PID file from the UI process. |
| Provider save | Still calls restart_backend("opencode") (api.py:12924, and the other provider writes at 12444-13042), which the core remaps to a snapshot advance. _refresh_opencode_provider_catalog_async then leases the current spec, which is a new generation if the save changed the digest. |
| Status | _opencode_process_status (api.py:9852-9872) reads the records and reports running when any proven generation is alive. |
7. Other consumers
vibe/cli.py:13872-13914(_stop_opencode_server): iterate the records and the legacy file with the same per-pid checks. ReturnTruewhen any server stopped.core/services/running_agents.py:717-764(_end_opencode): abort on the bound generation. When the last session ends, callagent.retire_idle_generations()instead ofretire_for_native_migrationon the singleton.core/handlers/settings_handler.py:453-479andcore/handlers/message_handler.py:548-562: useasync with agent.catalog_server(), a lease on the current generation.core/agent_auth_service.py:- the provider lookup (
796-805) and the IM API-key install (2112-2130) use a lease; _refresh_opencode_server(2149-2160) is deleted;- the disable branch (
2272-2280) becomesshutdown_runtime; - the OpenCode branches at
2339-2346and2359-2364move to the core path.
- the provider lookup (
docs/CLI.md:681and708, anddocs/CLI_ZH.md: point the PID-file row at the records directory, and drop theOPENCODE_PORTrow. That setting does not exist; the port is hard-coded atconfig/v2_compat.py:182.
8. Deletions
| Mechanism | Code |
|---|---|
PATCH /global/config reload |
refresh_global_config (server.py:667-706); _merge_global_config_snapshot and _get_global_config_snapshot (server.py:2792-2812); the reload branch of refresh_runtime_config (agent.py:1171-1223); config_reconciler.py, whose only caller is server.py:2798. |
| Deferred refresh | _auth_refresh_pending, _auth_refresh_pending_port, and _pending_runtime_config (server.py:285-288); _restart_for_auth_refresh_locked (595-649); detach_after_deferred_refresh (651-665); reload_runtime_config, _set_runtime_config, and _apply_pending_runtime_config_locked (708-730); restart_for_auth_refresh (2181-2194); the pending branches at 1054-1055 and 1863-1864. |
| Overlay transition and reservations | The overlay fields (server.py:290-304); MODEL_HUB_OVERLAY_DRAIN_TIMEOUT_SECONDS (66); set_model_hub_overlay_preparer (428-434); _configured_model_hub_overlay through _prepare_model_hub_launch_boundary (812-873); configure_model_hub_overlay (875-997); release_model_hub_overlay_reservation (999-1004); the reservation parameter of mark_run_active (1006-1037); OpenCodeModelHubOverlayRequiredError (238-239); the agent's reservation plumbing (agent.py:750-756, 1323, 1360-1364, 1748-1755, 2068-2084, and the _release... calls). |
| Policy- and plugin-pending refusals | OpenCodeManagedPolicyRefreshPendingError (server.py:234-235); _caller_context_plugin_refresh_pending (287); the refusal block (1860-1913); _pid_file_has_caller_context_binding, _pid_file_has_current_runtime_policy, _pid_file_was_started_by_current_process, and _pid_file_has_known_no_active_runs (1189-1208); their display mapping (agent.py:1064-1067); the i18n keys error.opencodeModelHubOverlayRequired and error.opencodePolicyRefreshPending (vibe/i18n/en.json:442-443, zh.json:442-443). |
| #2328 compatibility checks | None on this base; #2328 is still an open draft. Nothing is ported from it. |
| Singleton and fixed port | DEFAULT_OPENCODE_PORT (server.py:51); _instance, _class_lock, get_instance, and get_instance_if_managed_server_exists (249-250, 436-501); _pid_file (281); _runtime_generation_token and the replacement-retire helpers (324-366); _is_port_available and _find_opencode_serve_pids (1618-1684); _cleanup_orphaned_managed_server (1795-1846); ensure_running and _ensure_running_with_current_overlay (1848-1947); stop_instance_sync and terminate_instance_sync (2156-2204); the port field of OpenCodeCompatConfig (v2_compat.py:53, 182). |
| Adapter refresh entry | OpenCodeAgent.refresh_runtime_config (agent.py:1171-1223) becomes apply_runtime_config_change: reload opencode_config and take no server action. A forced refresh, used only by the coordinator's interrupt path until that path is deleted, force-stops every generation. prepare_runtime_restart (agent.py:1082-1084) becomes the adoption trigger. |
9. Tests
The rule: each deleted mechanism loses its tests, each rewritten contract keeps one test at its owner boundary, and each new behavior gets a test that fails on the old code.
| File | Change |
|---|---|
tests/test_opencode_server.py |
Delete the tests for removed mechanisms: refresh_global_config (1397-2149); restart_for_auth_refresh (2172-2277); request_scope pending (2455); reload_runtime_config (2469); pending detach (2598); get_instance (2493-2570, 2652); Hub launch refusals and rechecks (506-565); plugin and policy refreshes, deferrals, and refusals (483, 691-903); stale-pid cleanup (1021); the unmanaged healthy server (1049); singleton generation replacement (1069, 1095); the Windows port scan (2151); terminate_instance_sync (243, 267); the overlay transition tests (3350-3527). Rewrite as generation tests: the start timeout (198); record run markers (933-1002); record birth identity (954); adoption with active runs and reused pids (2289, 2301); terminate_sync (2313-2341); adoption and stop proofs (2354-2445); the observed exit (2445); resource governance (2482); overlay preparation as a spec input (600, 672); the recorded caller-context path (903); the catalog projection with the generation's provider ids (302, 342). Keep the HTTP and diagnostic tests (175-192, 288, 1126-1377, 2629-2675, 2700-3189, 3260, 3317). |
| New tests: spec | An in-place binary change (stat or version) changes the digest; this fails on the old code, which compared only the path. An OAuth token rewrite keeps the digest. An API-key change changes it. Inserting $schema keeps it. |
| New tests: process and routing | The launch never passes --port=0. Adoption covers every record plus the legacy file. A start on a taken port retries. A turn's status, abort, and steering go to its own generation while a newer one is current. A retiring generation stops when its last binding is released. |
tests/test_opencode_client_manager.py |
Replace both tests (14, 47) with hook tests for OpenCodeGenerations. |
tests/test_opencode_config_reconciler.py |
Delete, with the module. |
tests/test_agent_auth_service.py |
Delete 1580 and 1761-2185 (refresh, global-config reload, and uncached-server attach). Add one test: a config change takes no server action, and the next turn gets a new generation. |
tests/test_ui_api.py |
43-1546: patch the lease helper instead of OpenCodeServerManager.get_instance. The catalog assertions stay. Delete 346 (the UI launch boundary). Rewrite 600 as a lease-error mapping. |
tests/test_web_oauth_flow.py |
856-2172: patch the lease. Add one test: authorize, callback, and wait share one lease, which is released on success, cancel, and expiry. |
tests/test_multi_platform_runtime.py |
Delete 59 and 91 (the localized refusals). Move 127, 223, 1179, 1373, and 3978 from overlay reservations and ensure_running to acquire bindings. |
tests/test_opencode_restore_polls.py |
340-1114: route through the poll's generation. Add one test: a poll in the released shape (no generation key) routes to the legacy record. |
tests/test_agent_steering.py |
1306, 1450, 2706, and 2920: steer through the bound generation. 2706 covers "no binding". |
tests/test_vibe_cli.py |
1007 and 1035: stop every record plus the legacy file. |
tests/scenarios/auth_setup/test_auth_setup_scenarios.py |
3037, 4083, and 4273: use leases and renew-on-OAuth. Update the matching scenario IDs in catalog.yaml. |
tests/test_runtime_activation.py and tests/scenarios/model_hub/catalog.yaml |
Rewrite 242 for per-generation identity. MH-RUNTIME-002, 003, 004, and 007 (catalog.yaml:503-538) describe the deleted transition. Retire them and add IDs for "an overlay change starts a new generation; the old one finishes its run". |
| Smaller fake-server updates | tests/test_opencode_stop_receipt.py:233 (binding release replaces reservation release); tests/test_opencode_directory_bootstrap.py:188; tests/test_runtime_ownership.py:299 (per-generation targets); tests/test_native_takeover_lifecycle.py:862, 883; tests/test_desktop_runtime_stop.py:241, 543, 718 (dynamic-port argv, several servers); tests/test_agent_backend_alive.py:135-221; tests/test_running_agents_service.py:1075, 1109; tests/test_settings_handler.py:520-636; tests/test_message_handler_typing.py:361; tests/test_save_opencode_provider_auth.py:524, 666, 916; tests/test_native_writer_custody.py:290; tests/test_backend_connection.py:118; tests/test_native_login_single_flight.py:79. |
10. What the adapter needs from the core contract
- The spec object carries the adapter's launch inputs: the overlay content and the binary path. Equality is by digest only.
acquire(spec, *, purpose, ttl=None)returns a binding that pins its generation until released or expired. The binding works as an async context manager, and another task can release it.bind(generation)binds a restored poll to an adopted generation without comparing specs.adopt(generations)registers adopted generations, with "the newest matching generation becomes current".- A decision on who emits the runtime-update notice on a forced stop. The adapter can emit it from the cancelled task's handler.
- A renew epoch as a spec input, for manual Restart and Avibe-initiated OAuth success.
- The snapshot carries the Model Hub configuration for
prepare_opencode_overlay(section 5). - For backends that can coexist, in-place replacement starts the new generation before stopping the old one, so it never waits on a stop.
11. Risks and open items
- Cross-version coexistence is unverified. An upgrade while an old generation is busy runs the new version's database migrations under a running older version. Gate for Phase 2: a hermetic two-version probe in which the old version is mid-prompt while the new one starts, the old prompt completes, and the session continues on the new version. If the probe fails, the owner must decide whether a version change interrupts the old generation or waits for it to drain.
- OAuth tokens are assumed to be read live. The normalized credential
digest assumes OpenCode reads OAuth tokens from
auth.jsonon each request. Renew-on-OAuth-success covers Avibe's own logins either way. - Memory. Up to three servers can run at once.
12. Lifecycle invariants and audit
This audit covers head 2b35e0739. Each invariant below is a one-line rule. In
the transition table, every cell names the code path and states whether the
rule holds under normal flow, a failed write (W), cancellation (C), and
process death (D). A gap is a real violation and is fixed in the push that
follows the audit, with a regression that fails on 2b35e0739. A known item
is a bounded consequence kept by design, and is also listed in the PR's
Known-by-design ledger. Gaps G4 and G5 came from Codex's review of
2b35e0739, on transitions the first version of this table missed. Gaps G6–G9
and the corrected cells came from an independent agent that checked every
"holds" claim against the code.
Invariants
| ID | Rule |
|---|---|
| R1 | Every opencode serve process Avibe started has a record on disk before it can serve, until it is confirmed gone. |
| R2 | A record is removed only once its process is confirmed gone: stopped by Avibe, dead, or proven not ours. A record that cannot be read is kept. |
| R6 | A record of another desktop Runtime sharing this state directory is never adopted, stopped, forgotten, or overlay-cleaned here. _record_is_ours(), applied in _recorded_processes(), is the one gate every reader goes through. A durable poll whose run a live process of another Runtime executes is never bound, rewritten, or settled here. |
| R3 | A record never protects less than its process runs. A run marker or lease is written before its work starts. A release may lag, but a sweep rewrites it. |
| R4 | A generation's overlay copy lives and goes with its record. |
| R5 | No write recreates the record of a process that has stopped. |
| O1 | A live process is attached to at most one runtime in this controller. |
| O2 | Every recorded live process is attached to a runtime here, or is being started here, or stays unmarked so that an adoption here or a successor can take it. |
| O3 | The owned-here mark, the process's pid and create time, is set at spawn, before anything that can fail, the record write included. It ends only when a stop proves the process gone or its start proves it exited. Service shutdown stops every owned process, through its record or, without one, by that identity. |
| O4 | Every attached generation whose stop declined or failed is retried, by the controller's sweep or by its own runtime's sweep. |
| L1 | A lease holds one binding on its generation from grant until release or expiry. |
| L2 | Every lease ends by a release, its TTL, or a controller restart, where adoption re-holds what remains or drops what expired. |
| L3 | A release reaches the runtime holding the lease, whether or not its agent is registered. If no runtime holds it yet, the registered agent adopts first. |
| L4 | A lease's TTL covers its holder's longest legitimate wait. |
| L5 | A lease's expiry is in the record before the lease is handed out (R3). |
| B1 | A turn, a restored poll, a current_server() use, and a lease each hold one binding for their whole use, and release it exactly once on every exit. |
| B2 | No new work binds to a closed or stopped generation. A turn's prompt, status, abort, steering, and stop reach the generation it is bound to. |
| B3 | A bound generation is stopped only by a forced stop, which first settles the bound work, each session once across retries, with the stop's reason (a disable's, else a runtime update), and never another agent instance's work. |
| M1 | A native run is marked on its generation, and that marker persisted, before the run's first native write. |
| M2 | A turn clears its marker together with its durable poll: both go, or both stay. This is master's contract. |
| M3 | A marker that no live run or durable poll backs never keeps a process: adoption reconciliation and the re-reconcile in _stop. |
| S1 | New turns run on the generation whose spec equals the current spec. A renewal is persisted before it takes effect. |
| N1 | A native migration never overlaps the start of an OpenCode process: work outside a turn waits while the backend drains, and admitted work counts as active until it is bound. |
| P1 | A durable poll names the generation that runs its native turn, including after a restore binds it elsewhere. |
Transitions
| Transition | Code path | Invariants and outcome |
|---|---|---|
| Start: success | start_generation: overlay copy, spawn, mark owned, write_record, governance, _wait_until_ready; core acquire installs it current |
R1, R4, O3, S1 hold. Known K1: a controller crash in the microseconds between spawn and the record write leaves an unrecorded process (R1). |
| Start: port taken | outcome exited: ownership and record dropped, same id retried on a new port |
R1, R2, O3 hold. |
| Start: timeout or cancellation | terminate the spawned process; on exit remove the record, else hand the survivor to the runtime that started it (on_survivor), which keeps it owned, record and overlay included, and stops it at every later reap() and at shutdown() until it is gone |
R1, R2, R4 hold. W: a failed record write aborts the start and terminates the process. C: holds for one cancellation. Known K4: a second cancellation inside the cleanup can skip the record removal (a stale record, later removed as dead) or, if it lands before the kill, leave the process recorded but unsignalled until vibe stop, shutdown, or the next adoption. Gap G12: such a survivor was dropped from ownership, so nothing here retried its stop and it ran beside later generations until service shutdown. Every process a runtime spawned is now retried until it is gone, unrecorded ones included (a failed record write), since the runtime holds the process itself. Gap G14: ownership began only after the record write, so a start whose write and termination both failed left a process owned by nothing but its runtime's next reap; a service stop before that reap never found it. |
| Start: runtime closed meanwhile | core acquire attaches it closed and retiring and kicks the reconciler |
O2, O4 hold. |
| Adopt: fresh record | adopt_recorded_generations proves, health-checks, and returns it; ensure_adopted attaches them oldest first by process start, so the set's serials follow process age, and reconciles markers (W: write-behind), attaches, marks owned, applies governance, attaches activation, re-holds leases |
O1–O3, L2 hold. C: cancellation lands only inside adopt_recorded_generations (the attach loop has no suspension point), so nothing is marked and the retry adopts everything. D: an unhealthy proven process is stopped; a survivor keeps its record. Gap G7: one failed 5 s health probe stops a proven process, which may be busy with runs that durable polls would restore. Gap G9: a recorded lease is re-held for expires_at - now, unclamped, so a backward clock step across the crash pins the generation for that long. Gap G15: generations were attached in record filename order, which is random, so the cap's force-stop of the lowest serial took an arbitrary adopted process instead of the oldest. |
| Adopt: legacy record | converted to a generation with spec legacy; the legacy file goes once the new record is written (write-behind) |
R1, R3 hold. Gap G3: a crash between writing the converted record and removing the legacy file, or a failed removal, makes the next adoption adopt one process twice (O1). Gap G6: the same happens inside one controller: a runtime created by a re-enable re-adopts a legacy server that the closed runtime still owns, because ownership is known by generation id and a legacy record has none. A failed unlink also cleared _supersedes, so the removal was never retried. |
| Adopt: unreadable record | _read_json_object returns None and the record is skipped and kept |
R2, R4 hold. Its process is excluded from adoption, shutdown, and vibe stop alike; only a log line reports it. This is by design: nothing can prove what it names. |
| Adopt: malformed field | a readable record whose field has the wrong type reads as one without that field: _record_pid, _record_port, _record_number (finite numbers only), and _record_runtime_id (an id, null, or unrecorded, so judged by its live process); a generation's id is its file name |
R2, R6 hold. Gap G17: an unhashable desktop_runtime_id or generation_id, or a number too large for a float, raised in the gate, _owned_here, or the proof, so one corrupt record failed every adoption, lease, restore, and shutdown stop. |
| Adopt: dead or not ours | record and overlay removed without a signal | R2, R4 hold. |
| Lease acquire, in controller | lease_generation → OpenCodeRuntime.lease: core acquire, then set_lease (persisted first), then _hold_lease (timer and holder) |
L1, L5 hold. W: the lease fails and its binding is released. C: no binding survives. |
| Lease acquire, IPC | POST /internal/opencode/generation-leases → same path |
Same as above. A UI caller that gives up after the grant leaves the lease to its TTL (L2). |
| Lease renew | none by design; each holder sizes its TTL | L4 holds for realistic runs: OAuth uses the remaining flow budget + 60 s; the probe uses bootstrap + timeout + 60 s; model options makes at most about 5 × 10 s of requests under 60 s; catalog, model save, and auth removal each make one request bounded by its request timeout. A probe whose every request hits its own timeout can outlast its lease, and then fails anyway. A UI caller that gives up before the grant leaves a lease nobody releases, bounded by its TTL. |
| Lease release | in controller: the captured agent's release_generation_lease; IPC: release_opencode_lease (holder map, else each runtime agent adopts first, else the recorded lease is cleared, else 404); expiry timer → release_lease |
L1–L3 hold. W: the drop is write-behind and flushed by the next sweep. After a force-stop, the record write is a no-op (R5). |
| Turn bind and unbind | _run_turn: acquire → _session_generations → mark_run_active (persisted first) → durable poll → prompt; _process_message finally releases |
B1, B2, M1, M2 hold. C: release is synchronous bookkeeping in a finally. W: a failed marker write fails the turn before its first native write; a failed clear keeps marker and poll (M2). |
| Restored poll | _bind_restored_poll (adopts first; binds by generation id, else legacy marker, else current) → task → finally releases |
B2 holds. A closed runtime refuses the bind, so the poll stays durable. Gap G19: each handed-off poll task waits for the restore to publish it; a restore cancelled, or failing to mark an earlier poll's session running, left the rest waiting forever, holding their binding and request, so later restores skipped them. Gap G18: a failed rewrite of the poll's generation was logged and the poll still ran, so a crash before it finished left it naming the old process and the next restore bound it to another server. Gap G16: a poll whose run another desktop Runtime's live server executes found no generation here, so restore started its own, rewrote the poll to it, and settled the run from a server that does not run it. Gap G8: restore_active_polls holds the binding across several awaits before the poll task takes it over. An exception in that stretch leaks the binding (B1), and a forced stop in it leaves the poll registering on a dead process (B3). Gap G5: a poll bound to a generation other than the one it names keeps the old name, so after another crash adoption drops the new generation's marker and the rebind goes to the wrong process (P1, M3). |
| Native migration | BackendRestartCoordinator guard: begin_backend_drain holds turns; it waits on backend_runtime_active → runtime_has_active_turns; retire_for_native_migration → retire_all_strict; verify_idle |
Gap G4: current_server() and lease_generation() bypass turn admission, and an acquisition still starting a process is invisible to runtime_has_active_turns, so the guard can yield while a process starts (N1). |
| Retire: renewal | renew() persists the epoch first; the next turn's spec installs a new current and the old one retires |
S1 holds. W: renewal raises without effect. |
| Retire: End-idle and strict migration | retire_confirmed() waits for the reconciler and reports stopped, draining, or failed |
B3, O4 hold. |
| Retire: forced refresh | _cancel_active_requests() then retire_all() |
B3 holds; leases keep their generation until released. |
| Disable | the core interrupts the backend's work, unregisters the agent, and runs shutdown_runtime(settle_reason="backend_disabled") → OpenCodeRuntime.shutdown() inside AgentService.run_until_done: a forced stop_all of every attached generation, each forced stop settling its bound work with that reason, then stop_recorded_servers_sync() for every recorded server no runtime here owns. It raises while any process survives, so the idle sweep retries it; a retry repeats both steps |
B3 holds by the user's own interruption. L3 holds: a later UI release reaches the holder. W/D: a survivor fails the teardown, which is retried until it stops. Gap G2: a runtime that never adopted stopped without adopting, so a crashed predecessor's generations ran until shutdown (O2). Gap G1, a closed runtime that was never swept, ended with the drain path. Gap G10: an incomplete shutdown returned normally, so the teardown's retry was lost. Gap G13: the forced stop settled bound work only as a runtime update, so a disable whose core interrupt failed, retried after a re-enable that skips that interrupt, never settled it as disabled; it ended Activities by runtime key, which a re-enabled agent's Activities in the same session share; and a retry settled again a session an earlier attempt had settled, whose next turn may run on the re-enabled agent. |
| Cap force-stop | core _next_victim forces the oldest retiring generation; _on_generation_stopping(force) → _interrupt_generation_work settles the bound sessions' turns and, by the runtime keys the ownership snapshot gives them, their Activities; stop_generation |
B3 holds; a lease holder sees its process end, by design. Gap G11: the forced stop passed no runtime keys, so the interrupted sessions' Activities and Runs stayed active after the process was killed. Every forced stop of the adapter goes through this one hook; forget() handles a process that already died, and the record-based stops touch only records no runtime here owns. |
| Controller restart | explicit: shutdown stops every generation this controller owns; next start adopts and restores polls on a new current. After a crash with OpenCode disabled, startup runs stop_recorded_servers_sync() |
R2, B1 hold. Gap S-1: after a crash, a restart with OpenCode disabled never stopped its leftovers, which ran until the next stop or enable (O2). |
| Crash between steps | spawn→record (K1); record→ready (adopted or stopped); lease grant→hand-out (the successor honors it until TTL); marker→durable poll (marker reconciled away); kill→record removal (unproven, removed later); legacy write→legacy removal (G3) | R1–R3 hold except K1 and G3. |
| Process death | acquire replaces a dead current (forget → stop_generation cleans up); a dead retiring generation is cleaned on its last release |
R2, B1 hold. |
| CLI stop | stop_recorded_servers_sync(provenance): forget_dead_records(), then each proven record, through the one ownership gate, stop_recorded_server_sync |
R2, R4 hold; a survivor keeps its record; exit stays non-fatal (#2242). |
| Shutdown | stop_owned_generations_sync(): stop each recorded generation a runtime of this controller owns, then each owned process with no record by its pid and create time (never one whose create time differs or cannot be read); another desktop Runtime's records are left alone |
R2, R4 hold. Known K5: the loop keeps running briefly after this call, and a lease expiry or sweep there can rewrite a record of a process just killed (R5). The next adoption or vibe stop removes it as dead. |
Fixes
| Gap | Fix | Regression |
|---|---|---|
| G1 | moot: disabling stops every generation at once, so no closed runtime waits for a sweep. reap() still does not wait for a completed adoption |
— |
| G2 | shutdown() stops a previous controller's servers by their records, after its forced stop of what it attached |
test_disabling_the_backend_stops_a_previous_controllers_generations |
| G10 | shutdown() raises while any attached generation or recorded server survives |
test_a_disable_shutdown_that_leaves_a_process_raises_and_its_retry_finishes |
| G11 | _interrupt_generation_work passes base_session_id:working_path runtime keys |
test_a_cap_forced_stop_settles_the_activities_of_the_sessions_it_interrupts |
| G12 | a failed start's surviving process stays owned by its runtime, whose reap() and shutdown() retry its stop until it is gone |
test_a_failed_start_whose_process_survives_is_reaped_until_it_is_gone |
| G17 | every record reader takes fields through the typed readers above; a malformed Runtime id is judged by the live process; _every_recorded_process sets each generation's id from its file name |
test_a_malformed_record_never_disables_opencode |
| G18 | _bind_restored_poll releases its binding and raises when the rewrite fails; restore and the poll task leave the poll durable, its Turn live, and add it to _polls_awaiting_restore, as every other restore step that leaves a poll for later does; reap_runtime_generations restores again through restore_polls_on_ready_transports while one remains |
test_a_restore_whose_generation_rewrite_fails_runs_nothing_and_the_sweep_restores_it, test_a_poll_task_whose_rebind_cannot_be_recorded_leaves_its_turn_live_for_the_sweep |
| G19 | restore_active_polls tracks every handoff and, in a finally around the whole restore, cancels each task it never published, before its poll loop starts: the task releases its binding and request, and the poll stays durable in _polls_awaiting_restore for the sweep |
test_a_restore_whose_publication_fails_leaves_no_poll_task_waiting_on_it |
| G15 | ensure_adopted attaches adopted generations sorted by started_at; a record without one, such as the legacy record, takes its process's create time |
test_the_cap_stops_the_oldest_adopted_generation_whatever_its_record_order |
| G16 | restore reads other_runtimes_live_records() once and leaves every poll whose run one of them executes: the generation it names, or for a poll naming none, the process whose record marks its session running |
test_restore_leaves_every_poll_whose_run_another_desktop_runtimes_live_server_executes |
| G14 | ownership starts at spawn and ends only on a proven exit; stop_owned_generations_sync() also stops owned processes no record names, proven by pid and create time |
test_service_shutdown_stops_a_started_process_whose_record_was_never_written |
| G13 | shutdown_runtime(settle_reason) makes the reason this agent's forced-stop settlement for good; _interrupt_generation_work names sessions only from this agent's bindings, ends the Activities started under the stopping generation's activation identity, bound session or not, and settles each session of a generation once, recorded on the generation, so a retried stop settles only the rest |
test_runtime_gen_006_a_disable_retried_after_a_re_enable_settles_only_the_disabled_agents_work |
| G3 | adoption skips and removes a legacy record whose process a converted record already named | test_adoption_takes_a_converted_legacy_server_once |
| G4 | _outside_turn_admission(): work outside a turn waits while the backend drains; it is counted, in one step with the readiness check, until it is bound; runtime_has_active_turns() reports it |
test_a_native_migration_never_overlaps_an_opencode_start_outside_a_turn |
| G5 | _bind_restored_poll rewrites the poll's opencode_generation_id whenever it binds a different generation |
test_runtime_gen_022_a_restored_poll_resumes_on_the_generation_that_runs_it |
| G6 | the ownership map records each owned process's identity; adoption skips a legacy record whose process a runtime here owns; _supersedes clears only once the legacy file is gone, and every flush retries it |
test_a_reenabled_backend_leaves_a_legacy_server_another_runtime_here_owns |
| G7 | adoption probes a proven process up to three times, two seconds apart, before stopping it | test_adoption_gives_a_busy_server_more_than_one_health_probe |
| G8 | the restore loop holds a poll's binding in one try from the bind to the handoff create_task, and releases it on any BaseException, cancellation included; the task rebinds when a forced stop took the generation it was handed |
test_restore_releases_a_poll_binding_its_task_never_took, test_a_cancelled_restore_releases_the_binding_its_poll_task_never_took, test_a_restored_poll_whose_generation_was_force_stopped_rebinds_before_registering |
| G9 | an adopted lease is re-held for at most MAX_LEASE_SECONDS |
test_adoption_never_holds_a_recorded_lease_longer_than_any_lease_is_granted |
| S-1 | controller startup with OpenCode not registered runs stop_recorded_servers_sync(desktop_caller_provenance()) |
test_a_controller_starting_with_opencode_disabled_stops_a_crashed_controllers_servers (RUNTIME-GEN-025) |
Desktop Runtime ownership
Several desktop Runtimes can share one Avibe state directory, so every record
names the Runtime whose controller wrote it (desktop_runtime_id, written at
spawn: the one Runtime this process acts for, or null). _record_is_ours() is
the one ownership predicate:
- A caller with no desktop provenance acts on any record, as
vibe stopalways has. - A record that names a Runtime is ours only when this caller acts for exactly that Runtime. Null counts as a Runtime too, so it is foreign to a desktop caller.
- A record from a release or build before the field existed, including the
legacy single-server record, is judged by its live process. This is the same
check as
refuse_foreign_desktop_process: a process carrying another or no Runtime id, or one whose environment cannot be read, is foreign; a process that is gone belongs to nobody, so its record can be forgotten. Adopting such a record keeps it without the field, so the check stays the same on every later read.
Every reader goes through _recorded_processes(), which applies the gate.
What a shared state directory shares. Two Runtimes share one when they run
with the same AVIBE_HOME, by default ~/.avibe. This is the supported
desktop update path: each private Runtime tree has its own id, and the new
Runtime takes over the home of the one it replaces. It also happens when a
terminal install and the desktop app share a home. Everything under the home
is shared: the V2 config, the SQLite state (sessions, turns, deliveries,
Activities, settings, and OpenCode's active polls), logs, the runtime
directory, and OpenCode's generation records and overlays. The OpenCode
caller-context binding file and plugin are shared too, but they are keyed by
native session and renewed by their writer. The data-directory service lock is
held for a controller's lifetime, so at most one controller runs on a home at
a time. Two Runtimes' poll loops therefore never run at once.
Ownership follows processes, not user data. The SQLite state is the user's, and any Runtime's controller resumes it, exactly as after a restart; that boundary is the core's, and it is Runtime-agnostic by design. A Runtime owns only the processes it started. Durable state stays that Runtime's for as long as it names a live process of that Runtime:
- A record is the process's identity. Another Runtime's record is never acted on, even after its process ends, because a failed proof must never disown a live process. Its own Runtime forgets it once its process is gone.
- A poll belongs to the process that executes its run: the generation it
names, or, for a poll from before generations, the process whose record marks
its native session running. While another Runtime's record proves that process
live (
other_runtimes_live_records(), through the same_record_proves_processevery record reader uses), restore leaves the poll untouched: no bind, no rewrite, no settlement. Its Runtime resumes it. Once the process is gone, no process runs the poll's run, and this controller settles it as after a restart. An app update therefore never strands a turn.
| Path | Disposition |
|---|---|
| Adoption, including legacy conversion and dedupe, unproven-record removal, and the unhealthy-server stop | gated |
| Adoption's sweep of overlays without a record | removed: another Runtime writes its overlay before it spawns and records the process |
ensure_adopted lease re-hold, marker reconciliation, reap() flush, and _stop |
act only on generations this runtime attached, so they are ours |
stop_owned_generations_sync() (controller shutdown) |
gated for records, and limited to processes owned here; an owned process with no record is ours by spawn |
stop_recorded_servers_sync(runtime_ids) (vibe stop and a disabled startup) |
gated for the caller's ids; the inline refusal moved into the gate |
forget_dead_records(runtime_ids) and recorded_servers(runtime_ids) |
gated |
Status: vibe/api.py _opencode_process_status → recorded_servers() |
gated by the UI process's provenance, so another Runtime's servers do not count |
| Lease release | reaches only the holder or the registered agent, so it is ours |
start_generation |
writes desktop_runtime_id |
restore_active_polls |
leaves every poll whose run another Runtime's live process executes; resumes the rest |
Known by design
- K1. A controller crash in the microseconds between spawn and the first record write leaves one unrecorded process.
- M2 pin. A turn whose marker clear fails keeps its generation, through marker and durable poll, until the next restore or cap pressure. This is master's contract. In the reverse case, a cleared marker whose poll removal failed, the next restore settles the poll.
- K4. A second cancellation inside a failed start's cleanup can leave a
stale record, or a recorded process that is never signalled, until
vibe stop, shutdown, or the next adoption. - K6. A poll left to another Runtime keeps its durable turn live here,
so the core queues new messages on that session behind it. An idle
opencode servenever exits on its own, so after that Runtime's controller crashed, its turn waits until that Runtime runs here again or its server is stopped, for example by its scopedvibe stop --expect-runtime-id. Taking it over instead would settle the run from a server that does not run it. - K5. After shutdown stops the recorded generations, a late write can recreate the record of a killed process; it is removed as dead later.
- Core reconciler latency. A generation that drains while the reconciler pass that declined it is still running waits for the next release or sweep (60 s, or the closed runtime's own sweep). This is core behavior.