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.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
import calendar
import errno
import getpass
import ipaddress
import json
import logging
import os
import signal
import shlex
import shutil
import socket
import subprocess
import sys
import threading
import time
import urllib.error
import urllib.request
import uuid
from dataclasses import dataclass
from datetime import datetime, timezone
from enum import Enum
from functools import lru_cache
from pathlib import Path
from typing import Callable, NamedTuple
import psutil
from config import paths
from config.atomic_io import write_atomic
from config.v2_config import V2Config
from core.process_isolation import fingerprint_process_marker, isolated_subprocess_kwargs, processes_carrying_marker
from vibe.log_sink import RUNTIME_LOG_MAX_BYTES, RUNTIME_LOG_RETAIN_BYTES
logger = logging.getLogger(__name__)
SHUTDOWN_INTENT_TTL_SECONDS = 30
SHUTDOWN_INTENT_ENV = "VIBE_REQUIRE_SHUTDOWN_INTENT"
SERVICE_LOCK_READY_TIMEOUT_SECONDS = 5.0
SERVICE_SLOW_START_TIMEOUT_SECONDS = 120.0
#: The service takes the lock before it migrates the database and builds its
#: controller, because both of those have to be done under the exclusion the lock
#: provides. So the lock marks the START of startup, not the end of it, and the
#: record it writes says which of the two the holder has reached. Anything asking
#: "is this instance up" has to wait for the second one: a migration that fails
#: kills the holder, and a watcher that stopped at the lock has already recorded
#: a success by then.
SERVICE_PHASE_STARTING = "starting"
SERVICE_PHASE_RUNNING = "running"
@dataclass
class ProcessStartInfo:
pid: int | None = None
reused: bool = False
def capture(self, pid: int, *, reused: bool) -> int:
self.pid = pid
self.reused = reused
return pid
def get_package_root() -> Path:
"""Get the root directory of the vibe package."""
return Path(__file__).resolve().parent
def get_project_root() -> Path:
"""Get the project root directory (for development mode)."""
return Path(__file__).resolve().parents[1]
def get_ui_dist_path() -> Path:
"""Get the path to UI dist directory."""
# First check if we're in development mode (ui/dist exists at project root)
project_root = get_project_root()
dev_ui_path = project_root / "ui" / "dist"
if dev_ui_path.exists():
return dev_ui_path
# Then check if UI is bundled with the package
package_ui_path = get_package_root() / "ui" / "dist"
if package_ui_path.exists():
return package_ui_path
# Fallback to development path
return dev_ui_path
def get_service_main_path() -> Path:
"""Get the path to the main service entry point."""
# First check if we're in development mode (main.py exists at project root)
project_root = get_project_root()
dev_main_path = project_root / "main.py"
if dev_main_path.exists():
return dev_main_path
# Then check if service_main.py is bundled with the package
package_main_path = get_package_root() / "service_main.py"
if package_main_path.exists():
return package_main_path
# Fallback to development path
return dev_main_path
class ServiceLauncher(NamedTuple):
"""The install that a service or UI process should be started from.
One value rather than an ambient fact, because there is exactly one case
where the answer is not "this process" and it is the case that matters: a
rollback that crosses the `vibe-remote` -> `avibe-os` tool rename reinstalls
into a different directory than the one the rolling-back process is running
out of. Every spawn site read `sys.executable` for itself, so the reinstall
succeeded and the failed release was started again -- twice over, since the
service and the UI each read it separately and would otherwise have to be
fixed separately, and a third spawn site would have to be found and fixed
again.
The interpreter and the entry point travel together because they are one
install. Pairing an interpreter with another install's entry point runs the
replaced release's code under the replacement's imports, which is neither
generation and is the failure this exists to avoid.
"""
python: str
main: str
def current_service_launcher() -> ServiceLauncher:
"""The install THIS process is running from.
The default for every spawn, so nothing changes for the ordinary restart:
the interpreter that is running is the one that should run the next
generation. Only a rollback overrides it, and only because by then this
process is no longer the install being started.
"""
return ServiceLauncher(python=sys.executable, main=str(get_service_main_path()))
def get_working_dir() -> Path:
"""Get the working directory for subprocess execution."""
# In development mode, use project root
project_root = get_project_root()
if (project_root / "main.py").exists():
return project_root
# In installed mode, use package root
return get_package_root()
ROOT_DIR = get_project_root() # For backward compatibility
MAIN_PATH = get_service_main_path()
_SERVICE_LOCK = threading.Lock()
_SERVICE_INSTANCE_LOCK_HANDLE = None
_SERVICE_INSTANCE_LOCK_OWNER_PID: int | None = None
_PENDING_SQLITE_BACKUP_READINESS: tuple[Path, str, tuple[str, ...], datetime] | None = None
_SERVICE_START_PROCESSES: dict[int, subprocess.Popen] = {}
# /ready can spend up to two seconds in the Controller health probe.
UI_ADOPTION_PROBE_TIMEOUT_SECONDS = 3.0
# Preserve the desktop host's DEFAULT_PROBE_TIMEOUT when Python owns the wait.
DESKTOP_READY_PROBE_TIMEOUT_SECONDS = 5.0
def _rounded_seconds(seconds: float) -> float:
return round(max(0.0, seconds), 3)
class ServiceAlreadyRunningError(RuntimeError):
def __init__(self, *, lock_path: Path, holder_pid: int | None = None):
self.lock_path = lock_path
self.holder_pid = holder_pid
detail = f"Vibe service is already running for this data directory: {lock_path}"
if holder_pid:
detail = f"{detail} (pid={holder_pid})"
super().__init__(detail)
def ensure_dirs():
from storage.migrations import guard_source_checkout_default_state_bootstrap
guard_source_checkout_default_state_bootstrap()
paths.ensure_data_dirs()
def ensure_config():
from storage.migrations import guard_source_checkout_default_state_bootstrap
guard_source_checkout_default_state_bootstrap()
config_path = paths.get_config_path()
from config.v2_config import config_file_lock
from core.services import settings as settings_service
# Create-if-absent under the cross-process file lock (#1458 stage
# ③): the existence check and the seeding save are one atomic step,
# so a first-run default snapshot cannot overwrite an initial
# settings save another process completed between a lock-free check
# and the write.
with config_file_lock(config_path):
if not config_path.exists():
# The same first-run shape the CLI seeds, whichever process starts first.
settings_service.default_config().save(config_path)
return V2Config.load(config_path)
def write_json(path, payload):
# ``write_atomic`` owns the swap so a concurrent reader never sees a
# half-written file. The regression supervisor polls status files (e.g.
# restart_status.json) while restart jobs rewrite them, and a partial read
# would otherwise surface as None and be misread as "no restart in
# progress". Its per-call unique temp name is what makes that safe here:
# several threads in this process can write the same status path at once
# (e.g. overlapping FastAPI control requests dispatched through a
# threadpool), and a shared temp name would let one writer's os.replace
# yank the file from under another.
write_atomic(Path(path), json.dumps(payload, indent=2))
def read_json(path):
if not path.exists():
return None
try:
return json.loads(path.read_text(encoding="utf-8"))
except (json.JSONDecodeError, OSError):
# Status files are best-effort: a partially written or corrupted
# payload should not break write_status() or read_status().
return None
def get_restart_status_path() -> Path:
return paths.get_runtime_restart_status_path()
def get_service_lock_path() -> Path:
return paths.get_runtime_service_lock_path()
def _lock_file_pid(lock_file) -> int | None:
try:
lock_file.seek(0)
payload = json.loads(lock_file.read() or "{}")
except (OSError, json.JSONDecodeError, TypeError):
return None
pid = payload.get("pid") if isinstance(payload, dict) else None
return pid if isinstance(pid, int) and pid > 0 else None
# The byte this file's lock lives on, on Windows only.
#
# Windows byte-range locks are mandatory and scoped to a HANDLE, not a process:
# an exclusive lock denies every other handle -- including a second handle this
# same process opens -- both read and write access to the locked range. This
# lock file is also the record naming its holder, so locking the bytes the
# record occupies hid that record for exactly as long as the lock meant
# anything, and every reader below treats an unreadable record as "nobody holds
# this". Locking past end-of-file is legal, costs no disk and does not extend
# the file, so a byte out here still names this file while leaving every byte
# anyone reads unlocked. It sits far beyond any record this writes.
#
# POSIX keeps its whole-file advisory ``flock``: it never denied a read, so it
# has no defect to fix and an installed base that must keep excluding today's
# releases.
_WINDOWS_LOCK_BYTE_OFFSET = 1 << 30
def _windows_lock_byte(lock_file, mode: int) -> None:
"""Take or drop the Windows lock byte, leaving the handle where it was.
``msvcrt.locking`` locks ``nbytes`` from the descriptor's CURRENT position,
so the offset has to be applied to the raw descriptor -- a text handle
cannot seek to an arbitrary byte. Restoring position 0 afterwards keeps the
buffered handle coherent for the record write and read that follow.
"""
import msvcrt
os.lseek(lock_file.fileno(), _WINDOWS_LOCK_BYTE_OFFSET, os.SEEK_SET)
try:
msvcrt.locking(lock_file.fileno(), mode, 1)
finally:
lock_file.seek(0)
# What a non-blocking lock attempt fails with when another handle holds the lock.
_LOCK_HELD_ERRNOS = frozenset({errno.EACCES, errno.EDEADLK} if os.name == "nt" else {errno.EAGAIN, errno.EWOULDBLOCK})
def _take_lock_file(lock_file) -> bool:
"""False when another handle holds the lock; raises ``OSError`` when the attempt itself failed."""
try:
if os.name == "nt":
import msvcrt
_windows_lock_byte(lock_file, msvcrt.LK_NBLCK)
else:
import fcntl
fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
except OSError as exc:
if exc.errno in _LOCK_HELD_ERRNOS:
return False
raise
return True
# How long a service lock that no live service holds may take to come free.
#
# Holding the lock is how a service says it is running, but it is not the only
# way the lock gets held. It cannot be tested without being taken -- a Windows
# byte-range lock has no other test -- so every check holds it for an instant,
# and `vibe start` checks it every 100 ms while it waits for the service it
# launched. A service whose single attempt landed in one of those instants
# took the check for another service and exited. A holder that is gone can
# also keep it a while: Windows releases a terminated process's locks only as
# its resources allow. Neither names a live process in the record, which a
# service writes the moment it takes the lock, so only that state is waited
# out, and only this long; a live holder is answered at once.
#
# Only a start or a stop waits: the service taking the lock, a launcher
# deciding whether one already runs, and `vibe stop` deciding whether anything
# still holds it. Every other check answers from a single attempt, because
# the service asks some of them on its event loop, where a wait stalls every
# turn and lane behind it.
_SERVICE_LOCK_SETTLE_SECONDS = 2.0
_SERVICE_LOCK_SETTLE_INTERVAL_SECONDS = 0.02
def _lock_file_names_live_holder(lock_file) -> bool:
"""Whether the record names a process that is running and is the one that wrote it.
A record outlives its holder when a service is killed or the machine stops,
and its pid can pass to an unrelated process. The holder's start token,
written beside the pid, tells the two apart. A record without one, as an
older release writes it, cannot be told apart and names no one: a holder
that wrote it keeps the lock, and is refused once the wait runs out.
"""
pid = _lock_file_pid(lock_file)
if pid is None or not pid_alive(pid):
return False
try:
lock_file.seek(0)
start_token = json.loads(lock_file.read() or "{}").get("start_token")
except (OSError, json.JSONDecodeError, TypeError, AttributeError):
return False
return isinstance(start_token, str) and process_start_token(pid) == start_token
def _take_service_lock(lock_file) -> bool:
"""Take the service lock unless a service holds it; raises ``OSError`` when an attempt itself failed.
False when the record names a live holder, or when the lock stays held for
``_SERVICE_LOCK_SETTLE_SECONDS`` with none named.
"""
deadline = time.monotonic() + _SERVICE_LOCK_SETTLE_SECONDS
while not _take_lock_file(lock_file):
if _lock_file_names_live_holder(lock_file) or time.monotonic() >= deadline:
return False
time.sleep(_SERVICE_LOCK_SETTLE_INTERVAL_SECONDS)
return True
def _try_lock_file(lock_file, *, settle: bool = False) -> bool:
try:
return _take_service_lock(lock_file) if settle else _take_lock_file(lock_file)
except OSError:
return False
def _unlock_file(lock_file) -> None:
if os.name == "nt":
import msvcrt
try:
_windows_lock_byte(lock_file, msvcrt.LK_UNLCK)
except OSError:
logger.debug("Failed to unlock service instance lock", exc_info=True)
return
import fcntl
try:
fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
except OSError:
logger.debug("Failed to unlock service instance lock", exc_info=True)
def acquire_service_instance_lock() -> None:
"""Acquire the data-dir scoped service runtime lock for this process lifetime."""
global _SERVICE_INSTANCE_LOCK_HANDLE, _SERVICE_INSTANCE_LOCK_OWNER_PID
if _SERVICE_INSTANCE_LOCK_HANDLE is not None:
return
ensure_dirs()
lock_path = get_service_lock_path()
lock_path.parent.mkdir(parents=True, exist_ok=True)
lock_file = lock_path.open("a+", encoding="utf-8")
if not _try_lock_file(lock_file, settle=True):
holder_pid = _lock_file_pid(lock_file)
lock_file.close()
raise ServiceAlreadyRunningError(lock_path=lock_path, holder_pid=holder_pid)
_write_service_instance_lock_record(lock_file, SERVICE_PHASE_STARTING)
paths.get_runtime_pid_path().write_text(str(os.getpid()), encoding="utf-8")
_SERVICE_INSTANCE_LOCK_HANDLE = lock_file
_SERVICE_INSTANCE_LOCK_OWNER_PID = os.getpid()
def _write_service_instance_lock_record(lock_file, phase: str) -> None:
lock_file.seek(0)
lock_file.truncate()
lock_file.write(
json.dumps(
{
"pid": os.getpid(),
"instance_id": uuid.uuid4().hex,
"created_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
"started_at": process_create_time(os.getpid()),
"start_token": process_start_token(os.getpid()),
"phase": phase,
"command": get_process_command(os.getpid()),
},
indent=2,
)
)
lock_file.flush()
try:
os.fsync(lock_file.fileno())
except OSError:
logger.debug("Failed to fsync service instance lock", exc_info=True)
def mark_service_instance_started() -> None:
"""Record that this service is past startup and into its normal life.
Called once the database is migrated and the controller is built -- the last
point at which a new release can still fail structurally, and so the first
point at which "the upgrade worked" is a statement about anything. Whoever
started this process is waiting on exactly this write; until it lands, a
watcher only knows the lock was taken.
Rewrites the record through the handle that holds the lock, so the fact and
the lock cannot come apart: the kernel drops the lock when this process dies,
taking the claim with it.
"""
lock_file = _SERVICE_INSTANCE_LOCK_HANDLE
if lock_file is None:
return
_write_service_instance_lock_record(lock_file, SERVICE_PHASE_RUNNING)
global _PENDING_SQLITE_BACKUP_READINESS
try:
from alembic.script import ScriptDirectory
from storage.importer import validated_sqlite_backup_attempt
from storage.migrations import alembic_config
target = paths.get_sqlite_state_path()
attempt = validated_sqlite_backup_attempt(target)
if attempt is not None and _PENDING_SQLITE_BACKUP_READINESS is None:
_PENDING_SQLITE_BACKUP_READINESS = (
target,
attempt,
tuple(ScriptDirectory.from_config(alembic_config(target)).get_heads()),
datetime.now(timezone.utc),
)
confirm_pending_sqlite_backup_readiness()
except Exception:
# Missing expiry evidence retains the bounded rollback window. Optional
# maintenance must not turn an otherwise ready service into a failed one.
logger.warning("Could not confirm SQLite backup expiry readiness; retaining backups", exc_info=True)
def confirm_pending_sqlite_backup_readiness() -> None:
"""Retry only this service's observed readiness, preserving its original clock."""
global _PENDING_SQLITE_BACKUP_READINESS
pending = _PENDING_SQLITE_BACKUP_READINESS
if pending is None or not current_process_owns_service_instance() or not service_instance_started(os.getpid()):
return
from storage.backups import confirm_sqlite_backup_readiness
target, attempt, revisions, ready_at = pending
confirm_sqlite_backup_readiness(
target, attempt_id=attempt, expected_revisions=revisions, now=ready_at
)
# A busy lock raises and keeps the pending event. A false result means this
# exact attempt is no longer eligible; never adopt another process's attempt.
if _PENDING_SQLITE_BACKUP_READINESS is pending:
_PENDING_SQLITE_BACKUP_READINESS = None
def read_service_instance_lock_record() -> dict | None:
"""The service lock record as written by its holder, or None if unreadable."""
try:
payload = json.loads(get_service_lock_path().read_text(encoding="utf-8") or "{}")
except (OSError, json.JSONDecodeError, TypeError, ValueError):
return None
return payload if isinstance(payload, dict) else None
def service_instance_started(pid: int) -> bool:
"""Whether the service running as ``pid`` has reported it finished starting.
Keyed on the pid, because the record is the one thing here the holder does not
write atomically with the lock: between taking the lock and rewriting the
record, the file still holds whatever the PREVIOUS holder last said, and that
is a finished startup. The previous holder's pid is in it too, so requiring
the two to agree is what keeps a departed instance's record from answering for
this one.
A release that predates the phase distinction wrote ``running`` when it took
the lock, so it reads as started immediately. That is the behavior this
replaced, kept deliberately: it is what a rollback target on an older version
can offer, and demanding a write it will never make would turn every rollback
into a reported failure.
"""
record = read_service_instance_lock_record()
if record is None:
return False
return record.get("pid") == pid and record.get("phase") == SERVICE_PHASE_RUNNING
def service_instance_still_starting(pid: int) -> bool:
"""Whether ``pid``'s own record says it is still on its way up.
The mirror of :func:`service_instance_started`, and deliberately not its
negation. That one asks whether a new generation PROVED it works, so a
missing or unreadable record has to count as no proof. This one is read by
everything that reports a state word to a human, where the same absence means
only that nothing here knows -- and answering ``starting`` on no evidence
would leave a service whose lock record was lost looking stuck forever.
So only the holder's own record, naming this pid and this phase, moves the
word off ``running``. Anything less says what it has always said.
"""
record = read_service_instance_lock_record()
if record is None:
return False
return record.get("pid") == pid and record.get("phase") == SERVICE_PHASE_STARTING
def release_service_instance_lock() -> None:
global _SERVICE_INSTANCE_LOCK_HANDLE, _SERVICE_INSTANCE_LOCK_OWNER_PID, _PENDING_SQLITE_BACKUP_READINESS
_PENDING_SQLITE_BACKUP_READINESS = None
lock_file = _SERVICE_INSTANCE_LOCK_HANDLE
if lock_file is None:
return
_SERVICE_INSTANCE_LOCK_HANDLE = None
_SERVICE_INSTANCE_LOCK_OWNER_PID = None
try:
try:
paths.get_runtime_pid_path().unlink(missing_ok=True)
except OSError:
logger.debug("Failed to remove service pid file while releasing lock", exc_info=True)
try:
lock_file.seek(0)
lock_file.truncate()
lock_file.flush()
except OSError:
logger.debug("Failed to truncate service instance lock", exc_info=True)
_unlock_file(lock_file)
finally:
lock_file.close()
def service_instance_lock_available(*, settle: bool = False) -> tuple[bool, int | None]:
"""Return whether the data-dir scoped service lock can be acquired.
``settle`` is for a caller deciding whether to start a service; see
``_SERVICE_LOCK_SETTLE_SECONDS``. It may wait, so nothing on an event loop
passes it.
"""
ensure_dirs()
lock_path = get_service_lock_path()
lock_path.parent.mkdir(parents=True, exist_ok=True)
lock_file = lock_path.open("a+", encoding="utf-8")
try:
if _try_lock_file(lock_file, settle=settle):
_unlock_file(lock_file)
return True, None
return False, _lock_file_pid(lock_file)
finally:
lock_file.close()
def service_lock_holder_pid() -> int | None:
available, holder_pid = service_instance_lock_available()
if available:
return None
return holder_pid
def current_process_owns_service_instance() -> bool:
"""Return whether this process is still the active service owner.
Controller-owned background services capture whether they require this gate
at construction time. A real service process constructs them only after
acquiring the lock, so losing this handle later means the process must stop
scheduling work.
It is answered from the handle this process holds, and so asked freely on
the event loop: no lock is taken and nothing waits. The lease is gone once
the handle is released, in a child that inherited it, or when the file it
locks is no longer the one at the lock path -- removed or replaced, so that
another service could lock the new one.
"""
lock_file = _SERVICE_INSTANCE_LOCK_HANDLE
if lock_file is None or _SERVICE_INSTANCE_LOCK_OWNER_PID != os.getpid():
return False
try:
held = os.fstat(lock_file.fileno())
current = os.stat(get_service_lock_path())
except (OSError, ValueError):
return False
return (held.st_dev, held.st_ino) == (current.st_dev, current.st_ino)
def service_instance_lock_attached_to_process() -> bool:
return _SERVICE_INSTANCE_LOCK_HANDLE is not None
def get_shutdown_intent_path() -> Path:
return paths.get_runtime_dir() / "shutdown_intent.json"
def write_shutdown_intent(
target_pid: int,
*,
signum: int = signal.SIGTERM,
reason: str = "managed-stop",
) -> None:
"""Record a short-lived intent before sending a managed shutdown signal."""
if not isinstance(target_pid, int) or target_pid <= 0:
return
payload = {
"target_pid": target_pid,
"signum": int(signum),
"reason": reason,
"created_at": time.time(),
"sender_pid": os.getpid(),
"sender_command": get_process_command(os.getpid()),
"target_command": get_process_command(target_pid),
}
try:
write_json(get_shutdown_intent_path(), payload)
logger.info("Recorded managed shutdown intent: %s", payload)
except OSError:
logger.warning("Failed to write shutdown intent for pid=%s", target_pid, exc_info=True)
def consume_shutdown_intent(target_pid: int, signum: int = signal.SIGTERM) -> dict | None:
"""Return and remove a valid managed shutdown intent for this process."""
path = get_shutdown_intent_path()
payload = read_json(path)
if not isinstance(payload, dict):
return None
try:
age = time.time() - float(payload.get("created_at", 0))
matches = (
payload.get("target_pid") == target_pid
and int(payload.get("signum", 0)) == int(signum)
and 0 <= age <= SHUTDOWN_INTENT_TTL_SECONDS
)
except (TypeError, ValueError):
matches = False
if not matches:
return None
try:
path.unlink(missing_ok=True)
except OSError:
logger.debug("Failed to remove consumed shutdown intent", exc_info=True)
return payload
def shutdown_intent_required() -> bool:
return os.environ.get(SHUTDOWN_INTENT_ENV, "").lower() in {"1", "true", "yes"}
def _pid_alive_windows(pid: int) -> bool:
if pid <= 0:
return False
try:
import ctypes
kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
synchronize = 0x00100000
query_limited_information = 0x1000
still_active = 259
handle = kernel32.OpenProcess(synchronize | query_limited_information, False, pid)
if not handle:
last_error = ctypes.get_last_error()
# Access denied still means the process exists.
if last_error == 5:
return True
return False
try:
exit_code = ctypes.c_ulong()
if not kernel32.GetExitCodeProcess(handle, ctypes.byref(exit_code)):
return False
return exit_code.value == still_active
finally:
kernel32.CloseHandle(handle)
except Exception:
logger.debug("Windows pid_alive probe failed for pid=%s", pid, exc_info=True)
return False
def _terminate_process_windows(pid: int, timeout: float = 5) -> bool:
if pid <= 0:
return False
try:
import ctypes
kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
synchronize = 0x00100000
query_limited_information = 0x1000
process_terminate = 0x0001
wait_object_0 = 0
handle = kernel32.OpenProcess(
synchronize | query_limited_information | process_terminate,
False,
pid,
)
if not handle:
return not _pid_alive_windows(pid)
try:
if not kernel32.TerminateProcess(handle, 1):
return False
timeout_ms = max(0, int(timeout * 1000))
wait_result = kernel32.WaitForSingleObject(handle, timeout_ms)
return wait_result == wait_object_0
finally:
kernel32.CloseHandle(handle)
except Exception:
logger.debug("Windows process termination failed for pid=%s", pid, exc_info=True)
return False
def get_process_command(pid: int) -> str | None:
"""The command line ``pid`` runs, or None when it cannot be read.
psutil reads it in this process. A ``ps`` or PowerShell child per lookup
took seconds on Windows, and failed outright where a setuid ``ps`` cannot
run, as under a macOS sandbox: there a start could not tell the recorded
UI from another program and replaced it, orphaning the UI still serving.
Only another user's process, which psutil may not read on macOS, still
asks ``ps``; on Windows such a process reads as None.
"""
if not isinstance(pid, int) or pid <= 0:
return None
try:
argv = psutil.Process(pid).cmdline()
except psutil.AccessDenied:
return None if os.name == "nt" else _get_process_command_from_ps(pid)
except psutil.Error:
return None
if not argv:
return None
return subprocess.list2cmdline(argv) if os.name == "nt" else shlex.join(argv)
def _get_process_command_from_ps(pid: int) -> str | None:
try:
result = subprocess.run(
["ps", "-p", str(pid), "-o", "command="],
capture_output=True,
text=True,
check=False,
)
except Exception:
return None
command = (getattr(result, "stdout", "") or "").strip()
return command or None
def pid_alive(pid):
if not isinstance(pid, int) or pid <= 0:
return False
if os.name == "nt":
return _pid_alive_windows(pid)
try:
os.kill(pid, 0)
except ProcessLookupError:
return False
except PermissionError:
return True
except (OSError, ValueError, SystemError):
return False
try:
status = psutil.Process(pid).status()
except psutil.NoSuchProcess:
return False
except psutil.AccessDenied:
return True
except psutil.Error:
return True
dead_statuses = {psutil.STATUS_ZOMBIE}
status_dead = getattr(psutil, "STATUS_DEAD", None)
if status_dead is not None:
dead_statuses.add(status_dead)
return status not in dead_statuses
def process_create_time(pid: int) -> float | None:
"""Wall-clock start time of a process, or ``None`` if it can't be read.
Used to tell a recorded pid apart from an unrelated process that later reused
the same pid (notably across a reboot): a reused pid has a different start
time, so ``(pid, create_time)`` identifies the original process.
"""
try:
return float(psutil.Process(pid).create_time())
except (psutil.Error, ValueError, TypeError):
return None
@lru_cache(maxsize=1)
def _linux_boot_id() -> str | None:
try:
boot_id = Path("/proc/sys/kernel/random/boot_id").read_text(encoding="utf-8").strip()
except OSError:
return None
return boot_id or None
def process_start_token(pid: int) -> str | None:
"""When a process started, as a value no clock adjustment changes; None if it cannot be read.
This is the one identity of a running process: a recorded ``(pid, token)``
still names the same execution after the wall clock or the boot time moves,
or the machine reboots, and never names a process that later reused the
pid. A token is returned only when every part of it was read; otherwise
None, which every caller treats as unverifiable.
- Linux counts a process's start in clock ticks since boot (field 22 of
``/proc/<pid>/stat``). psutil turns that into wall-clock time through the
boot time, which moves whenever the clock is stepped -- by a VM's time
sync, a WSL2 resume, NTP catching up after boot. The ticks, with the boot
they count from, do not move. Ticks restart at every boot, so without
the boot id there is no token.
- macOS (and NetBSD) store the wall-clock time a process started, but
psutil's ``create_time()`` adds the change in whole seconds of
``kern.boottime`` since psutil was imported, and the system time daemon
moves ``kern.boottime`` in routine adjustments. The same process then
reads a second later or earlier, and differently in two processes that
imported psutil at different times. The stored value is what psutil
itself uses for process identity (``Process._get_ident``), through
``create_time(monotonic=True)``. That accessor is private, so a psutil
without it reads as None.
- Windows stores the creation time with the process, and psutil reads it
back unchanged.
- Elsewhere (FreeBSD, OpenBSD, ...) the start psutil reads moves with
system clock updates, as psutil itself warns, and no stable one is
available: no process there has a token, so a record of one is
unverifiable.
"""
if sys.platform.startswith("linux"):
try:
ticks = Path(f"/proc/{pid}/stat").read_text(encoding="utf-8").rsplit(")", 1)[1].split()[19]
except (OSError, IndexError, ValueError):
return None
boot_id = _linux_boot_id()
if boot_id is None or not ticks.isdigit():
return None
return f"{boot_id}:{ticks}"
monotonic = sys.platform == "darwin" or sys.platform.startswith("netbsd")
if not monotonic and sys.platform != "win32":
return None
try:
process = psutil.Process(pid)
start = process._proc.create_time(monotonic=True) if monotonic else process.create_time()
return repr(float(start))
except (psutil.Error, AttributeError, TypeError, ValueError, OSError):
return None
def process_start_seconds(pid: int) -> float | None:
"""When a process started, as the platform's own tools print it; None if it cannot be read.
This is a wall-clock time, so it is never an identity on its own: it is what
``ps -o lstart`` shows, which records written before start tokens carry.
Linux computes it from the boot time and the start ticks, as procps does, and
macOS keeps the wall-clock time the process started, which psutil reads back
unadjusted through ``create_time(monotonic=True)``.
"""
try:
process = psutil.Process(pid)
if sys.platform == "darwin" or sys.platform.startswith("netbsd"):
return float(process._proc.create_time(monotonic=True))
return float(process.create_time())
except (psutil.Error, AttributeError, TypeError, ValueError, OSError):
return None
def process_age_seconds(pid: int) -> float | None:
"""How long a process has run; None if it cannot be read.
Linux counts it from the boot, in the same ticks the start is recorded in,
so a step of the wall clock does not change it. Elsewhere it is the wall
clock's distance from the start.
"""
if sys.platform.startswith("linux"):
try:
ticks = int(Path(f"/proc/{pid}/stat").read_text(encoding="utf-8").rsplit(")", 1)[1].split()[19])
uptime = float(Path("/proc/uptime").read_text(encoding="utf-8").split()[0])
return max(0.0, uptime - ticks / os.sysconf("SC_CLK_TCK"))
except (OSError, IndexError, ValueError):
return None
try:
return max(0.0, time.time() - float(psutil.Process(pid).create_time()))
except (psutil.Error, TypeError, ValueError, OSError):
return None
def _safe_resolve_path(value: str | Path) -> Path | None:
try:
return Path(value).expanduser().resolve()
except (OSError, RuntimeError, ValueError):
return None
def _path_is_service_entry(path: Path, current_main: Path | None) -> bool:
resolved = _safe_resolve_path(path)
if current_main is not None and resolved == current_main:
return True
if path.name == "service_main.py":
parent = resolved.parent if resolved is not None else path.parent
return parent.name == "vibe" and (parent / "runtime.py").exists()
if path.name == "main.py":
root = resolved.parent if resolved is not None else path.parent
return (root / "vibe" / "runtime.py").exists() and (root / "core" / "controller.py").exists()
return False
def _systemd_scope_target_argv(args: list[str]) -> list[str] | None:
if not args:
return None
executable_name = Path(args[0].strip("\"'")).name.lower()
if executable_name != "systemd-run":
return None
try:
separator = args.index("--")
except ValueError:
return None
if "--scope" not in args[1:separator]:
return None
target = args[separator + 1 :]
return target or None
def _service_entry_arg_from_argv(args: list[str]) -> str | None:
if not args:
return None
executable_name = Path(args[0].strip("\"'")).name.lower()
scope_target = _systemd_scope_target_argv(args)
if scope_target is not None:
return _service_entry_arg_from_argv(scope_target)
if executable_name.startswith("python"):
for arg in args[1:]:
cleaned_arg = arg.strip("\"'")
if cleaned_arg in {"-c", "-m"}:
return None
if cleaned_arg.startswith("-"):
continue
return cleaned_arg
return None
if Path(args[0].strip("\"'")).name in {"main.py", "service_main.py"}:
return args[0].strip("\"'")
return None
def _command_looks_like_service_entry(
command: str | None,
*,
cwd: str | None = None,
include_scope_wrapper: bool = True,
) -> bool:
if not command:
return False
try:
args = shlex.split(command, posix=(os.name != "nt"))
except ValueError:
return False
if not include_scope_wrapper and _systemd_scope_target_argv(args) is not None:
return False
current_main = _safe_resolve_path(get_service_main_path())
cwd_path = _safe_resolve_path(cwd) if cwd else None
entry_arg = _service_entry_arg_from_argv(args)
if not entry_arg:
return False
path = Path(entry_arg)
if not path.is_absolute() and cwd_path is not None:
path = cwd_path / path
return _path_is_service_entry(path, current_main)
def _process_is_service_session_leader(pid: int) -> bool:
if os.name == "nt":
return True
try:
return os.getsid(pid) == pid
except OSError:
return False
def _process_command_from_info(proc) -> str | None:
"""Name a scanned process from what psutil already collected, or not at all.
This is asked for every process on the machine, so it has to be cheap. It
used to fall back to `get_process_command`, which on Windows then launched
`powershell -Command Get-CimInstance ...` -- and a second `pwsh` when the
first says nothing -- once per process. A per-process external shell inside
a whole-machine walk is invisible on Linux, where that fallback is a /proc
read, and on Windows it is a `vibe stop` that prints nothing and never
returns. That is how gh-v3.1.1rc10 died.
Nothing is lost by stopping here. The scan looks for lock-less Avibe
daemons; those are processes this install started, whose command line
psutil can read. One it cannot read is by construction not ours, and the
authoritative owner comes from the service lock rather than from this scan.
"""
info = getattr(proc, "info", {}) or {}
cmdline = info.get("cmdline")
if cmdline:
return shlex.join(str(part) for part in cmdline if str(part))
return None
def _process_cwd(proc) -> str | None:
try:
return proc.cwd()
except (psutil.Error, OSError, AttributeError):
return None
def _process_home_matches_current(proc) -> bool | None:
current_home = _safe_resolve_path(paths.get_vibe_remote_dir())
if current_home is None:
return None
try:
env = proc.environ()
except (psutil.Error, OSError, AttributeError):
return None
explicit_home = env.get(paths.AVIBE_HOME_ENV)
if explicit_home:
return _safe_resolve_path(explicit_home) == current_home
has_avibe_marker = str(env.get(SHUTDOWN_INTENT_ENV) or "").lower() in {"1", "true", "yes"}
has_avibe_marker = has_avibe_marker or str(env.get("VIBE_DISABLE_STDOUT_LOGGING") or "").lower() in {
"1",
"true",
"yes",
}
if not has_avibe_marker:
return None
home = env.get("HOME")
if not home:
return None
candidates = [
Path(home) / paths.AVIBE_HOME_DIRNAME,
Path(home) / paths.LEGACY_HOME_DIRNAME,
]
return any(_safe_resolve_path(candidate) == current_home for candidate in candidates)
def service_processes(*, include_unverified: bool = False) -> list[dict]:
"""Return Avibe service processes associated with the current data dir.
The service lock remains the authoritative owner signal. This process scan is
deliberately secondary: it detects extra lock-less daemons left behind by
older lifecycle bugs, but only treats a process as actionable when its
command looks like Avibe's service entry point and its environment maps to
the current AVIBE_HOME. Do not require session leadership here: legacy and
container launchers may background ``python main.py`` from a shell without
creating a new session, and those lock-less services still need recovery.
"""
processes: list[dict] = []
try:
iterator = psutil.process_iter(attrs=["pid", "cmdline"])
except psutil.Error:
return processes
for proc in iterator:
info = getattr(proc, "info", {}) or {}
pid = info.get("pid")
if not isinstance(pid, int) or pid <= 0 or pid == os.getpid():
continue
try:
alive = pid_alive(pid)
except Exception as exc:
logger.warning("Failed to inspect possible service process pid=%s: %s", pid, exc)
continue
if not alive:
continue
session_leader = _process_is_service_session_leader(pid)
command = _process_command_from_info(proc)
if not _command_looks_like_service_entry(
command,
cwd=_process_cwd(proc),
include_scope_wrapper=False,
):
continue
lock_owner = service_lock_held_by(pid)
home_match = _process_home_matches_current(proc)
if not (lock_owner or home_match is True or (include_unverified and home_match is None)):
continue
processes.append(
{
"pid": pid,
"command": command,
"lock_owner": lock_owner,
"home_match": home_match,
"session_leader": session_leader,
}
)
return processes
def extra_service_process_pids(owner_pid: int | None = None, *, include_unverified: bool = False) -> list[int]:
pids: list[int] = []
for process in service_processes(include_unverified=include_unverified):
pid = process.get("pid")
if not isinstance(pid, int) or pid == owner_pid:
continue
if include_unverified or process.get("home_match") is True or process.get("lock_owner") is True:
pids.append(pid)
return sorted(set(pids))
def service_process_running() -> bool:
return resolve_service_owner_pid(include_starting=False) is not None or bool(extra_service_process_pids())
def verified_service_running() -> bool:
"""Report whether a service holding the service lock is running.
``service_process_running`` answers a different question -- whether anything at
all occupies this data dir -- and ``start_service`` is right to ask that one,
because a half-started child must still block a second start. Deciding whether
the instance has a working service needs the narrower fact: a process that
reserved the pid and never acquired the lock is not a service, it is a failed
start, and a restart record describing that failure must not be demoted to
history because the wreckage is still running.
That argument does not stop at the lock, and this function used to. A process
that acquired the lock and never finished starting is not a working service
either -- it is the same failed start one step further along, since the lock is
taken BEFORE the database is migrated and the controller built. So the holder
must also have published ``SERVICE_PHASE_RUNNING``. Without that, a release
that hangs in its migration holds the lock forever and reads as healthy, which
is precisely the state the upgrade rollback exists to end.
A dead holder cannot keep the lock, since the kernel drops it when the process
goes, so liveness needs no separate check beyond that.
This is the one owner of "does this instance have a working service".
``service_instance_lock_available`` owns the different question ``start_service``
asks -- whether anything at all would block a second start -- and callers must
not mix them: a holder mid-startup blocks a start AND is not yet running, and
both answers are correct for their own question.
Cheap by construction: one open, one non-blocking lock attempt, and one small
read, and unlike the broader probe it never scans the process table.
"""
lock_available, holder_pid = service_instance_lock_available()
if lock_available:
return False
return holder_pid is not None and service_instance_started(holder_pid)
def _pid_reservation_is_fresh(pid_path: Path, pid: int, *, max_age: float = SERVICE_SLOW_START_TIMEOUT_SECONDS) -> bool:
try:
pidfile_mtime = pid_path.stat().st_mtime
except OSError:
return False
create_time = process_create_time(pid)
latest_signal = max(pidfile_mtime, create_time or 0)
return time.time() - latest_signal <= max_age
def stop_pid(pid: int, timeout: float = 5, *, shutdown_reason: str = "stop_pid") -> bool:
if not isinstance(pid, int) or pid <= 0:
return False
if not pid_alive(pid):
return False
if os.name == "nt":
return _terminate_process_windows(pid, timeout=timeout)
write_shutdown_intent(pid, signum=signal.SIGTERM, reason=shutdown_reason)
try:
logger.info(
"Sending managed SIGTERM to pid=%s command=%s",
pid,
get_process_command(pid),
)
os.kill(pid, signal.SIGTERM)
except ProcessLookupError:
return False
except PermissionError:
return False
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
if not pid_alive(pid):
return True
time.sleep(0.2)
try:
logger.warning("Sending managed SIGKILL to pid=%s command=%s", pid, get_process_command(pid))
os.kill(pid, signal.SIGKILL)
except ProcessLookupError:
return True
except OSError:
return False
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
if not pid_alive(pid):
return True
time.sleep(0.2)
logger.error("Managed SIGKILL did not terminate pid=%s command=%s", pid, get_process_command(pid))
return False
def _log_path(name: str) -> Path:
return paths.get_runtime_dir() / name
def _spawn_runtime_log_sink(path: Path) -> subprocess.Popen:
return subprocess.Popen(
[
sys.executable,
"-m",
"vibe.log_sink",
str(path),
"--max-bytes",
str(RUNTIME_LOG_MAX_BYTES),
"--retain-bytes",
str(RUNTIME_LOG_RETAIN_BYTES),
],
stdin=subprocess.PIPE,
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
cwd=str(get_working_dir()),
close_fds=True,
**isolated_subprocess_kwargs(console=False),
)
def _spawn_runtime_log_sinks(stdout_path: Path, stderr_path: Path) -> tuple[subprocess.Popen, subprocess.Popen]:
stdout_sink = _spawn_runtime_log_sink(stdout_path)
try:
stderr_sink = _spawn_runtime_log_sink(stderr_path)
except Exception:
if stdout_sink.stdin is not None:
stdout_sink.stdin.close()
raise
if stdout_sink.stdin is None or stderr_sink.stdin is None:
if stdout_sink.stdin is not None:
stdout_sink.stdin.close()
if stderr_sink.stdin is not None:
stderr_sink.stdin.close()
raise RuntimeError("Failed to create runtime log sink pipes")
return stdout_sink, stderr_sink
def independent_process_env(
env: dict[str, str] | None,
) -> dict[str, str]:
"""Build the environment for a process Avibe owns, not one it runs for a caller.
The service, the UI server, the connector and the restart supervisor all
outlive the call that started them and act as the installation. The caller
provenance the current process may be carrying belongs to that call, so it
stops here — the child's own entry point is Owner work and would refuse it
anyway. ``None`` is materialized rather than passed through to ``Popen``,
because an implicit inherit would carry the caller across too.
"""
from core.caller_context import environment_without_caller_context
child_env = environment_without_caller_context(env)
return child_env
#: How long a child that was killed because its spawn failed is waited for.
#: SIGKILL and TerminateProcess are not refusable, so this only bounds a kernel
#: that is slow to deliver them.
SPAWN_DISCARD_REAP_TIMEOUT_SECONDS = 5.0
def discard_spawned_child(process: subprocess.Popen) -> None:
"""Kill and reap a child whose handover to its caller failed.
Called from inside an ``except`` that re-raises, so it must not replace the
failure it is cleaning up after: anything it cannot do is logged instead.
"""
try:
process.kill()
except OSError:
logger.error("Failed to kill pid=%s after its spawn failed", process.pid, exc_info=True)
return
try:
process.wait(timeout=SPAWN_DISCARD_REAP_TIMEOUT_SECONDS)
except subprocess.TimeoutExpired:
logger.error(
"Killed pid=%s after its spawn failed, but it had not exited after %.0fs",
process.pid,
SPAWN_DISCARD_REAP_TIMEOUT_SECONDS,
)
def _spawn_owned_process(
args,
stdout_name: str,
stderr_name: str,
env: dict[str, str] | None,
*,
hand_over: Callable[[subprocess.Popen], None] | None = None,
withdraw: Callable[[int], None] | None = None,
) -> subprocess.Popen:
"""Start a process the caller owns, or leave no process at all.
A caller can only undo what it knows about. Every step between ``Popen``
and the moment the caller knows -- closing the parent's copies of the
child's handles, the pid record that lets any other process find it, the
caller's own note that it created the child -- used to be able to raise
with the child already running, and then no caller could see it:
`cmd_start`'s rollback looked for a UI it had created and found none, and
the orphan kept the listener every later start then failed to bind. So a
failure anywhere in that span kills and reaps the child before it
propagates, and every caller inherits the rule instead of each rolling back
a window it cannot observe.
``hand_over`` is the caller's side of that span: it records the child and
captures it as created, and it runs inside the guarded region so that
nothing is handed back half-owned. Once it returns, the caller's own
rollback can find the child. If the child is discarded instead,
``withdraw`` removes whatever part of that record already exists -- but
only once the child is known to be gone, so a child that could not be
reaped stays findable.
"""
stdout_path = _log_path(stdout_name)
stderr_path = _log_path(stderr_name)
stdout_path.parent.mkdir(parents=True, exist_ok=True)
stdout_sink, stderr_sink = _spawn_runtime_log_sinks(stdout_path, stderr_path)
stdin = open(os.devnull, "rb")
# The child holds its own copies of these once it starts; the parent's must
# still close, or a log sink never sees end-of-file.
parent_handles = [stdin, stdout_sink.stdin, stderr_sink.stdin]
process: subprocess.Popen | None = None
try:
process = subprocess.Popen(
args,
stdin=stdin,
stdout=stdout_sink.stdin,
stderr=stderr_sink.stdin,
cwd=str(get_working_dir()),
close_fds=True,
env=independent_process_env(env),
**isolated_subprocess_kwargs(console=False),
)
# Closing can fail too, so it happens inside this region and before the
# handover: once the caller owns the child, nothing here can raise.
_close_parent_handles(parent_handles)
if hand_over is not None:
hand_over(process)
except BaseException:
if process is not None:
discard_spawned_child(process)
if withdraw is not None and process.returncode is not None:
_withdraw_quietly(withdraw, process.pid)
_close_parent_handles(parent_handles, quietly=True)
raise
return process
def _withdraw_quietly(withdraw: Callable[[int], None], pid: int) -> None:
"""Remove a discarded child's record without replacing the failure being raised."""
try:
withdraw(pid)
except Exception:
logger.error("Failed to remove the record of discarded pid=%s", pid, exc_info=True)
def _close_parent_handles(handles: list, *, quietly: bool = False) -> None:
"""Close every handle, then raise the first failure unless ``quietly``.
Closing an already closed file is a no-op, so the failure path may call this
again after a close that raised part way through the list.
"""
first_failure: Exception | None = None
for handle in handles:
try:
handle.close()
except Exception as exc:
if quietly:
logger.debug("Failed to close a spawn handle after the spawn failed", exc_info=True)
elif first_failure is None:
first_failure = exc
if first_failure is not None:
raise first_failure
def spawn_background(
args,
pid_path,
stdout_name: str,
stderr_name: str,
env: dict[str, str] | None = None,
*,
start_info: ProcessStartInfo | None = None,
):
"""Start a process recorded in ``pid_path``; the record exists iff the child does.
With ``start_info`` the child is also captured as created before this
returns, inside the same guarded region: a caller that rolls back what
``start_info`` names cannot miss a child this started.
"""
def hand_over(process: subprocess.Popen) -> None:
# A reader never sees a half-written record: a full stop acts on it.
write_atomic(Path(pid_path), str(process.pid))
if start_info is not None:
start_info.capture(process.pid, reused=False)
return _spawn_owned_process(
args,
stdout_name,
stderr_name,
env,
hand_over=hand_over,
withdraw=lambda pid: _forget_pid_record(pid_path, pid),
).pid
def spawn_service_background_process(
args,
stdout_name: str,
stderr_name: str,
env: dict[str, str] | None = None,
*,
hand_over: Callable[[subprocess.Popen], None] | None = None,
withdraw: Callable[[int], None] | None = None,
) -> subprocess.Popen:
return _spawn_owned_process(
args,
stdout_name,
stderr_name,
env,
hand_over=hand_over,
withdraw=withdraw,
)
def spawn_service_background(args, stdout_name: str, stderr_name: str, env: dict[str, str] | None = None) -> int:
return spawn_service_background_process(args, stdout_name, stderr_name, env=env).pid
def _record_service_pid_reservation(pid: int) -> None:
pid_path = paths.get_runtime_pid_path()
pid_path.parent.mkdir(parents=True, exist_ok=True)
pid_path.write_text(str(pid), encoding="utf-8")
def _reap_service_start_process(pid: int) -> None:
process = _SERVICE_START_PROCESSES.pop(pid, None)
wait = getattr(process, "wait", None)
if not callable(wait):
return
def _wait() -> None:
try:
wait()
except Exception:
logger.debug("Failed to reap service launcher pid=%s", pid, exc_info=True)
threading.Thread(
target=_wait,
name=f"vibe-service-launcher-reaper-{pid}",
daemon=True,
).start()
def _clear_service_pid_reservation(pid: int) -> None:
_reap_service_start_process(pid)
_forget_pid_record(paths.get_runtime_pid_path(), pid)
def _forget_pid_record(pid_path: Path, pid: int) -> None:
"""Remove ``pid_path`` only while it still names ``pid``."""
if _read_pid_file(pid_path) == pid:
pid_path.unlink(missing_ok=True)
def _read_pid_file(pid_path: Path) -> int | None:
try:
pid = int(pid_path.read_text(encoding="utf-8").strip())
except (OSError, ValueError):
return None
return pid if pid > 0 else None
def service_lock_held_by(pid: int) -> bool:
lock_path = get_service_lock_path()
lock_path.parent.mkdir(parents=True, exist_ok=True)
lock_file = lock_path.open("a+", encoding="utf-8")
try:
if _try_lock_file(lock_file):
_unlock_file(lock_file)
return False
return _lock_file_pid(lock_file) == pid
finally:
lock_file.close()
def _service_start_exit_code(pid: int) -> int | None:
process = _SERVICE_START_PROCESSES.get(pid)
if process is None:
return None
exit_code = process.poll()
if exit_code is None:
return None
_clear_service_pid_reservation(pid)
return exit_code
def service_pid_recorded(pid: int) -> bool:
pid_path = paths.get_runtime_pid_path()
if not pid_path.exists():
return False
try:
recorded_pid = int(pid_path.read_text(encoding="utf-8").strip())
except (OSError, ValueError):
return False
return recorded_pid == pid and pid_alive(pid) and service_lock_held_by(pid)
def service_pid_file_points_to_running_service(pid_path: Path | None = None) -> bool:
pid = _read_pid_file(pid_path or paths.get_runtime_pid_path())
return bool(pid and service_pid_recorded(pid))
def _pid_alive_for_owner_resolution(pid: int) -> bool:
try:
return pid_alive(pid)
except Exception as exc:
logger.warning("Failed to inspect service owner pid=%s: %s", pid, exc)
return False
def resolve_service_owner_pid(*, include_starting: bool = True) -> int | None:
"""Resolve the live service owner for this data dir.
The flock in ``service.lock`` is the authoritative owner signal. The pidfile
is still useful for fast reuse and for a just-spawned service that has not
acquired the lock yet, but it must not be the only lifecycle source of truth.
"""
pid_path = paths.get_runtime_pid_path()
recorded_pid = _read_pid_file(pid_path)
if recorded_pid and _pid_alive_for_owner_resolution(recorded_pid):
if service_pid_recorded(recorded_pid):
return recorded_pid
available, lock_holder_pid = service_instance_lock_available()
if not available and lock_holder_pid and _pid_alive_for_owner_resolution(lock_holder_pid):
return lock_holder_pid
if include_starting and available and recorded_pid and _pid_alive_for_owner_resolution(recorded_pid):
if not _pid_mismatches_service(recorded_pid):
return recorded_pid
return None
def wait_for_service_pid(pid: int, timeout: float = SERVICE_LOCK_READY_TIMEOUT_SECONDS) -> bool:
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
if service_pid_recorded(pid):
_reap_service_start_process(pid)
return True
if _service_start_exit_code(pid) is not None:
return False
if not pid_alive(pid):
_clear_service_pid_reservation(pid)
return False
time.sleep(0.1)
ready = service_pid_recorded(pid)
if ready:
_reap_service_start_process(pid)
elif _service_start_exit_code(pid) is not None:
return False
return ready
def stop_process(pid_path, timeout=5, *, runtime_ids: frozenset[str] = frozenset(), part: str = "process"):
if not pid_path.exists():
return False
try:
pid = int(pid_path.read_text(encoding="utf-8").strip())
except (OSError, ValueError):
pid_path.unlink(missing_ok=True)
return False
if not pid_alive(pid):
pid_path.unlink(missing_ok=True)
return False
refuse_foreign_desktop_process(pid, part, runtime_ids)
stopped = stop_pid(pid, timeout=timeout)
if stopped:
pid_path.unlink(missing_ok=True)
else:
logger.error(
"Failed to stop pid=%s from %s; preserving pid file so future starts do not orphan it",
pid,
pid_path,
)
return stopped
def write_status(state, detail=None, service_pid=None, ui_pid=None):
now_iso = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
# Preserve started_at across consecutive "running" writes so the UI can
# show a stable service start time. Reset it on transitions in/out of
# running state, AND when the service PID has changed (e.g. a forced
# restart that goes running -> running but with a new process).
started_at = None
if state == "running":
previous = read_json(paths.get_runtime_status_path()) or {}
if (
previous.get("state") == "running"
and previous.get("started_at")
and previous.get("service_pid") == service_pid
):
started_at = previous["started_at"]
else:
started_at = now_iso
payload = {
"state": state,
"detail": detail,
"service_pid": service_pid,
"ui_pid": ui_pid,
"updated_at": now_iso,
}
if started_at:
payload["started_at"] = started_at
write_json(paths.get_runtime_status_path(), payload)
def read_status():
return read_json(paths.get_runtime_status_path()) or {}
def _pid_mismatches_service(pid: int) -> bool:
command = get_process_command(pid)
if not command:
logger.warning(
"Reusing existing service pid=%s because its command line could not be inspected",
pid,
)
return False
try:
cwd = psutil.Process(pid).cwd()
except (psutil.Error, OSError):
cwd = None
return not _command_looks_like_service_entry(command, cwd=cwd)
class ServiceState(NamedTuple):
"""What this data dir's service is doing right now."""
state: str
detail: str
service_pid: int | None
owner_pid: int | None
extra_pids: list[int]
@property
def running(self) -> bool:
return self.state in {"running", "degraded"}
def resolve_service_state(*, detect_extra_processes: bool = True) -> ServiceState:
"""The one answer to what state word describes this instance's service.
Everything that reports or records that word asks here, because the word is
the same fact each time and every place that derived it independently got the
same case wrong: the lock is taken BEFORE the database is migrated and the
controller is built, so its holder occupies this instance long before it can
serve anything. Reading that occupancy as `running` is how a release that
hung in its migration read as healthy for eight days with nobody served.
`starting` is therefore a state of its own rather than a shade of running:
something is here, it holds the lock, and it is not serving. `degraded` stays
what it was -- a service process holding no lock, which is a different fault
with a different repair.
Only a record that positively says so produces `starting`, never the absence
of one saying otherwise. This function reports; it does not adjudicate. A
machine that lost its lock record has a service on it either way, and telling
its owner it is starting -- forever, since nothing will ever write the record
it is waiting for -- trades a stuck instance that reads healthy for a healthy
instance that reads stuck.
"""
owner_pid = resolve_service_owner_pid(include_starting=False)
extra_pids: list[int] = []
if detect_extra_processes:
extra_pids = extra_service_process_pids(owner_pid=owner_pid)
if owner_pid:
detail = f"pid={owner_pid}"
if extra_pids:
detail = f"{detail}; extra_service_pids={','.join(str(pid) for pid in extra_pids)}"
if service_instance_still_starting(owner_pid):
return ServiceState("starting", f"{detail} has not finished starting", owner_pid, owner_pid, extra_pids)
return ServiceState("running", detail, owner_pid, owner_pid, extra_pids)
if extra_pids:
return ServiceState(
"degraded",
f"lockless service process detected pid={extra_pids[0]}",
extra_pids[0],
None,
extra_pids,
)
return ServiceState("stopped", "process not running", None, None, [])
def _starting_record_outlived_its_start(status: dict) -> bool:
"""Whether a persisted `starting` has outlived the start it describes.
`starting` survives a resolved `stopped` on purpose: between the spawn and
the moment the child takes the instance lock there is a window where nothing
resolves as running, and reporting that window as `stopped` would make every
healthy start look like a failure. But unlike `setup` and `error`, `starting`
is a claim about a process that is expected to arrive, so it holds only for
as long as that arrival is still possible. `wait_for_service_ready` gives up
after SERVICE_SLOW_START_TIMEOUT_SECONDS; past that same deadline a
`starting` record no longer describes a machine coming up, it describes one
that died on the way -- which is the exact failure this change exists to stop
reporting as healthy.
"""
updated_at = status.get("updated_at")
if not isinstance(updated_at, str):
return True
try:
written_at = calendar.timegm(time.strptime(updated_at, "%Y-%m-%dT%H:%M:%SZ"))
except (ValueError, TypeError):
# Every status write stamps `updated_at`, so a record without a readable
# one cannot be dated at all. Treat it as expired rather than as fresh:
# an undatable `starting` that is believed lasts forever, and the whole
# point of the deadline is that this state must not be permanent.
return True
return time.time() - written_at > SERVICE_SLOW_START_TIMEOUT_SECONDS
def render_status(*, detect_extra_processes: bool = True):
status = read_status()
resolved = resolve_service_state(detect_extra_processes=detect_extra_processes)
owner_pid = resolved.owner_pid
extra_pids = resolved.extra_pids
running = resolved.running
# A resolved `stopped` does not overwrite a persisted `setup`, `starting` or
# `error`: those describe a machine with nothing running on purpose, and this
# function reports what is running, not what was meant to. `starting` is the
# exception with a deadline -- see above -- because it is the only one of the
# three that describes something in flight.
overwritable = {"running", "degraded"}
if status.get("state") == "starting" and _starting_record_outlived_its_start(status):
overwritable.add("starting")
if resolved.state != "stopped" or status.get("state") in overwritable:
status["state"] = resolved.state
status["detail"] = resolved.detail
status["service_pid"] = resolved.service_pid
if extra_pids:
status["extra_service_pids"] = extra_pids
else:
status.pop("extra_service_pids", None)
status["service_owner_pid"] = owner_pid
status["running"] = running
status["pid"] = owner_pid or (extra_pids[0] if extra_pids else None)
# A supervisor may bring the service up from an older install than the
# last activation; it is not refused, so say so here.
from vibe.upgrade import generation_downgrade, process_generation
downgrade = generation_downgrade(process_generation(owner_pid)) if owner_pid else None
if downgrade is not None:
status["generation_downgrade"] = downgrade.as_dict()
else:
status.pop("generation_downgrade", None)
restart_status = read_json(get_restart_status_path())
if restart_status:
status["restart"] = restart_status
internal_server_status = read_json(paths.get_internal_server_status_path())
if internal_server_status:
# The internal server cannot outlive its service: it runs on that
# process's loop and owns a socket that dies with it. A SIGKILL leaves
# no shutdown path to correct the file, so a live "ready" without a
# service owner is stale by definition rather than something to report.
if not running and str(internal_server_status.get("state") or "") not in {"stopped", "error"}:
internal_server_status = {**internal_server_status, "state": "stopped", "stale": True}
status["internal_server"] = internal_server_status
try:
if owner_pid:
from core.show_git import show_git_checkpointing_active
checkpointing_available = show_git_checkpointing_active()
else:
from core.git_binary import resolve_git
checkpointing_available = resolve_git() is not None
if checkpointing_available:
status.pop("show_git_checkpoints", None)
else:
status["show_git_checkpoints"] = "degraded: Git checkpoint service unavailable"
except Exception:
status["show_git_checkpoints"] = "degraded: Git checkpoint status failed"
return json.dumps(status, indent=2)
def _raise_service_start_not_ready(pid: int, *, timeout: float) -> None:
if pid_alive(pid):
raise RuntimeError(
f"Vibe service process pid={pid} did not acquire the service lock within {timeout:.0f} seconds"
)
_clear_service_pid_reservation(pid)
raise RuntimeError(f"Vibe service process pid={pid} did not acquire the service lock")
def _raise_service_started_but_never_ran(pid: int, *, timeout: float) -> None:
"""The service was identified and never reported itself up.
Kept apart from :func:`_raise_service_start_not_ready` because the two are
different failures that used to be reported as one. That one means nothing
on this machine ever claimed to be the service. This one is the incident
behind the rollback work: something did claim it, took the lock, and then
died or hung inside its own startup -- which is exactly how an upgrade to a
release that cannot start looks from outside, and saying "did not acquire
the service lock" about it sends whoever reads the log looking for a lock
contention that is not there.
"""
owner_pid = resolve_service_owner_pid() or pid
if not pid_alive(owner_pid):
_clear_service_pid_reservation(owner_pid)
raise RuntimeError(f"Vibe service process pid={owner_pid} exited while starting up")
if service_instance_still_starting(owner_pid):
raise RuntimeError(
f"Vibe service process pid={owner_pid} acquired the service lock but did not "
f"finish starting within {timeout:.0f} seconds"
)
_raise_service_start_not_ready(owner_pid, timeout=timeout)
# --- cgroup resource-governance bootstrap -----------------------------------
#
# ``core/resource_governance.py`` can only move agent subprocesses into a
# memory-capped cgroup when Avibe itself runs inside a *delegated* cgroup
# subtree. A normal login lands the service in a root-owned, non-delegated
# ``session-*.scope`` where ``mkdir`` returns EPERM, so governance is inert.
#
# The kernel's delegation-containment rule forbids a non-root process from
# migrating itself out of that session scope into the user manager's delegated
# tree (the common ancestor ``user-<uid>.slice`` is root-owned). The only way
# in is to be *launched* inside the delegated tree. ``systemd-run --user
# --scope`` does exactly that: it asks the user systemd manager to create a
# transient scope under ``user@<uid>.service/app.slice`` (qiqi-owned, memory +
# pids delegated) and then ``execve()``s into the target — so the launched
# process keeps its real pid and cmdline (no supervising parent), and Avibe's
# pid-tracking is unaffected.
#
# This is best-effort and fails open: on macOS, without systemd, without a live
# user manager, when governance is disabled, or when linger can't be confirmed,
# the prefix is empty and the service starts exactly as before.
SYSTEMD_SCOPE_PREFIX = (
"systemd-run",
"--user",
"--scope",
"-q", # suppress the "Running scope as unit ..." banner from the log sink
"-p",
"Delegate=yes",
"--",
)
def _resource_governance_mode() -> str:
try:
from config.v2_config import V2Config
from core.resource_governance import config_from_runtime
return str(config_from_runtime(V2Config.load()).get("mode") or "auto").strip().lower()
except Exception:
# Absent/broken config must not block startup; treat as the default.
return "auto"
def _current_username() -> str:
try:
return getpass.getuser()
except Exception:
return str(os.getuid())
def _linger_is_enabled(user: str) -> bool:
try:
result = subprocess.run(
["loginctl", "show-user", user, "-p", "Linger"],
capture_output=True,
text=True,
timeout=5,
)
except Exception:
return False
return "Linger=yes" in (result.stdout or "")
def _ensure_linger_enabled(*, allow_enable: bool) -> bool:
"""Confirm that the user lingers, enabling it only when explicitly allowed.
Once the service lives under ``user@<uid>.service`` instead of a login
session scope, logind tears that manager down on last-session-end unless
lingering is enabled — which would kill Avibe on the first SSH logout.
``loginctl enable-linger`` changes persistent account state, so automatic
governance only observes it. Explicitly enabled governance may opt in to
that change. Fail open: if we can't confirm linger, skip the scope wrap.
"""
user = _current_username()
if _linger_is_enabled(user):
return True
if not allow_enable:
return False
try:
subprocess.run(
["loginctl", "enable-linger", user],
capture_output=True,
text=True,
timeout=5,
)
except Exception:
return False
return _linger_is_enabled(user)
def _systemd_run_self_test_ok(timeout: float = 5.0) -> bool:
"""Bounded dry-run so DBus/user-manager flakiness surfaces here, not as an
opaque 'service did not acquire lock' timeout 30s later."""
try:
result = subprocess.run(
["systemd-run", "--user", "--scope", "-q", "-p", "Delegate=yes", "--", "true"],
capture_output=True,
text=True,
timeout=timeout,
)
except Exception:
return False
return result.returncode == 0
def maybe_systemd_scope_prefix() -> list[str]:
"""Return the ``systemd-run --user --scope`` argv prefix to launch the
service inside a delegated user cgroup, or ``[]`` to start unwrapped.
All predicates must hold; any failure fails open to today's behavior. There
is deliberately no "already inside our own scope" guard: nested
``systemd-run --scope`` creates a harmless *sibling* scope (not a nested
child), and such a guard would misfire when a governed agent shells out to
``vibe restart`` — landing the restarted service inside the old
memory-capped, ``oom.group`` agent cgroup.
"""
if not sys.platform.startswith("linux"):
return []
if shutil.which("systemd-run") is None:
return []
getuid = getattr(os, "getuid", None)
if getuid is None:
return []
if not Path(f"/run/user/{getuid()}/systemd/private").is_socket():
return []
try:
from core.resource_governance import detect_cgroup_root
if detect_cgroup_root() is None:
return []
except Exception:
return []
governance_mode = _resource_governance_mode()
if governance_mode == "disabled":
return []
if not _ensure_linger_enabled(allow_enable=governance_mode == "enabled"):
logger.warning(
"cgroup scope bootstrap: could not confirm user linger; "
"starting service without a delegated user scope"
)
return []
if not _systemd_run_self_test_ok():
logger.warning(
"cgroup scope bootstrap: systemd-run self-test failed; "
"starting service without a delegated user scope"
)
return []
return list(SYSTEMD_SCOPE_PREFIX)
def _adopt_scoped_service_owner(prev_pid: int) -> int | None:
"""Adopt the authoritative ``service.lock`` holder if it differs from ``prev_pid``.
Called on every tick of ``_wait_for_scoped_service_pid``. ``--scope`` exec()s
into the target, so ``prev_pid`` is normally already the real service pid and
the owner matches it (no-op). This exists to stay correct on any host where a
shim survives as a distinct parent: the flock in ``service.lock`` is the
authoritative owner signal (see ``resolve_service_owner_pid``), so if a
*different* live process now holds it, adopt that pid instead of the shim's.
Returns the adopted pid, or ``None`` to leave ``prev_pid`` in place.
"""
owner = resolve_service_owner_pid(include_starting=False)
if owner and owner != prev_pid and pid_alive(owner):
# The shim's Popen must not be attributed to `owner`, but a long-lived
# caller still needs to wait() it after the service exits.
_reap_service_start_process(prev_pid)
_record_service_pid_reservation(owner)
logger.info(
"cgroup scope bootstrap: adopting lock-holder pid=%s as the service owner (shim pid=%s)",
owner,
prev_pid,
)
return owner
return None
def _wait_for_scoped_service_pid(spawn_pid: int, timeout: float) -> int | None:
"""Poll a ``systemd-run --user --scope`` launch until it is lock-verified.
``--scope`` exec()s into the target, so ``spawn_pid`` is normally already the
service pid. To stay correct even if a shim ever survives as a distinct
parent, the ``service.lock`` flock holder is authoritative: on every tick we
adopt a differing live lock holder, so we never settle on an unverified
(possibly wrapper) pid. Returns the ready pid, or ``None`` if it neither
became ready nor left a live owner within ``timeout``.
"""
pid = spawn_pid
deadline = time.monotonic() + timeout
while True:
if service_pid_recorded(pid):
_reap_service_start_process(pid)
return pid
adopted = _adopt_scoped_service_owner(pid)
if adopted is not None:
pid = adopted
continue
# The spawn process is gone and nobody holds the lock -> startup failed.
if _service_start_exit_code(spawn_pid) is not None:
if resolve_service_owner_pid(include_starting=False) is None:
return None
elif not pid_alive(pid) and resolve_service_owner_pid(include_starting=False) is None:
return None
if time.monotonic() >= deadline:
return None
time.sleep(0.05)
def wait_for_service_ready(
spawn_pid: int, timeout: float = SERVICE_SLOW_START_TIMEOUT_SECONDS
) -> int | None:
"""Wait until the service has finished starting and return its owner pid.
Two questions, in order. WHICH process is the service: unlike
``wait_for_service_pid()``, which only confirms a *specific* pid, this
resolves the real ``service.lock`` holder, so a pid handed back by
``start_service()`` that was a launcher/wrapper never taking the lock (e.g. a
surviving ``systemd-run`` parent under some host configuration) is replaced by
the live owner instead of waited on forever. Then: is that process UP --
``SERVICE_PHASE_RUNNING``, which it publishes after migrating the database and
building its controller.
The second question is the one a caller acting on the answer needs. The lock
is taken before the migration runs, so a holder can own the lock and then die
on it; anything that stopped at the lock reports a healthy start and leaves.
That is the whole shape of an upgrade taking an instance dark.
Returns the resolved owner pid, or ``None`` if none finished starting within
``timeout`` -- including when the owner dies while starting, which is that
failure arriving early rather than as a timeout.
"""
deadline = time.monotonic() + timeout
owner_pid = _wait_for_scoped_service_pid(spawn_pid, timeout)
if owner_pid is None:
return None
while True:
if service_instance_started(owner_pid):
return owner_pid
if not pid_alive(owner_pid):
return None
if time.monotonic() >= deadline:
return None
time.sleep(0.05)
def _start_scoped_service_result(
spawn_pid: int,
*,
initial_ready_timeout: float,
wait_for_ready: bool,
) -> int:
"""Resolve the final service pid for a scoped launch, polling+adopting the
authoritative lock holder rather than trusting the spawn pid."""
# A scoped launch must resolve to a lock-verified pid, so give the first
# phase a floor even when the caller passed initial_ready_timeout=0 (e.g.
# restart_supervisor): the spawn pid alone is not a trustworthy owner signal
# under a scope wrapper. In the common exec() case this returns as soon as
# the service acquires the lock, so the floor rarely costs anything.
first_timeout = max(initial_ready_timeout, SERVICE_LOCK_READY_TIMEOUT_SECONDS)
ready = _wait_for_scoped_service_pid(spawn_pid, first_timeout)
if ready is not None:
return ready
exit_code = _service_start_exit_code(spawn_pid)
if exit_code is not None and resolve_service_owner_pid(include_starting=False) is None:
raise RuntimeError(
f"Vibe service process pid={spawn_pid} exited with code {exit_code} before acquiring the service lock"
)
if not wait_for_ready:
candidate = resolve_service_owner_pid() or spawn_pid
if pid_alive(candidate):
logger.warning(
"Scoped Vibe service pid=%s has not acquired the service lock yet; "
"continuing while it finishes startup",
candidate,
)
return candidate
ready = _wait_for_scoped_service_pid(spawn_pid, SERVICE_SLOW_START_TIMEOUT_SECONDS)
if ready is not None:
return ready
exit_code = _service_start_exit_code(spawn_pid)
if exit_code is not None:
raise RuntimeError(
f"Vibe service process pid={spawn_pid} exited with code {exit_code} before acquiring the service lock"
)
_raise_service_start_not_ready(spawn_pid, timeout=SERVICE_SLOW_START_TIMEOUT_SECONDS)
return spawn_pid
def start_service(
*,
wait_for_ready: bool = True,
initial_ready_timeout: float = SERVICE_LOCK_READY_TIMEOUT_SECONDS,
start_info: ProcessStartInfo | None = None,
launcher: ServiceLauncher | None = None,
) -> int:
"""Start the service and return the pid, by default only once it is up.
Two questions, and this function exists because they were being answered by
the same value. WHICH process is the service is settled below, by taking the
spawn lock, reconciling the pid file against the live lock holder and
launching if nobody holds it. WHETHER that process is up is settled here,
once, for every way the answer can be reached.
The split is the fix. `_resolve_service_pid()` has seven places it can hand a
pid back -- a recorded pid file, a lock holder whose command does not match,
a scoped launch adopting its owner, a fresh spawn taking the lock -- and only
one of them ever waited for the running phase. Every other caller of
`wait_for_ready=True` got "the lock was taken", which is the state an
instance is in when the release that took it is about to die on its own
migration. The Dashboard recorded that as a started service and the doctor
recorded it as a successful repair, both correctly trusting the parameter.
Waiting out here also takes the wait off the spawn lock, where a slow start
used to block every other caller for the length of it.
Both phases spend one deadline, not one each. `SERVICE_SLOW_START_TIMEOUT_SECONDS`
is the budget for a service starting, and taking the lock and reaching the
serving state are two phases of that single event -- so passing the constant
to each in turn let a start that is slow in both cost a caller twice the
number the configuration states, on the Dashboard and doctor paths where
someone is waiting for the answer. Measuring from here also makes the bound
mean what it says whichever of `_resolve_service_pid`'s several returns
produced the pid, including the ones that did no waiting at all.
"""
deadline = time.monotonic() + SERVICE_SLOW_START_TIMEOUT_SECONDS
pid = _resolve_service_pid(
wait_for_ready=wait_for_ready,
initial_ready_timeout=initial_ready_timeout,
launcher=launcher,
start_info=start_info,
)
if not wait_for_ready:
return pid
ready_pid = wait_for_service_ready(pid, timeout=max(0.0, deadline - time.monotonic()))
if ready_pid is None:
_raise_service_started_but_never_ran(pid, timeout=SERVICE_SLOW_START_TIMEOUT_SECONDS)
claim_ready_service(ready_pid, started_pid=pid)
if start_info is not None:
start_info.capture(ready_pid, reused=start_info.reused)
from vibe.install_generations import collect_install_generations
collect_install_generations()
return ready_pid
def _resolve_service_pid(
*,
wait_for_ready: bool,
initial_ready_timeout: float,
launcher: ServiceLauncher | None,
start_info: ProcessStartInfo | None,
) -> int:
"""Which process is the service, starting one if nothing holds the lock.
Answers only that. Whether the process it names has finished starting is
`start_service()`'s to establish -- see its docstring for why that is not
left to the individual returns below.
"""
from storage.migrations import guard_source_checkout_default_state_bootstrap
from vibe.desktop_runtime import desktop_runtime_id
def result(pid: int, *, reused: bool) -> int:
# A process this call did not start is reused only when it is the
# caller's own desktop Runtime's; see claim_desktop_runtime_process.
if reused:
claim_desktop_runtime_process(pid, "service")
return start_info.capture(pid, reused=reused) if start_info is not None else pid
def already_running(*holder_pids: int | None) -> ServiceAlreadyRunningError:
# A desktop start that finds a service it may not reuse says whose it
# is not, as a reuse does; one nothing can name is nobody's to claim.
if desktop_runtime_id() is not None:
live = [pid for pid in holder_pids if pid and pid_alive(pid)]
if not live:
raise DesktopRuntimeClaimRefused("service", "identity_unavailable")
for pid in live:
claim_desktop_runtime_process(pid, "service")
return ServiceAlreadyRunningError(lock_path=get_service_lock_path(), holder_pid=holder_pids[0])
guard_source_checkout_default_state_bootstrap()
with _SERVICE_LOCK:
pid_path = paths.get_runtime_pid_path()
existing_pid = 0
if pid_path.exists():
try:
existing_pid = int(pid_path.read_text(encoding="utf-8").strip())
except Exception:
existing_pid = 0
if existing_pid and pid_alive(existing_pid):
if not _pid_mismatches_service(existing_pid):
if service_pid_recorded(existing_pid):
return result(existing_pid, reused=True)
if _pid_reservation_is_fresh(pid_path, existing_pid):
# A reservation this recent names the service whether or
# not it is up yet, so the question is answered. Waiting
# for the running phase used to happen here, and only
# here, which is precisely why every other return below
# answered a question it had not asked.
return result(existing_pid, reused=True)
logger.warning(
"Ignoring stale service pid file pid=%s because it never acquired the service lock",
existing_pid,
)
lock_available, lock_holder_pid = service_instance_lock_available(settle=True)
if not lock_available:
if lock_holder_pid and pid_alive(lock_holder_pid):
if lock_holder_pid == existing_pid:
logger.warning(
"Reusing service pid=%s from lock even though the pid file command does not "
"match this CLI install",
existing_pid,
)
return result(lock_holder_pid, reused=True)
raise already_running(lock_holder_pid)
logger.warning(
"Ignoring stale service pid file pid=%s because it does not match the Vibe service",
existing_pid,
)
pid_path.unlink(missing_ok=True)
lock_available, lock_holder_pid = service_instance_lock_available(settle=True)
if not lock_available:
if lock_holder_pid and lock_holder_pid == existing_pid and pid_alive(lock_holder_pid):
return result(lock_holder_pid, reused=True)
raise already_running(lock_holder_pid)
extra_pids = extra_service_process_pids()
if extra_pids:
raise already_running(*extra_pids)
launcher = launcher or current_service_launcher()
scope_prefix = maybe_systemd_scope_prefix()
if scope_prefix:
logger.info("cgroup scope bootstrap: launching service inside a delegated user scope")
# The reservation is how anything outside this frame finds a service that
# has not taken the lock yet -- `stop_service()` included, and so every
# rollback -- and `start_info` is how the caller knows it created one.
# Both are written inside the spawn primitive's guarded region, so a
# failure or a signal before the last of them kills the child instead of
# leaving one that nothing can stop. Only a findable child is recorded as
# created: whoever reads `start_info` may rely on the reservation too.
def hand_over(process: subprocess.Popen) -> None:
_SERVICE_START_PROCESSES[process.pid] = process
_record_service_pid_reservation(process.pid)
result(process.pid, reused=False)
process = spawn_service_background_process(
[*scope_prefix, launcher.python, launcher.main],
"service_stdout.log",
"service_stderr.log",
env={
**os.environ,
"VIBE_DISABLE_STDOUT_LOGGING": "1",
SHUTDOWN_INTENT_ENV: "1",
},
hand_over=hand_over,
withdraw=_clear_service_pid_reservation,
)
pid = process.pid
if scope_prefix:
# Scoped launches resolve their pid via the authoritative lock holder
# (poll-and-adopt), never by trusting the spawn pid alone.
resolved_pid = _start_scoped_service_result(
pid,
initial_ready_timeout=initial_ready_timeout,
wait_for_ready=wait_for_ready,
)
claim_ready_service(resolved_pid, started_pid=pid)
return result(resolved_pid, reused=False)
if initial_ready_timeout > 0 and wait_for_service_pid(pid, timeout=initial_ready_timeout):
return pid
exit_code = _service_start_exit_code(pid)
if exit_code is not None:
raise RuntimeError(
f"Vibe service process pid={pid} exited with code {exit_code} before acquiring the service lock"
)
if pid_alive(pid) and not wait_for_ready:
logger.warning(
"Vibe service process pid=%s has not acquired the service lock after %.1fs; "
"continuing while it finishes startup",
pid,
initial_ready_timeout,
)
return pid
if wait_for_service_pid(pid, timeout=SERVICE_SLOW_START_TIMEOUT_SECONDS):
return pid
exit_code = _service_start_exit_code(pid)
if exit_code is not None:
raise RuntimeError(
f"Vibe service process pid={pid} exited with code {exit_code} before acquiring the service lock"
)
_raise_service_start_not_ready(pid, timeout=SERVICE_SLOW_START_TIMEOUT_SECONDS)
return pid
def _ui_health_url(host: str, port: int) -> str:
from vibe.desktop_runtime import _normalized_bind_host
health_host = _normalized_bind_host(host)
if health_host in {"0.0.0.0", ""}:
health_host = "127.0.0.1"
elif health_host in {"::", "::0"}:
health_host = "[::1]"
elif health_host.startswith("[") and health_host.endswith("]"):
pass
elif ":" in health_host:
health_host = f"[{health_host}]"
return f"http://{health_host}:{port}/health"
def _ui_health_urls(host: str, port: int) -> tuple[str, ...]:
from vibe.desktop_runtime import desktop_origin
primary_url = _ui_health_url(host, port)
desktop_url = f"{desktop_origin(host, port)}/ready"
urls = [primary_url]
if desktop_url not in urls:
urls.append(desktop_url)
return tuple(urls)
def _ui_ready_identity_state(response) -> bool | None:
try:
payload = json.loads(response.read().decode("utf-8"))
except (AttributeError, OSError, UnicodeDecodeError, json.JSONDecodeError):
return None
return _ui_ready_payload_state(response.status, payload)
def _ui_ready_payload_state(status: int, payload) -> bool | None:
if not isinstance(payload, dict):
return None
if type(payload.get("schema_version")) is not int or payload["schema_version"] != 1:
return None
if payload.get("product") != "avibe" or type(payload.get("ready")) is not bool:
return None
controller_runtime_id = payload.get("desktop_runtime_id")
ui_runtime_id = payload.get("desktop_ui_runtime_id")
expected_ready = {"schema_version", "product", "ready"}
if controller_runtime_id is not None and ui_runtime_id is not None:
return None
for field, runtime_id in (
("desktop_runtime_id", controller_runtime_id),
("desktop_ui_runtime_id", ui_runtime_id),
):
if runtime_id is None:
continue
if (
not isinstance(runtime_id, str)
or len(runtime_id) != 64
or any(character not in "0123456789abcdef" for character in runtime_id)
):
return None
expected_ready.add(field)
if status == 200 and set(payload) == expected_ready and payload["ready"] is True:
return True
code = payload.get("code")
if (
status == 503
and isinstance(code, str)
and bool(code)
and payload
== {
"schema_version": 1,
"product": "avibe",
"ready": False,
"code": code,
}
):
return None if code == "runtime_identity_invalid" else False
return None
def _ui_server_readiness(host: str, port: int, timeout: float = 0.5) -> bool | None:
for health_url in _ui_health_urls(host, port):
try:
with urllib.request.urlopen(health_url, timeout=timeout) as response:
if health_url.endswith("/ready"):
return _ui_ready_identity_state(response)
if response.status != 200:
return None
except urllib.error.HTTPError as exc:
if health_url.endswith("/ready"):
return _ui_ready_identity_state(exc)
return None
except (OSError, urllib.error.URLError, TimeoutError, ValueError):
return None
return None
def ui_server_healthy(host: str, port: int, timeout: float = 0.5) -> bool:
return _ui_server_readiness(host, port, timeout=timeout) is True
def ui_server_compatible(
host: str,
port: int,
timeout: float = UI_ADOPTION_PROBE_TIMEOUT_SECONDS,
) -> bool:
return _ui_server_readiness(host, port, timeout=timeout) is not None
def wait_for_ui_server(host: str, port: int, timeout: float = 5.0) -> bool:
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
if ui_server_healthy(host, port):
return True
time.sleep(0.1)
return ui_server_healthy(host, port)
def wait_for_desktop_startup_ready(
service_pid: int,
host: str,
port: int,
*,
timeout: float = SERVICE_SLOW_START_TIMEOUT_SECONDS,
) -> int | None:
"""Wait for the UI and Controller together under one startup deadline.
``/ready`` is the existing combined UI/Controller readiness contract. The
service owner lookup is still required to return the authoritative process
for status and rollback; it never becomes a second readiness predicate.
"""
import asyncio
import httpx
from vibe.desktop_runtime import desktop_origin
deadline = time.monotonic() + max(0.0, timeout)
origin = desktop_origin(host, port)
async def observe(client):
# The combined exact-origin /ready predicate includes the usable UI,
# service owner and Controller IPC. LAN /health is not a desktop gate.
async with client.stream("GET", f"{origin}/ready", headers={"Accept-Encoding": "identity"}) as response:
length = response.headers.get("content-length")
if length is not None:
try:
if int(length) > 1024:
return False
except ValueError:
return False
body = bytearray()
async for chunk in response.aiter_raw():
if len(body) + len(chunk) > 1024:
return False
body.extend(chunk)
try:
return _ui_ready_payload_state(response.status_code, json.loads(body.decode("utf-8"))) is True
except (ValueError, UnicodeDecodeError):
return False
async def wait():
current_pid = service_pid
async with httpx.AsyncClient(trust_env=False, follow_redirects=False) as client:
while time.monotonic() < deadline:
owner_pid = resolve_service_owner_pid(include_starting=False)
if owner_pid is not None:
current_pid = owner_pid
remaining = deadline - time.monotonic()
if remaining <= 0:
return None
try:
# Bound the entire request including headers and streamed
# body, not a fresh socket timeout for each received byte.
ready = await asyncio.wait_for(
observe(client), min(DESKTOP_READY_PROBE_TIMEOUT_SECONDS, remaining),
)
except (httpx.HTTPError, TimeoutError, OSError):
ready = False
if ready and time.monotonic() < deadline:
if owner_pid is not None or service_instance_started(current_pid):
return current_pid
if not pid_alive(current_pid) and owner_pid is None:
return None
await asyncio.sleep(min(0.1, max(0.0, deadline - time.monotonic())))
return None
return asyncio.run(wait())
def _is_ui_server_command(command: str) -> bool:
return "vibe.ui_server" in command and "run_ui_server" in command
def _pid_matches_ui_server(pid: int) -> bool:
command = get_process_command(pid)
if not command:
return False
return _is_ui_server_command(command)
def ui_pid_file_points_to_running_ui(pid_path: Path | None = None) -> bool:
pid = _read_pid_file(pid_path or paths.get_runtime_ui_pid_path())
return bool(pid and pid_alive(pid) and _pid_matches_ui_server(pid))
def recorded_ui_is_gone(pid_path: Path | None = None) -> bool:
"""Whether no UI runs under the recorded pid, as far as can be known.
Gone means no record, a dead pid, or a pid now running another program. A
live pid whose command cannot be read is not gone: it may be the UI, and one
started beside it would only die on its port.
"""
pid = _read_pid_file(pid_path or paths.get_runtime_ui_pid_path())
if not pid or not pid_alive(pid):
return True
command = get_process_command(pid)
return command is not None and not _is_ui_server_command(command)
def resolve_localhost_family() -> str:
"""Return the loopback family ``localhost`` actually maps to on this host.
``"inet"`` when IPv4 loopback resolves (the common dual-stack case),
``"inet6"`` only when ``localhost`` is exclusively IPv6. Used by
``effective_ui_bind_host`` and ``_origin_host_for_pairing`` so the
bind family and the cloudflared origin family stay aligned: forcing
IPv4 unconditionally would regress IPv6-only hosts, while leaving
resolution to the UI server + cloudflared independently re-creates the
::1 vs 127.0.0.1 race that surfaces as 502.
"""
try:
infos = socket.getaddrinfo("localhost", None, type=socket.SOCK_STREAM)
except socket.gaierror:
return "inet"
families = {info[0] for info in infos}
if socket.AF_INET in families:
return "inet"
if socket.AF_INET6 in families:
return "inet6"
return "inet"
def effective_ui_bind_host(config: V2Config, requested_host: str | None = None) -> str:
"""Resolve the host the UI server should bind to.
When the Avibe Cloud tunnel is enabled, keep loopback-only configs bound
to loopback. For non-loopback setup hosts, bind to a wildcard so the local
``cloudflared`` origin (which dials ``127.0.0.1``/``[::1]``) can reach the
UI no matter which interface IP the user typed into ``ui.setup_host``
(Tailscale CGNAT, LAN). The host-trust middleware in ``ui_server`` still
rejects untrusted peers, so widening the bind does not widen exposure.
Why: If the user binds to a Tailscale or LAN IP and then enables the
tunnel, ``cloudflared`` cannot reach the UI on its loopback origin and
every public request returns 502.
``requested_host`` lets callers (e.g. the ``/ui/reload`` endpoint)
propagate the host from the inbound request without persisting it first;
when omitted we fall back to ``config.ui.setup_host``.
"""
setup_host = (requested_host if requested_host is not None else config.ui.setup_host) or "127.0.0.1"
cloud = getattr(getattr(config, "remote_access", None), "vibe_cloud", None)
if cloud is not None and cloud.enabled:
normalized = setup_host.strip()
if normalized.startswith("[") and normalized.endswith("]"):
normalized = normalized[1:-1]
# "localhost" is ambiguous on dual-stack hosts and may even be
# exclusively IPv6. Resolve once and bind to a literal loopback that
# matches the family _origin_host_for_pairing will hand cloudflared,
# so the two sides cannot disagree without widening the local socket.
if normalized.lower() == "localhost":
return "::1" if resolve_localhost_family() == "inet6" else "127.0.0.1"
try:
address = ipaddress.ip_address(normalized)
except ValueError:
address = None
if address is not None and address.is_loopback:
return address.compressed
# Pick the wildcard family that matches the user's non-loopback intent
# so IPv6 setup_host values stay reachable on v6.
if normalized in {"::", "::0"} or ":" in normalized:
return "::"
return "0.0.0.0"
return setup_host
def start_ui(
host,
port,
*,
wait_for_ready: bool = True,
start_info: ProcessStartInfo | None = None,
launcher: ServiceLauncher | None = None,
):
from vibe.desktop_runtime import normalize_desktop_port
port = normalize_desktop_port(port)
pid_path = paths.get_runtime_ui_pid_path()
if pid_path.exists():
try:
existing_pid = int(pid_path.read_text(encoding="utf-8").strip())
except Exception:
existing_pid = 0
if existing_pid and pid_alive(existing_pid):
is_ui_server = _claim_recorded_ui(existing_pid)
if is_ui_server and ui_server_compatible(host, port):
if start_info is not None:
start_info.capture(existing_pid, reused=True)
return existing_pid
if is_ui_server:
logger.warning(
"Stopping stale UI process pid=%s because required listener or identity checks failed for %s",
existing_pid,
", ".join(_ui_health_urls(host, port)),
)
if not stop_pid(existing_pid):
# The stale process still owns the configured listener, so a
# replacement would only die on bind while that process kept
# serving. Preserve the pid record naming the process that has
# to be stopped: unlinking it here would leave the incompatible
# UI running with nothing pointing at it.
logger.error(
"Failed to stop stale UI process pid=%s; preserving pid state and not starting a replacement",
existing_pid,
)
return None
else:
logger.warning(
"Ignoring stale UI pid file pid=%s because it does not match the Vibe UI server",
existing_pid,
)
pid_path.unlink(missing_ok=True)
# Named entry point, not a body of code: whatever release the launcher's
# interpreter belongs to supplies its own `run_ui_server`. A rollback that
# sent source text across the generation boundary would run the replacement's
# idea of startup inside the replaced install.
command = "from vibe.ui_server import run_ui_server; run_ui_server('{}', {})".format(host, port)
spawn_kwargs = {}
# `start_info` is captured inside the spawn, not after it returns: in between,
# a signal left a live UI with a pid record that `cmd_start`'s rollback,
# which undoes only what `start_info` names as created, never looked at.
if start_info is not None:
spawn_kwargs["start_info"] = start_info
pid = spawn_background(
[(launcher or current_service_launcher()).python, "-c", command],
pid_path,
"ui_stdout.log",
"ui_stderr.log",
**spawn_kwargs,
)
if wait_for_ready and not wait_for_ui_server(host, port):
logger.warning(
"Started UI pid=%s but required health checks did not pass for %s",
pid,
", ".join(_ui_health_urls(host, port)),
)
return pid
def stop_service(
*,
runtime_ids: frozenset[str] = frozenset(),
shutdown_reason: str = "stop_service",
):
"""Stop every service process; with ``runtime_ids``, only when all are that Runtime's.
The ids are checked on the very processes this stop selected, before any
of them is signalled, so a Runtime that took over since an earlier check
is refused, not stopped.
"""
with _SERVICE_LOCK:
pid_path = paths.get_runtime_pid_path()
owner_pid = resolve_service_owner_pid()
target_pids: list[int] = []
if owner_pid is not None:
target_pids.append(owner_pid)
target_pids.extend(extra_service_process_pids(owner_pid=owner_pid))
target_pids = sorted(set(target_pids))
if not target_pids:
recorded_pid = _read_pid_file(pid_path)
if recorded_pid and not pid_alive(recorded_pid):
pid_path.unlink(missing_ok=True)
return False
for pid in target_pids:
refuse_foreign_desktop_process(pid, "service", runtime_ids)
stopped_all = True
for pid in target_pids:
if shutdown_reason == "stop_service":
stopped = stop_pid(pid, timeout=5)
else:
stopped = stop_pid(pid, timeout=5, shutdown_reason=shutdown_reason)
if stopped:
_clear_service_pid_reservation(pid)
continue
stopped_all = False
logger.error(
"Failed to stop resolved service process pid=%s; preserving pid and lock state",
pid,
)
return stopped_all
def stop_remote_access_connector() -> bool:
"""Stop this home's tunnel connector; ``False`` when it may still be running.
The connector's configuration is left as it is, so the next UI start
reconciles it back when remote access is enabled.
"""
try:
from vibe import remote_access
result = remote_access.stop()
except Exception:
logger.warning("Failed to stop remote access", exc_info=True)
return False
if isinstance(result, dict) and result.get("ok") is False:
logger.warning("Failed to stop remote access: %s", result.get("error"))
return False
return True
def stop_ui(
timings: dict[str, float | bool] | None = None,
*,
stop_remote_access: bool = True,
runtime_ids: frozenset[str] = frozenset(),
):
"""Stop the recorded UI and, by default, the tunnel connector it serves.
With ``runtime_ids``, a UI that is not that Runtime's is refused, and so is
its connector: the UI is checked before the connector stops, and again as
the pid about to be signalled is read.
"""
remote_access_stopped = True
started_at = time.monotonic()
ui_pid_path = paths.get_runtime_ui_pid_path()
if stop_remote_access and runtime_ids:
recorded_pid = _read_pid_file(ui_pid_path)
if recorded_pid and pid_alive(recorded_pid):
refuse_foreign_desktop_process(recorded_pid, "ui", runtime_ids)
if stop_remote_access:
remote_access_started_at = time.monotonic()
remote_access_stopped = stop_remote_access_connector()
if timings is not None:
timings["stop_remote_access_seconds"] = _rounded_seconds(time.monotonic() - remote_access_started_at)
elif timings is not None:
timings["stop_remote_access_seconds"] = 0.0
timings["stop_remote_access_skipped"] = True
ui_started_at = time.monotonic()
ui_stopped = stop_process(ui_pid_path, runtime_ids=runtime_ids, part="ui")
if timings is not None:
timings["stop_ui_process_seconds"] = _rounded_seconds(time.monotonic() - ui_started_at)
timings["stop_ui_seconds"] = _rounded_seconds(time.monotonic() - started_at)
return bool(ui_stopped and remote_access_stopped)
class DesktopRuntimePresence(Enum):
"""Whether the desktop Runtime a scoped stop names is running.
``MATCH`` comes from the process scan: a service, UI, backend installer
or OpenCode server carrying the id is running. With none running, the
service lock decides without its record being read: free is ``ABSENT``,
held is ``MISMATCH`` (the holder is not a service of this Runtime), and a
lock that cannot be probed is ``UNKNOWN``. The desktop host mirrors these
as Mine, Absent, Foreign and Unknown.
"""
ABSENT = "absent"
MATCH = "match"
MISMATCH = "mismatch"
UNKNOWN = "unknown"
class DesktopRuntimeStopOutcome(Enum):
"""What a scoped stop left behind, decided by the rescan after it."""
NOT_OURS = "not_ours"
STOPPED = "stopped"
FAILED = "failed"
_DESKTOP_STOP_REFUSALS = {
DesktopRuntimePresence.MISMATCH: "service_runtime_id_mismatch",
DesktopRuntimePresence.UNKNOWN: "service_identity_unavailable",
}
# A process carrying the id whose command line cannot be read may hold any
# role, so it is never signalled and never counted as stopped.
_UNKNOWN_DESKTOP_ROLE = "unknown"
@dataclass(frozen=True)
class DesktopRuntimeProcess:
"""A process carrying the id: ``role`` is ``service``, ``ui``, ``installer``,
``opencode``, ``unknown``, or ``None`` for any other program."""
pid: int
role: str | None
name: str
@dataclass(frozen=True)
class _ScannedDesktopProcess:
process: psutil.Process
report: DesktopRuntimeProcess
# This stop or one of its ancestors: never signalled.
lineage: bool
@dataclass(frozen=True)
class DesktopRuntimeStopResult:
"""What a stop scoped to one desktop Runtime did.
``refusal`` is set when nothing was signalled. ``remaining`` names the
role processes still carrying the id after the stop, and ``left_running``
the other programs carrying it, which the stop never signals.
"""
refusal: str | None = None
remaining: tuple[DesktopRuntimeProcess, ...] = ()
left_running: tuple[DesktopRuntimeProcess, ...] = ()
opencode_stopped: bool = False
@property
def failure(self) -> str | None:
"""The first part that did not stop: ``service``, ``ui``, ``installer``, ``opencode`` or ``unknown``."""
roles = {process.role for process in self.remaining}
for part in ("service", "ui", "installer", "opencode", _UNKNOWN_DESKTOP_ROLE):
if part in roles:
return part
return None
@property
def outcome(self) -> DesktopRuntimeStopOutcome:
if self.refusal is not None:
return DesktopRuntimeStopOutcome.NOT_OURS
if self.failure is not None:
return DesktopRuntimeStopOutcome.FAILED
return DesktopRuntimeStopOutcome.STOPPED
# A scan classifies every process carrying the id, and an agent's command line
# is arbitrary text, so each role is the exact argv shape Avibe launches it with.
# Only the arguments Avibe writes decide: the program is whatever interpreter,
# configured executable or shim runs them.
_UI_SERVER_PAYLOAD = "from vibe.ui_server import run_ui_server;"
def _is_ui_server_argv(argv: list[str]) -> bool:
# `start_ui` and the UI restart run `<python> -c "from vibe.ui_server import run_ui_server; ..."`.
return len(argv) >= 3 and argv[1] == "-c" and argv[2].startswith(_UI_SERVER_PAYLOAD)
def _is_opencode_serve_argv(argv: list[str]) -> bool:
# The server manager runs `<agents.opencode.cli_path> serve --hostname=... --port=...`;
# a shim or wrapper runs it with its own program in front. Those arguments
# are common to servers, so they decide only for a process the manager stamped.
return (
len(argv) >= 4
and argv[-3] == "serve"
and argv[-2].startswith("--hostname=")
and argv[-1].startswith("--port=")
)
def _is_desktop_service_command(command: str, cwd: str | None) -> bool:
# The bundle runs vibe/service_main.py. Its argv names the service even
# after an update has replaced or moved the files it started from.
try:
entry = _service_entry_arg_from_argv(shlex.split(command, posix=(os.name != "nt")))
except ValueError:
entry = None
if entry is not None:
path = Path(entry.strip("\"'"))
if path.name == "service_main.py" and path.parent.name == "vibe":
return True
return _command_looks_like_service_entry(command, cwd=cwd)
def _own_lineage() -> frozenset[int]:
"""This process and its ancestors: started by the desktop host, they carry the id too."""
lineage = {os.getpid(), os.getppid()}
try:
lineage.update(parent.pid for parent in psutil.Process().parents())
except psutil.Error:
logger.warning("Could not read every ancestor of this stop", exc_info=True)
return frozenset(lineage)
def _desktop_process_gone(process: psutil.Process) -> bool:
try:
# is_running() compares the birth time psutil read at the scan, so a
# pid reused since then reads as gone, never as the scanned process.
return not process.is_running() or process.status() == psutil.STATUS_ZOMBIE
except psutil.NoSuchProcess:
return True
except psutil.Error:
return False
def _desktop_process_role(process: psutil.Process) -> str | None:
"""Raises ``psutil.NoSuchProcess`` for a process that has exited."""
from vibe.desktop_runtime import DESKTOP_INSTALLER_ROLE, DESKTOP_OPENCODE_ROLE, DESKTOP_ROLE_ENV
try:
stamped_role = process.environ().get(DESKTOP_ROLE_ENV)
# Every member of a backend install tree inherits the role, whatever
# program it runs.
if stamped_role == DESKTOP_INSTALLER_ROLE:
return "installer"
argv = [str(part) for part in process.cmdline()]
except psutil.NoSuchProcess:
raise
except (psutil.Error, OSError):
stamped_role = None
argv = []
command = shlex.join(argv)
if not command:
if _desktop_process_gone(process):
raise psutil.NoSuchProcess(process.pid)
return _UNKNOWN_DESKTOP_ROLE
if _is_desktop_service_command(command, _process_cwd(process)):
return "service"
if _is_ui_server_argv(argv):
return "ui"
if stamped_role == DESKTOP_OPENCODE_ROLE and _is_opencode_serve_argv(argv):
return "opencode"
return None
def is_desktop_ui(pid: int, runtime_id: str | None) -> bool | None:
"""Whether ``pid`` runs a UI carrying ``runtime_id``, or no Runtime id when that is ``None``.
A scan knows a UI by the same launch shape. ``None`` when the process
cannot be read; a process that has exited is no UI.
"""
from vibe.desktop_runtime import desktop_runtime_id
try:
process = psutil.Process(pid)
role = _desktop_process_role(process)
if role != "ui":
return None if role == _UNKNOWN_DESKTOP_ROLE else False
return desktop_runtime_id(process.environ()) == runtime_id
except psutil.NoSuchProcess:
return False
except (psutil.Error, OSError):
return None
class DesktopRuntimeClaimRefused(RuntimeError):
"""A start or stop found a running ``part`` that is not its own Runtime's.
``reason`` is ``runtime_id_mismatch`` for a process carrying another id or
none, and ``identity_unavailable`` when nothing can tell whose it is. The
process is left as it is.
"""
def __init__(self, part: str, reason: str) -> None:
super().__init__(f"the running {part} is not this desktop Runtime's ({reason})")
self.part = part
self.reason = reason
def _desktop_runtime_mismatch(pid: int, runtime_ids: frozenset[str]) -> str | None:
"""Why ``pid`` is not a process of the one Runtime ``runtime_ids`` names, or None.
A caller that can act for two Runtimes acts for neither. A process that has
exited is nobody's.
"""
from vibe.desktop_runtime import desktop_runtime_id
try:
carried = desktop_runtime_id(psutil.Process(pid).environ())
except psutil.NoSuchProcess:
return None
except (psutil.Error, OSError):
return "identity_unavailable"
if carried is None or runtime_ids != {carried}:
return "runtime_id_mismatch"
return None
def claim_desktop_runtime_process(pid: int, part: str) -> None:
"""Raise ``DesktopRuntimeClaimRefused`` unless ``pid`` is this desktop Runtime's own.
A start carrying a desktop Runtime id reuses, adopts or replaces only
processes carrying the same id. A start without one claims as it always has.
"""
from vibe.desktop_runtime import desktop_runtime_id
runtime_id = desktop_runtime_id()
if runtime_id is not None:
refuse_foreign_desktop_process(pid, part, frozenset({runtime_id}))
def refuse_foreign_desktop_process(pid: int, part: str, runtime_ids: frozenset[str]) -> None:
"""Raise ``DesktopRuntimeClaimRefused`` unless a caller acting for ``runtime_ids`` may act on ``pid``.
No ids is a caller with no desktop provenance, which acts on anything.
"""
if not runtime_ids:
return
reason = _desktop_runtime_mismatch(pid, runtime_ids)
if reason is not None:
raise DesktopRuntimeClaimRefused(part, reason)
def claim_ready_service(ready_pid: int, *, started_pid: int) -> None:
"""Claim the lock holder a start ended up with when it is not the process it asked about.
A service of another Runtime can take the lock first. The start's own
record still names the process it created, which is what a rollback stops.
"""
if ready_pid != started_pid:
claim_desktop_runtime_process(ready_pid, "service")
def _claim_recorded_ui(pid: int) -> bool:
"""Whether the live ``pid`` the UI record names is a UI server a start may reuse or replace.
A record naming another program is stale. Under a desktop Runtime id a UI
server must be that Runtime's, and a pid whose command line cannot be read
is refused: nothing can tell whose it is.
"""
from vibe.desktop_runtime import desktop_runtime_id
is_ui_server = _pid_matches_ui_server(pid)
if not is_ui_server and desktop_runtime_id() is not None and not get_process_command(pid):
raise DesktopRuntimeClaimRefused("ui", "identity_unavailable")
if is_ui_server:
claim_desktop_runtime_process(pid, "ui")
return is_ui_server
def claim_desktop_runtime_start(*, include_ui: bool = True) -> None:
"""Raise ``DesktopRuntimeClaimRefused`` unless what a desktop start would reuse or replace is its Runtime's.
Asked before the start announces anything, so a refused start leaves the
status as it found it. The service is judged as a stop judges it, and with
``include_ui`` the recorded UI as ``start_ui`` judges it. A start without a
desktop Runtime id claims as it always has.
"""
from vibe.desktop_runtime import desktop_runtime_id
runtime_id = desktop_runtime_id()
if runtime_id is None:
return
refusal = desktop_provenance_refusal(include_ui=False, runtime_ids=frozenset({runtime_id}))
if refusal is not None:
raise refusal
ui_pid = _read_pid_file(paths.get_runtime_ui_pid_path())
if include_ui and ui_pid and pid_alive(ui_pid):
_claim_recorded_ui(ui_pid)
def _stop_created_process(pid: int, runtime_ids: frozenset[str]) -> bool:
"""Stop ``pid``, created by a start that did not finish, while it is that Runtime's; True once it is gone."""
if not pid_alive(pid):
return True
reason = _desktop_runtime_mismatch(pid, runtime_ids)
if reason is not None:
logger.warning("A failed start leaves pid=%s running (%s)", pid, reason)
return False
if stop_pid(pid):
return True
logger.error("Failed to stop pid=%s, created by a failed start", pid)
return False
def roll_back_start(service_start: ProcessStartInfo, ui_start: ProcessStartInfo) -> None:
"""Stop what a start that did not finish created, the UI and then its service.
Created is what the start infos record as not reused. The UI stop leaves the
tunnel connector alone: a start never brings one up, so any connector alive
predates it. Under a desktop Runtime id the rollback stops exactly the
processes the start created, and only while they carry that id: what the
records name by then may be another Runtime's.
"""
from vibe.desktop_runtime import desktop_runtime_id
runtime_id = desktop_runtime_id()
ui_created = ui_start.pid is not None and not ui_start.reused
service_created = service_start.pid is not None and not service_start.reused
if runtime_id is None:
if ui_created:
stop_ui(stop_remote_access=False)
if service_created:
stop_service()
return
runtime_ids = frozenset({runtime_id})
if ui_created and _stop_created_process(ui_start.pid, runtime_ids):
_forget_pid_record(paths.get_runtime_ui_pid_path(), ui_start.pid)
if service_created:
with _SERVICE_LOCK:
if _stop_created_process(service_start.pid, runtime_ids):
_clear_service_pid_reservation(service_start.pid)
def desktop_provenance_refusal(
*,
include_ui: bool = True,
runtime_ids: frozenset[str] | None = None,
) -> DesktopRuntimeClaimRefused | None:
"""Why this caller may not stop or restart the Avibe running here, or None when it may.
A caller with no desktop provenance manages whatever runs here, as it always
has. A desktop caller acts only for its own Runtime: every service process,
and with ``include_ui`` the recorded UI, must carry exactly its id, and a
service lock held, or not probed, with no process named as its holder is
refused. With nothing running there is nothing to refuse. ``runtime_ids``
defaults to this caller's ``desktop_caller_provenance()``.
"""
from vibe.desktop_runtime import desktop_caller_provenance
provenance = desktop_caller_provenance() if runtime_ids is None else runtime_ids
if not provenance:
return None
owner_pid = resolve_service_owner_pid()
if owner_pid is None and desktop_service_lock_presence() is not DesktopRuntimePresence.ABSENT:
return DesktopRuntimeClaimRefused("service", "identity_unavailable")
service_pids = set(extra_service_process_pids(owner_pid=owner_pid))
if owner_pid is not None:
service_pids.add(owner_pid)
parts = [("service", pid) for pid in sorted(service_pids)]
if include_ui:
ui_pid = _read_pid_file(paths.get_runtime_ui_pid_path())
if ui_pid and pid_alive(ui_pid):
parts.append(("ui", ui_pid))
for part, pid in parts:
reason = _desktop_runtime_mismatch(pid, provenance)
if reason is not None:
return DesktopRuntimeClaimRefused(part, reason)
return None
def _scan_desktop_runtime(fingerprint: str, lineage: frozenset[int]) -> list[_ScannedDesktopProcess]:
"""This user's processes carrying the id, by role, each with its scan handle."""
from vibe.desktop_runtime import DESKTOP_RUNTIME_ID_ENV
scanned: list[_ScannedDesktopProcess] = []
for process in processes_carrying_marker(fingerprint, marker_env=DESKTOP_RUNTIME_ID_ENV):
try:
role = _desktop_process_role(process)
except psutil.NoSuchProcess:
continue
try:
name = process.name()
except psutil.Error:
name = ""
report = DesktopRuntimeProcess(pid=process.pid, role=role, name=name)
scanned.append(_ScannedDesktopProcess(process, report, process.pid in lineage))
return scanned
def desktop_service_lock_presence(while_absent: Callable[[], None] | None = None) -> DesktopRuntimePresence:
"""With no role process carrying the id, whether anything else holds the service lock.
``while_absent`` runs holding the free lock, so no service can take it,
and so publish its status, until it returns.
"""
try:
lock_path = get_service_lock_path()
lock_path.parent.mkdir(parents=True, exist_ok=True)
lock_file = lock_path.open("a+", encoding="utf-8")
except OSError:
logger.warning("Could not probe the service instance lock", exc_info=True)
return DesktopRuntimePresence.UNKNOWN
with lock_file:
# Only another holder is a mismatch; a lock call that failed says nothing.
try:
taken = _take_service_lock(lock_file)
except OSError:
logger.warning("Could not probe the service instance lock", exc_info=True)
return DesktopRuntimePresence.UNKNOWN
if not taken:
return DesktopRuntimePresence.MISMATCH
try:
if while_absent is not None:
while_absent()
finally:
_unlock_file(lock_file)
return DesktopRuntimePresence.ABSENT
def _stop_desktop_processes(processes: list[psutil.Process], timeout: float = 5) -> None:
"""Stop ``processes`` gracefully, then forcefully, through the handles the scan returned.
``is_running()`` holds right before every signal, and psutil itself
refuses to signal a handle whose pid has been reused since the scan.
"""
phases = (None,) if os.name == "nt" else (signal.SIGTERM, signal.SIGKILL)
alive = list(processes)
for sig in phases:
for process in alive:
if _desktop_process_gone(process):
continue
try:
if sig is None:
logger.info("Terminating desktop Runtime pid=%s", process.pid)
process.terminate()
else:
if sig == signal.SIGTERM:
write_shutdown_intent(process.pid, signum=signal.SIGTERM, reason="stop_pid")
logger.info("Sending managed %s to desktop Runtime pid=%s", signal.Signals(sig).name, process.pid)
process.send_signal(sig)
except psutil.NoSuchProcess:
continue
except (psutil.Error, OSError):
logger.warning("Failed to signal desktop Runtime pid=%s", process.pid, exc_info=True)
deadline = time.monotonic() + timeout
while True:
alive = [process for process in alive if not _desktop_process_gone(process)]
if not alive or time.monotonic() >= deadline:
break
time.sleep(0.1)
if not alive:
return
logger.error("Desktop Runtime processes did not exit: %s", [process.pid for process in alive])
def stop_desktop_runtime(runtime_id: str) -> DesktopRuntimeStopResult:
"""Stop only what the desktop Runtime ``runtime_id`` started.
Discovery is one scan of this user's processes for the id they inherited
in ``AVIBE_DESKTOP_RUNTIME_ID``; no pidfile or record is read. This stop
and its ancestors carry the id when the desktop host started it and are
never signalled. Service processes stop first, then the UI, each through
the handle the scan returned; then every backend installer tree of this
Runtime whose owning UI has exited; then its OpenCode server. A rescan
decides the outcome. Installer staging and records stay for the next
claim of their backend root.
Other programs carrying the id, such as agent CLIs and the tunnel
connector, are reported and left running. With no role process carrying
the id, a held service lock refuses the stop and nothing is signalled.
Role classification guards against accidental collisions, not mimicry.
An agent process already runs with the user's full authority and could
signal the service itself, so a process deliberately shaped like a role is
not a boundary this scan defends. Every descendant of the service inherits
every variable the service carries, so no inherited marker separates the
service from its agent tasks: the service is known by its launch shape and
the id alone. A process carrying the id that runs a file ending in
``vibe/service_main.py`` is therefore stopped with the Runtime it belongs to.
"""
from vibe.desktop_runtime import DESKTOP_RUNTIME_ID_ENV, desktop_runtime_id
if desktop_runtime_id({DESKTOP_RUNTIME_ID_ENV: runtime_id}) != runtime_id:
return DesktopRuntimeStopResult(refusal="invalid_runtime_id")
fingerprint = fingerprint_process_marker(runtime_id)
lineage = _own_lineage()
found = _scan_desktop_runtime(fingerprint, lineage)
if any(entry.report.role is not None for entry in found):
presence = DesktopRuntimePresence.MATCH
else:
presence = desktop_service_lock_presence()
refusal = _DESKTOP_STOP_REFUSALS.get(presence)
if refusal is not None:
return DesktopRuntimeStopResult(refusal=refusal)
def targets(role: str) -> list[psutil.Process]:
return [entry.process for entry in found if entry.report.role == role and not entry.lineage]
with _SERVICE_LOCK:
_stop_desktop_processes(targets("service"))
_stop_desktop_processes(targets("ui"))
from vibe.desktop_backends import reap_abandoned_desktop_backend_installs
# A tree whose owner is still alive stays, and the rescan reports it.
reap_abandoned_desktop_backend_installs(runtime_id)
opencode = targets("opencode")
_stop_desktop_processes(opencode)
left = _scan_desktop_runtime(fingerprint, lineage)
return DesktopRuntimeStopResult(
remaining=tuple(entry.report for entry in left if entry.report.role is not None),
left_running=tuple(entry.report for entry in left if entry.report.role is None and not entry.lineage),
opencode_stopped=any(_desktop_process_gone(process) for process in opencode),
)