opencode-runtime 0.4.1__tar.gz → 0.5.0__tar.gz

{opencode_runtime-0.4.1 → opencode_runtime-0.5.0}/.github/workflows/ci.yml

@@ -1,8 +1,10 @@
 name: ci
 
 on:
-  push:
   pull_request:
+  push:
+    branches:
+      - main
 
 jobs:
   ci:

{opencode_runtime-0.4.1 → opencode_runtime-0.5.0}/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-## [Unreleased]
+## [0.5.0]
+
+### Added
+- SQLite-backed server registry at `~/.opencode-runtime/servers/registry.db` — persistent, atomic, supports concurrent claims
+- `ServerState` enum (STARTING, RUNNING, STOPPING, FAILED) for type-safe state tracking
+- Health probes: process liveness check + HTTP health endpoint verification; display status shows running/starting/unhealthy/stale/failed
+- `inspect` command: detailed server info (PID, port, uptime, idle time, runtime version, health)
+- Server metadata: track `runtime_version` and `last_used_at` timestamp
+
+### Changed
+- Registry moved from PID files to SQLite — no API changes, same registry operations
+- All state tracking uses `ServerState` enum instead of string literals (type safety)
+- Server startup now lazy — contexts don't auto-create default server, start on first `session()` call
+- `runtime.close()` now stops only servers that `OpenCodeRuntime` instance itself started; servers it merely attached to (already running, started by another process or the CLI) are left alone (safe for multi-process deployments)
+
+### Fixed
+- one `OpenCodeRuntime` exiting would terminate servers created by other processes or CLI — now scoped to servers it actually started
 
 ## [0.4.1] - 2026-07-09
 

{opencode_runtime-0.4.1 → opencode_runtime-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-runtime
-Version: 0.4.1
+Version: 0.5.0
 Summary: Embed OpenCode in your Python application.
 Project-URL: Homepage, https://github.com/ashish16052/opencode-runtime
 Project-URL: Repository, https://github.com/ashish16052/opencode-runtime
@@ -91,14 +91,15 @@ opencode-runtime ps
 ```
 
 ```
-  ID                  PID    PORT    STATUS     UPTIME    WORKSPACE   USER    PROJECT
-  ──────────────────────────────────────────────────────────────────────────────────
-  39dce5beb4debfaa   12051   58409   ● alive    Up 5m     org_a       u_1     ~/Developer/myproject
-  81fa29acb3e9210f   12088   58411   ● alive    Up 3m     org_b       u_2     ~/Developer/myproject
+  ID                  PID    PORT    STATUS      UPTIME    WORKSPACE   USER    PROJECT
+  ───────────────────────────────────────────────────────────────────────────────────
+  39dce5beb4debfaa   12051   58409   ● running   5m        org_a       u_1     ~/Developer/myproject
+  81fa29acb3e9210f   12088   58411   ● running   3m        org_b       u_2     ~/Developer/myproject
 ```
 
 ```sh
 opencode-runtime health 39dce5beb4debfaa
+opencode-runtime inspect 39dce5beb4debfaa
 opencode-runtime stop-all
 ```
 

{opencode_runtime-0.4.1 → opencode_runtime-0.5.0}/README.md

@@ -58,14 +58,15 @@ opencode-runtime ps
 ```
 
 ```
-  ID                  PID    PORT    STATUS     UPTIME    WORKSPACE   USER    PROJECT
-  ──────────────────────────────────────────────────────────────────────────────────
-  39dce5beb4debfaa   12051   58409   ● alive    Up 5m     org_a       u_1     ~/Developer/myproject
-  81fa29acb3e9210f   12088   58411   ● alive    Up 3m     org_b       u_2     ~/Developer/myproject
+  ID                  PID    PORT    STATUS      UPTIME    WORKSPACE   USER    PROJECT
+  ───────────────────────────────────────────────────────────────────────────────────
+  39dce5beb4debfaa   12051   58409   ● running   5m        org_a       u_1     ~/Developer/myproject
+  81fa29acb3e9210f   12088   58411   ● running   3m        org_b       u_2     ~/Developer/myproject
 ```
 
 ```sh
 opencode-runtime health 39dce5beb4debfaa
+opencode-runtime inspect 39dce5beb4debfaa
 opencode-runtime stop-all
 ```
 

{opencode_runtime-0.4.1 → opencode_runtime-0.5.0}/docs/cli.md

@@ -11,11 +11,11 @@ opencode-runtime ps
 ```
 
 ```
-  ID                  PID    PORT    STATUS     UPTIME    WORKSPACE   USER    PROJECT
-  ──────────────────────────────────────────────────────────────────────────────────
-  39dce5beb4debfaa   12051   58409   ● alive    Up 5m     org_a       u_1     ~/Developer/myproject
-  81fa29acb3e9210f   12088   58411   ● alive    Up 3m     org_b       u_2     ~/Developer/myproject
-  c3f2a1d9e8b74f05   13204   58413   ● alive    Up 1h     org_c       u_3     ~/Developer/myproject
+  ID                  PID    PORT    STATUS      UPTIME    WORKSPACE   USER    PROJECT
+  ───────────────────────────────────────────────────────────────────────────────────
+  39dce5beb4debfaa   12051   58409   ● running   5m        org_a       u_1     ~/Developer/myproject
+  81fa29acb3e9210f   12088   58411   ● running   3m        org_b       u_2     ~/Developer/myproject
+  c3f2a1d9e8b74f05   13204   58413   ● running   1h        org_c       u_3     ~/Developer/myproject
 ```
 
 Every server your Python app has started — across all users and workspaces — is visible here. PID, port, uptime, which tenant, which user, which project. No guessing, no digging through logs.
@@ -34,6 +34,26 @@ Pipe it into your alerting:
 opencode-runtime health 39dce5beb4debfaa || pagerduty-alert "opencode server down"
 ```
 
+## Inspect a server in detail
+
+`health` tells you if a server is up; `inspect` tells you everything else — uptime, idle time, runtime version, log file location:
+
+```sh
+opencode-runtime inspect 39dce5beb4debfaa
+```
+
+```
+  ID         39dce5beb4debfaa
+  Status     ● running
+  Project    ~/Developer/myproject
+  Workspace  org_a
+  User       u_1
+  PID        12051
+  Port       58409
+  Uptime     5m 12s
+  Last used  30s ago
+```
+
 ## Start a server manually
 
 Spin up a server outside of Python — useful for pre-warming tenants before they hit your API, or for running one-off tasks from the terminal:
@@ -95,5 +115,6 @@ deploy.sh
 | `opencode-runtime ps` | List all running servers with ID, PID, port, status, uptime, workspace, user, project |
 | `opencode-runtime serve` | Start a background server. Accepts `--workspace`, `--user-id` |
 | `opencode-runtime health <id>` | Health check a server by ID. Exits non-zero if unhealthy |
+| `opencode-runtime inspect <id>` | Show detailed info for a server: uptime, idle time, runtime version, log file |
 | `opencode-runtime stop <id>` | Stop a specific server by ID |
 | `opencode-runtime stop-all` | Stop all running servers |

{opencode_runtime-0.4.1 → opencode_runtime-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "opencode-runtime"
-version = "0.4.1"
+version = "0.5.0"
 description = "Embed OpenCode in your Python application."
 readme = "README.md"
 requires-python = ">=3.10"

{opencode_runtime-0.4.1 → opencode_runtime-0.5.0}/src/opencode_runtime/__init__.py

@@ -2,11 +2,11 @@
 opencode-runtime: runtime infrastructure for multi-user OpenCode deployments.
 """
 
-__version__ = "0.4.1"
+__version__ = "0.5.0"
 
 from .event import OpenCodeEvent
-from .runtime import OpenCodeRuntime
 from .response import OpenCodeResponse
+from .runtime import OpenCodeRuntime
 from .session import OpenCodeSession
 
 __all__ = [

{opencode_runtime-0.4.1 → opencode_runtime-0.5.0}/src/opencode_runtime/cli.py

@@ -17,13 +17,14 @@ import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
-from .server import ServerManager, _compute_runtime_key
+from .server import DisplayStatus, ServerManager, _compute_runtime_key
 
 # ---------------------------------------------------------------------------
 # ANSI
 # ---------------------------------------------------------------------------
 
 _R = "\033[0m"
+_DIM = "\033[2m"
 
 
 def _green(s: str) -> str:
@@ -43,7 +44,7 @@ def _cyan(s: str) -> str:
 
 
 def _dim(s: str) -> str:
-    return f"\033[2m{s}{_R}"
+    return f"{_DIM}{s}{_R}"
 
 
 # ---------------------------------------------------------------------------
@@ -76,6 +77,29 @@ def _row(label: str, value: str) -> None:
     print(f"  {_cyan(f'{label:<9}')}  {value}")
 
 
+_STATUS_ICONS: dict[DisplayStatus, str] = {
+    DisplayStatus.RUNNING: "●",
+    DisplayStatus.STARTING: "◐",
+    DisplayStatus.UNHEALTHY: "▲",
+    DisplayStatus.STALE: "○",
+    DisplayStatus.FAILED: "✗",
+}
+_STATUS_COLORS = {
+    DisplayStatus.RUNNING: _green,
+    DisplayStatus.STARTING: _yellow,
+    DisplayStatus.UNHEALTHY: _red,
+    DisplayStatus.STALE: _dim,
+    DisplayStatus.FAILED: _red,
+}
+
+
+def _status_display(status: DisplayStatus) -> str:
+    """Render a ServerStatus.display value as a coloured icon + label."""
+    icon = _STATUS_ICONS.get(status, "?")
+    color = _STATUS_COLORS.get(status, _dim)
+    return color(f"{icon} {status.value}")
+
+
 # ---------------------------------------------------------------------------
 # serve
 # ---------------------------------------------------------------------------
@@ -152,11 +176,11 @@ def cmd_serve(args: argparse.Namespace) -> None:
 
 
 def cmd_ps(_args: argparse.Namespace) -> None:
-    entries = ServerManager().list()
-    show_workspace = any(e.workspace for e, _ in entries)
-    show_user = any(e.user_id for e, _ in entries)
+    statuses = asyncio.run(ServerManager().list_statuses())
+    show_workspace = any(st.entry.workspace for st in statuses)
+    show_user = any(st.entry.user_id for st in statuses)
 
-    cols = ["  {:<18}", "{:>6}", "{:>6}", "{:<7}", "{:>8}"]
+    cols = ["  {:<18}", "{:>6}", "{:>6}", "{:<11}", "{:>8}"]
     headers = ["ID", "PID", "PORT", "STATUS", "UPTIME"]
     if show_workspace:
         cols.append("{:<12}")
@@ -171,18 +195,33 @@ def cmd_ps(_args: argparse.Namespace) -> None:
     print(_cyan(fmt.format(*headers)))
     print(_dim("  " + "─" * (70 + 14 * show_workspace + 14 * show_user)))
 
-    for e, alive in entries:
-        status_plain = "● alive" if alive else "● dead"
-        status_coloured = _green(status_plain) if alive else _red(status_plain)
-        vals = [e.key, str(e.pid), str(e.port), status_plain, _uptime(e.started_at, alive)]
+    for st in statuses:
+        e = st.entry
+        status_plain = f"{_STATUS_ICONS.get(st.display, '?')} {st.display.value}"
+        status_coloured = _status_display(st.display)
+
+        # Compute uptime
+        try:
+            started = datetime.fromisoformat(e.started_at)
+            uptime_secs = int((datetime.now(timezone.utc) - started).total_seconds())
+            if uptime_secs < 60:
+                uptime_str = f"{uptime_secs}s"
+            elif uptime_secs < 3600:
+                uptime_str = f"{uptime_secs // 60}m"
+            else:
+                uptime_str = f"{uptime_secs // 3600}h"
+        except Exception:
+            uptime_str = "?"
+
+        vals = [e.key, str(e.pid), str(e.port), status_plain, uptime_str]
         if show_workspace:
             vals.append(e.workspace or "-")
         if show_user:
             vals.append(e.user_id or "-")
         vals.append(_home(e.project_dir))
         row = fmt.format(*vals)
-        row = row.replace(status_plain, status_coloured, 1)
-        print(_dim(row).replace(_dim(status_coloured), status_coloured, 1))
+        dimmed_row = _dim(row).replace(status_plain, f"{status_coloured}{_DIM}", 1)
+        print(dimmed_row)
 
 
 # ---------------------------------------------------------------------------
@@ -191,8 +230,10 @@ def cmd_ps(_args: argparse.Namespace) -> None:
 
 
 def cmd_stop(args: argparse.Namespace) -> None:
+    from . import registry
+
     manager = ServerManager()
-    entry = manager.find(args.key)
+    entry = registry.read(args.key)
     if entry is None:
         sys.exit(_red(f"✗ ID {args.key!r} not found in registry"))
 
@@ -202,7 +243,7 @@ def cmd_stop(args: argparse.Namespace) -> None:
 
     print(f"{_green('✓ Server stopped')}\n")
     _row("ID", entry.key)
-    _row("PID", _dim(str(entry.pid)))
+    _row("PID", _dim(str(entry.pid)) if entry.pid else _dim("(none)"))
 
 
 # ---------------------------------------------------------------------------
@@ -230,20 +271,103 @@ def cmd_stop_all(_args: argparse.Namespace) -> None:
 
 
 def cmd_health(args: argparse.Namespace) -> None:
-    from .exceptions import OpenCodeServerError
+    manager = ServerManager()
+    st = asyncio.run(manager.status(args.key))
+    if st is None:
+        sys.exit(_red(f"✗ ID {args.key!r} not found in registry"))
+    entry = st.entry
+
+    if st.display == DisplayStatus.RUNNING:
+        try:
+            result = asyncio.run(manager.health(args.key))
+            version = result.get("version")
+            print(
+                _green("✓ healthy")
+                + f"   {_dim(f'version {version}')}"
+                + f"   {_dim(f'http://127.0.0.1:{entry.port}')}"
+            )
+        except Exception as exc:
+            sys.exit(_red(f"✗ unhealthy: /global/health failed: {exc}"))
+    elif st.display == DisplayStatus.STARTING:
+        try:
+            claimed = datetime.fromisoformat(entry.claimed_at)
+            age_secs = int((datetime.now(timezone.utc) - claimed).total_seconds())
+            sys.exit(_yellow(f"◐ starting: claimed {age_secs}s ago, health check pending"))
+        except Exception:
+            sys.exit(_yellow("◐ starting: awaiting health check"))
+    elif st.display == DisplayStatus.UNHEALTHY:
+        sys.exit(
+            _red(
+                f"✗ unhealthy: process running (pid {entry.pid}) but /global/health endpoint failed"
+            )
+        )
+    elif st.display == DisplayStatus.STALE:
+        sys.exit(_red(f"✗ stale: registry entry exists but pid {entry.pid} is not running"))
+    elif st.display == DisplayStatus.FAILED:
+        sys.exit(_red("✗ failed: startup failed or lease expired"))
+    else:
+        sys.exit(_red(f"✗ unknown: {st.display}"))
+
 
+# ---------------------------------------------------------------------------
+# inspect
+# ---------------------------------------------------------------------------
+
+
+def cmd_inspect(args: argparse.Namespace) -> None:
     manager = ServerManager()
-    entry = manager.find(args.key)
-    if entry is None:
+    st = asyncio.run(manager.status(args.key))
+    if st is None:
         sys.exit(_red(f"✗ ID {args.key!r} not found in registry"))
+    entry = st.entry
 
-    url = f"http://127.0.0.1:{entry.port}"
+    # Compute uptime
     try:
-        result = asyncio.run(manager.health(args.key))
-        version = result.get("version")
-        print(_green("✓ healthy") + f"   {_dim(f'version {version}')}" + f"   {_dim(url)}")
-    except OpenCodeServerError as exc:
-        sys.exit(_red(f"✗ unreachable   {url}\n  {exc}"))
+        started = datetime.fromisoformat(entry.started_at)
+        uptime_secs = int((datetime.now(timezone.utc) - started).total_seconds())
+        if uptime_secs < 60:
+            uptime = f"{uptime_secs}s"
+        elif uptime_secs < 3600:
+            uptime = f"{uptime_secs // 60}m {uptime_secs % 60}s"
+        else:
+            uptime = f"{uptime_secs // 3600}h {(uptime_secs % 3600) // 60}m"
+    except Exception:
+        uptime = "?"
+
+    # Compute idle time (time since last use)
+    if entry.last_used_at:
+        try:
+            last_used = datetime.fromisoformat(entry.last_used_at)
+            idle_secs = int((datetime.now(timezone.utc) - last_used).total_seconds())
+            if idle_secs < 60:
+                idle = f"{idle_secs}s ago"
+            elif idle_secs < 3600:
+                idle = f"{idle_secs // 60}m ago"
+            else:
+                idle = f"{idle_secs // 3600}h ago"
+        except Exception:
+            idle = "?"
+    else:
+        idle = "-"
+
+    print()
+    _row("ID", entry.key)
+    _row("Status", _status_display(st.display))
+    _row("Project", _home(entry.project_dir))
+    if entry.workspace:
+        _row("Workspace", entry.workspace)
+    if entry.user_id:
+        _row("User", entry.user_id)
+    _row("PID", _dim(str(entry.pid)) if entry.pid else _dim("(none)"))
+    _row("Port", _dim(str(entry.port)))
+    _row("Uptime", uptime)
+    _row("Last used", idle)
+    if entry.runtime_version:
+        _row("Runtime", entry.runtime_version)
+    if entry.server_dir:
+        log_file = _home(str(Path(entry.server_dir) / "opencode.log"))
+        _row("Log file", _dim(log_file))
+    print()
 
 
 # ---------------------------------------------------------------------------
@@ -291,6 +415,10 @@ def main() -> None:
     p.add_argument("key", help="server id (from ps)")
     p.set_defaults(func=cmd_health)
 
+    p = sub.add_parser("inspect", help="show detailed server information")
+    p.add_argument("key", help="server id (from ps)")
+    p.set_defaults(func=cmd_inspect)
+
     if len(sys.argv) == 1:
         parser.print_help()
         sys.exit(0)

{opencode_runtime-0.4.1 → opencode_runtime-0.5.0}/src/opencode_runtime/client.py

@@ -24,8 +24,9 @@ class OpenCodeClient:
     Args:
         base_url:  Base URL of the running opencode server,
                    e.g. ``"http://127.0.0.1:4096"``.
-        password:  Value of ``OPENCODE_SERVER_PASSWORD``. Sent as
-                   ``Authorization: Bearer <password>`` when set.
+        password:  Value of ``OPENCODE_SERVER_PASSWORD``. Sent as HTTP Basic
+                   auth (``Authorization: Basic base64("opencode:<password>")``)
+                   when set.
         timeout:   Default request timeout in seconds.
     """
 

{opencode_runtime-0.4.1 → opencode_runtime-0.5.0}/src/opencode_runtime/event.py

@@ -20,8 +20,3 @@ class OpenCodeEvent:
     type: str
     text: str | None = None
     raw: Any = None
-
-    def to_sse(self) -> str:
-        """Format as a Server-Sent Events string suitable for HTTP streaming."""
-        data = self.text or ""
-        return f"event: {self.type}\ndata: {data}\n\n"

{opencode_runtime-0.4.1 → opencode_runtime-0.5.0}/src/opencode_runtime/exceptions.py

@@ -12,3 +12,11 @@ class OpenCodeServerError(OpenCodeRuntimeError):
 
 class OpenCodeTimeoutError(OpenCodeRuntimeError):
     """Raised when a health check or request exceeds the allowed timeout."""
+
+
+class RegistrySchemaError(OpenCodeRuntimeError):
+    """Raised when the registry database's schema version can't be handled.
+
+    Either it's newer than this version of opencode-runtime understands, or
+    no migration is registered to bring it up to the current version.
+    """

opencode_runtime-0.5.0/src/opencode_runtime/registry.py

@@ -0,0 +1,188 @@
+"""
+Registry for tracking OpenCode instance processes.
+
+Every running instance is a row in a SQLite database at:
+    ~/.opencode-runtime/servers/registry.db
+
+Used by both the CLI (opencode-runtime serve/ps/stop) and the library
+(OpenCodeRuntime) — the registry is the shared source of truth for all
+running instances regardless of how they were started.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Generator
+
+from .schema import SCHEMA, SCHEMA_VERSION, migrate
+
+REGISTRY_DIR = Path(
+    os.environ.get("OPENCODE_RUNTIME_REGISTRY_DIR")
+    or (Path.home() / ".opencode-runtime" / "servers")
+)
+
+# A 'starting' row older than this is treated as abandoned (its starter
+# crashed — SIGKILL, host reboot — before reaching write()/delete()) and is
+# reclaimed by the next claim_starting() call. Comfortably above
+# _wait_healthy's default 60s startup timeout, so a claim only expires once
+# a start attempt has definitely either finished or died without cleaning
+# up after itself.
+_START_LEASE_SECONDS = 90
+
+
+class ServerState(str, Enum):
+    """Server lifecycle state.
+
+    STARTING: claimed startup slot, awaiting health check.
+    RUNNING: process alive, health check passing.
+    STOPPING: shutdown initiated (reserved for future use).
+    FAILED: startup failed or lease expired (reserved for future use).
+    """
+
+    STARTING = "starting"
+    RUNNING = "running"
+    STOPPING = "stopping"
+    FAILED = "failed"
+
+
+@dataclass
+class RegistryEntry:
+    """A server entry in the registry.
+
+    state: ServerState enum value. Display status is derived from state + observed health.
+    """
+
+    key: str
+    state: ServerState
+    pid: int | None
+    port: int
+    password: str
+    project_dir: str
+    server_dir: str | None
+    started_at: str  # ISO-8601
+    claimed_at: str  # ISO-8601; only meaningful while state == "starting"
+    workspace: str | None = None
+    user_id: str | None = None
+    last_used_at: str | None = None
+    runtime_version: str | None = None
+
+
+_INSERT = """
+INSERT INTO servers (key, state, pid, port, password, project_dir, server_dir,
+                     started_at, claimed_at, workspace, user_id, last_used_at,
+                     runtime_version)
+VALUES (:key, :state, :pid, :port, :password, :project_dir, :server_dir,
+        :started_at, :claimed_at, :workspace, :user_id, :last_used_at,
+        :runtime_version)
+"""
+
+_UPSERT = _INSERT.replace("INSERT", "INSERT OR REPLACE", 1)
+
+
+@contextmanager
+def _connect() -> Generator[sqlite3.Connection, None, None]:
+    """Open the registry database, creating it on first use.
+
+    Commits on clean exit, rolls back if the body raises. The 5s timeout is
+    SQLite's busy timeout — concurrent writers wait for each other instead
+    of failing immediately.
+    """
+    REGISTRY_DIR.mkdir(parents=True, exist_ok=True)
+    db_path = REGISTRY_DIR / "registry.db"
+    is_new = not db_path.exists()
+    conn = sqlite3.connect(db_path, timeout=5.0)
+    try:
+        conn.row_factory = sqlite3.Row
+        conn.execute(SCHEMA)
+        if is_new:
+            db_path.chmod(0o600)  # entries hold server passwords
+            conn.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
+        else:
+            current_version = conn.execute("PRAGMA user_version").fetchone()[0]
+            if current_version != SCHEMA_VERSION:
+                migrate(conn, current_version)
+        yield conn
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def _entry(row: sqlite3.Row) -> RegistryEntry:
+    # Column names match RegistryEntry field names one-to-one.
+    return RegistryEntry(**{name: row[name] for name in row.keys()})
+
+
+def write(entry: RegistryEntry) -> None:
+    """Write (insert or replace) a registry entry."""
+    with _connect() as conn:
+        conn.execute(_UPSERT, asdict(entry))
+
+
+def read(key: str) -> RegistryEntry | None:
+    """Read a registry entry by key. Returns None if not found."""
+    with _connect() as conn:
+        row = conn.execute("SELECT * FROM servers WHERE key = ?", (key,)).fetchone()
+    return _entry(row) if row is not None else None
+
+
+def delete(key: str) -> None:
+    """Remove a registry entry. No-op if not found."""
+    with _connect() as conn:
+        conn.execute("DELETE FROM servers WHERE key = ?", (key,))
+
+
+def list_all() -> list[RegistryEntry]:
+    """Return all registry entries."""
+    with _connect() as conn:
+        rows = conn.execute("SELECT * FROM servers").fetchall()
+    return [_entry(row) for row in rows]
+
+
+def claim_starting(entry: RegistryEntry) -> bool:
+    """Atomically insert a 'starting' row for entry.key.
+
+    Returns True if this call claimed the key, False if a row for the key
+    already exists (a live 'starting' claim or a 'ready' server). A
+    'starting' row older than _START_LEASE_SECONDS is treated as abandoned
+    and reclaimed within the same transaction.
+    """
+    cutoff = (datetime.now(timezone.utc) - timedelta(seconds=_START_LEASE_SECONDS)).isoformat(
+        timespec="microseconds"
+    )
+    try:
+        with _connect() as conn:
+            conn.execute(
+                "DELETE FROM servers WHERE key = ? AND state = ? AND claimed_at < ?",
+                (entry.key, ServerState.STARTING.value, cutoff),
+            )
+            conn.execute(_INSERT, asdict(entry))
+        return True
+    except sqlite3.IntegrityError:  # PRIMARY KEY conflict — someone else holds the key
+        return False
+
+
+def is_alive(pid: int | None) -> bool:
+    """Return True if pid is set and a process with it is running."""
+    if pid is None:
+        return False
+    try:
+        os.kill(pid, 0)
+        return True
+    except (ProcessLookupError, PermissionError):
+        return False
+
+
+def now_iso() -> str:
+    """Return current UTC time as ISO-8601 string with fixed microsecond precision.
+
+    Fixed precision (rather than omitting the fraction when it's exactly
+    zero, as isoformat() does by default) keeps these strings correctly
+    orderable by plain string comparison, e.g. in claim_starting()'s lease check.
+    """
+    return datetime.now(timezone.utc).isoformat(timespec="microseconds")