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.
Process Identity Across Clock Changes
Status: proposed, low priority. The owner asked for this plan on 2026-10-04, after #2356.
Background
One case today
- At 10:00:00 Avibe starts an OpenCode server, pid 4321. Its record says "pid 4321, created at 10:00:00".
- At 10:20 the Avibe process is killed by the kernel's out-of-memory killer. No shutdown runs, so the OpenCode server keeps running its turn.
- Shortly after, the system steps its clock back by two seconds.
- At 10:21 Avibe is started again and finds the record. psutil now reports pid 4321 as created at 09:59:58. The comparison is exact, so Avibe decides the pid belongs to another process and drops the record without stopping anything.
- The old server keeps running with no owner. Its turn is never recovered,
and
vibe stopcannot find it.
Why
psutil's create time moves with the clock on Linux. It returns the process's start in clock ticks since boot plus the boot time. That boot time is the kernel's
btime: the current wall clock minus the uptime, in whole seconds. Every clock step or NTP adjustment therefore moves the create time of every process. The Incus regression VM stepped by about 2 s every few minutes, roughly 96 s in one hour.macOS can shift it too. The repository already records this in
core/process_isolation.py::process_identity_matchesandvibe/desktop_backends.py::_installer_owner_gone.Avibe uses the value for two different questions:
- Is the process at this pid still the one I recorded? This is identity, answered by an exact comparison.
- How long ago did it start? This is age, compared with
time.time().
The first question breaks when the clock moves. The second does not, because it is measured on the same clock.
Scope of the exposure
- A normal stop or restart does not depend on this.
Controller.cleanup_syncshuts the backends down and stops every OpenCode server this controller owns. A service restart keeps crash-recovery semantics; seebackend-rolling-restart.md, "Service restart boundary". - The servers a running controller started itself are judged by their process handle since #2356, both each turn and at shutdown.
- What remains is bookkeeping across processes: recovery after an Avibe process died without cleanup, and the few records one Avibe process checks while another runs, such as a restart in progress.
- A mismatch always errs toward "the recorded process is gone". The cost is a leaked process or a duplicate start, never a signal to a stranger, because every stop path refuses to signal a pid it cannot prove.
An approach that was rejected
#2356 first replaced the shared reader vibe.runtime.process_create_time with
a clock-stable value: a per-boot anchor plus the tick count from /proc.
Review found a new consumer it broke on every round, among them wall-clock age
checks, records written by released builds, and the watch reuse heuristic.
Changing the meaning of a value that many consumers and persisted records
share is the wrong unit of change. The PR was narrowed to process handles.
Goal
Every check of "is the process at this pid still the one recorded" is immune to clock changes on every platform, and it is changed one consumer at a time without altering any value other consumers or released records rely on.
Design
The repository already has the model:
core/process_isolation.py's inherited identity marker. It is a 256-bit token
in the spawned process's environment (AVIBE_PROCESS_IDENTITY), inherited by
its whole process tree. The record keeps only its fingerprint. The marker is
meant to be the authority and the birth time only a hint:
process_identity_matchesproves the recorded process by its marker.process_identity_recycledproves a reused pid when the process holding it is readable and lacks the marker, but today it also requires a birth-time mismatch. That requirement goes: a readable environment without the marker is proof on its own, since a clock step can make a replacement's birth time equal the recorded one. This is a change to a shared predicate, made once in the first rollout step for all its callers.process_group_identity_statusjudges a recorded process group the same way and needs the same change. Today it compares each member's birth time with the recorded leader's, so after a clock step a group that reused the pgid is "unknown" instead of "another tree", and recovery records for watches, scheduled tasks, the Model Hub engine, and the desktop installer stay blocked until that unrelated group exits. Members are judged by their markers alone.
Command workers (core/command_runner.py), the Model Hub engine supervisor,
and the desktop backends use it today.
One rule decides identity, in this order:
A process handle, when this process holds one: it is exact until the handle reaps the child. #2356 uses this. On Windows, an open handle to any process also keeps its pid from being reused, and becomes signaled when the process exits.
The inherited marker, when the process was spawned with one.
A structural relation, where one exists. A child waiting for its parent compares
os.getppid()with the recorded parent pid on POSIX. Windows never re-parents, soos.getppid()keeps the old pid after the parent exits; the child opens a handle to the parent at start (rule 1) and waits on it.Independent evidence, only for records with none of 1–3, such as those written by released builds. The birth time proves nothing in either direction: a clock step shifts it for the same process, and a step back can give a replacement process exactly the recorded value. The check gives three answers, never two:
- the same process: a readable, independent proof matches, such as the command line, port, or role, and the birth time agrees;
- another process: a readable, independent proof no longer matches;
- unknown: anything else, including a matching birth time alone. The record is kept, nothing adopts or signals its process, and a later pass asks again.
A boolean check cannot express the third answer, so each consumer still using rule 4 needs one. A command line is independent proof only when it names this particular process. Every watch supervisor runs the same
python …/watch_worker.pyargv, with its watch id only in the environment, so for those the per-watch environment is the proof, and without it the answer is unknown.
A marker identifies one managed process tree and never crosses a role
boundary. Otherwise, after a marked process exits, a descendant of another
role that later receives its recycled pid would carry its fingerprint and pass
for it. The common boundary enforces this: vibe.runtime.independent_process_env,
which every service and UI launch goes through (including a vibe start run
by a marked backend descendant), removes AVIBE_PROCESS_IDENTITY. A role that
needs a marker sets its own after that.
Identity must still hold when the signal is sent. A check followed by a bare-pid signal leaves a gap in which the process can exit and its pid be reused; a TERM, a wait, and then a KILL leaves two. Every stop therefore signals through a handle where the platform offers one (a pidfd on Linux, a process handle on Windows), or re-proves identity immediately before each signal.
Ages keep the wall-clock birth time and are out of scope, for example
vibe.runtime._pid_reservation_is_fresh. Ordering a process's birth against a
file's mtime to decide whether it is still the same process is identity, not
age.
Invariants
- Neither a clock step nor a create-time shift makes a live recorded process look gone or foreign.
- A reused pid is never taken for the recorded process, and a process that cannot be proven is never signalled.
- Every record written by a released build is still read. New fields are
optional and additive, and
process_created_atkeeps its meaning. - Identity holds through every signal, not only at the check before it.
Consumers
This is the starting inventory, not a proof of completeness. Each implementation PR re-audits its consumer end to end, every reader and every signal path, before it changes it.
| Consumer | Where | Decides | Today | Plan |
|---|---|---|---|---|
| OpenCode adopted servers | modules/agents/opencode/server.py: _record_proves_process, OpenCodeGeneration.process_alive with no handle, _owned_here pid fallback, _stop_unrecorded_process_sync for a non-child |
Adopt, stop, vibe stop, and liveness of a server from a previous controller |
Exact birth time, then command and port; a boolean that deletes the record when false | Spawn with a marker and store its fingerprint in the generation record, then prove by marker. A legacy record gets rule 4's three answers: adopt_recorded_generations and forget_dead_records delete only another process and keep an unknown record without adopting or stopping it |
| Claude CLI registry | modules/agents/claude_process_reaper.py: register_claude_owned_process, _process_identity_matches, and the signal primitive _reap_pid_set; core/services/running_agents.py: _collect_orphans (the Running Agents list), _end_orphan_pid, _end_claude, and the post-stop reap |
Which leftover CLI processes are shown, reaped, or ended | ps -o lstart within 1 s, repeated in each consumer; _reap_pid_set signals bare pids |
Add a marker to the CLI environment beside AVIBE_CLAUDE_PROCESS_OWNER and store its fingerprint in the registry. Every consumer proves by it through one shared check, and _reap_pid_set keeps that identity through each signal |
| Restart supervisor | vibe/restart_supervisor.py writes supervisor_started_at; vibe/ui_server.py (restart in flight), vibe/upgrade.py (seed retention), and scripts/incus_regression_supervisor.py::_restart_in_progress compare it |
Whether a restart job is still running | Exact birth time, or within 1 s | Spawn the supervisor with a marker, have the status carry its fingerprint, and migrate all three readers. _start_runtime_processes strips the marker from the service and UI it starts |
| Deferred upgrade activation (Windows) | vibe/upgrade.py passes --parent-started-at; vibe/cli.py waits on it |
When the launching parent has exited | Pid alive and birth time unchanged | Rule 3: before spawning the helper, the launcher opens an inheritable handle to itself and passes it. A handle the helper opened later could already name a process that reused the pid; the helper waits on the inherited one. The candidate keeps accepting and ignoring --parent-started-at indefinitely: an older installed release runs the newer candidate's parser, so a user who skips releases would otherwise fail to upgrade |
| Install generations | vibe/install_generations.py::_installer_is_live |
Whether the installer that wrote a generation's marker still runs, before collection may retire unselected generations | Installer birth time no later than the marker's mtime | Rule 4 with the installer's command line as the second proof. An unknown installer counts as live, so collection never deletes a candidate during a handoff |
| Desktop installer owner | vibe/desktop_backends.py::_installer_owner_gone |
Whether a Runtime's installer owner exited | A matching birth time counts as the owner; only a mismatch consults is_desktop_ui |
Rule 4: the owner is proven by its role (is_desktop_ui) whether or not the birth time matches, and a matching birth time alone is unknown |
| Watch workers | core/watches.py::_legacy_pid_was_reused, with blocked entries kept by _unreaped_runtime_entries; current entries through process_identity_recycled |
Recovery of watch workers; a --forever worker can outlive an upgrade |
Legacy: birth time later than updated_at. Current: marker, plus the birth-time mismatch the shared predicate requires |
Current entries benefit from the shared predicate change. Legacy entries use rule 4 with the per-watch environment as the proof (the argv is the same for every watch); without it they stay unknown, blocked and never signalled |
Rollout
- Shared ground, one PR.
- Make
vibe.runtime.process_create_timesay what it is: a wall-clock observation for ages and for reading released records, not an identity. Its docstring currently promises that(pid, create_time)identifies the original process, which would invite the next consumer to repeat the problem. Its value does not change. process_identity_recycledno longer requires a birth-time mismatch, andprocess_group_identity_statusjudges group members by marker alone.independent_process_envremoves the marker.
- Make
- Then one PR per consumer, in this order: OpenCode adopted servers, the Claude registry with Running Agents and the reaper's signal primitive, the restart supervisor (all three readers), install generations with the deferred upgrade activation, the desktop installer owner, and legacy watch entries. Each adds its marker, handle, or relation, keeps reading the legacy shape under rule 4, changes no other shared helper's meaning, and names, for every check it touches, whether that check is identity or age.
Validation
- Unit tests for each consumer, covering:
- a create-time shift with the marker present, which must still match;
- a reused pid holding a readable environment without the marker, which must be taken for another process;
- an unreadable environment, which proves nothing either way;
- each released record shape, read without a marker, including the unknown answer that keeps a record without acting on it.
- Windows tests for the deferred activation wait: the helper proceeds once
its parent exits, although
os.getppid()still returns the old pid. - Linux tests with real child processes for marker inheritance through a launcher, such as an npm shim or a shell wrapper.
- End to end on the Incus regression VM, whose clock drifts on its own:
- Kill the controller with
kill -9while an OpenCode turn runs. - Wait for a clock adjustment.
- Start the service again. The server must be adopted, its turn recovered, and a later stop must stop it.
- Kill the controller with
Open questions
Review of this plan raised the points below. The owner decided on 2026-10-06 that findings on this plan are advisory, so they are recorded here rather than resolved. Each one must be settled in the implementation PR it affects.
No atomic signal on macOS. A pidfd on Linux and a process handle on Windows bind a signal to one process. macOS has neither, so re-proving identity just before
kill(pid, ...)still leaves a window in which the process can exit and its pid be reused. The trade-off: either accept that window, with strong identity evidence immediately before the signal, or refuse to signal on macOS, which would leave leaked processes there unstopped. The plan leans toward accepting the window; the first PR that signals on macOS decides and records it.A marker names a tree, not a process. Every descendant inherits it. A consumer that must find one exact process, rather than act on a whole tree, needs a proof specific to that process, such as a handle, or a marker the root alone carries that its children do not inherit.
A role is not an owner.
runtime.is_desktop_uishows that a process is a UI of that desktop Runtime, not that it is the UI an installer owner record names. The desktop installer migration needs an owner-specific proof.The current controller's own shutdown still compares birth times.
modules/agents/opencode/server.py::terminate_pid_tree_syncandvibe/runtime.py::_stop_desktop_processeskeeppsutil.Processobjects whose reuse guard compares the birth time cached at the scan. A clock step during the TERM wait can make a surviving process look gone. They belong in the consumer inventory.Whether a process's initial environment is readable under the service user for every backend binary on macOS and Windows: a hardened or signed binary might refuse it. Measure before each consumer relies on it. An unreadable environment falls back to rule 4 and never signals.
Whether the OpenCode launcher or the Claude CLI clears the environment for any descendant that holds the listening socket or does the work. Measure with a real server and CLI.