Daemon attachment and local startup #

Albedo's API connection and its local process launcher have separate jobs. A client can attach to a supplied endpoint without reading local installation files, starting a process, or replacing one.

Before #

The CLI's connection helper read daemon.json, checked health, compared the running build with the bundled executable, and could start or replace the daemon. Many discovery failures looked like absence. The launcher also supplied the token and VM defaults, so starting the daemon independently behaved differently.

After #

1. Discover reads the local record and probes its authenticated health endpoint. It reports absence, a proven stale record, or a running daemon. Invalid records, authentication failures, unreachable endpoints, and unhealthy daemons return actionable errors. A failed health check does not authorize another launch.
2. Attach validates the protocol and required capabilities, then returns an API connection. Build identity is update information. A different build with the required API remains usable.
3. The ordinary interactive CLI offers to restart a running daemon once per invocation. Keeping it is the default. The prompt warns that restarting interrupts active work across sessions. Scripts keep a compatible daemon and report incompatibility instead of replacing it.
4. Launch starts a local daemon only under the application's policy. Concurrent launchers coordinate through a persistent advisory launcher.lock; the daemon's storage lock remains the authority for home ownership.
5. Upgrade requires the exact snapshot approved by the caller. It validates the replacement executable before stopping anything, rechecks the approved target, drains the supported daemon, and launches its replacement. If the target changed, the caller must obtain fresh approval. Unknown protocols cannot authorize shutdown.

albedo daemon --stop inspects the existing daemon without prompting or starting one. An absent or stale daemon needs no shutdown. Discovery failures are reported.

Authentication and defaults #

Bearer authentication remains the same. The daemon owns its home directory and token: by default it uses ~/.albedo and generates a random token. It publishes daemon.json atomically with mode 0600 inside the private home directory. The record contains the endpoint, PID, protocol, token, and optional build identity. It is a local discovery file, not an API compatibility contract.

The shared priv/bin/albedo-daemon bootstrap installs VM defaults before Erlang starts. Source, test snapshots, and packaged startup use that bootstrap. Deliberate ALBEDO_HOME, ALBEDO_TOKEN, ALBEDO_BUILD, and ERL_FLAGS overrides remain available; operator VM flags follow the defaults and take precedence. The local launcher filters provider overrides so saved daemon configuration remains the source of provider settings.

Cancellation ends discovery, lock acquisition, startup waits, shutdown waits, and the restart prompt. It does not kill a detached daemon that has already started. A client disconnect cannot stop a daemon shared by other clients.

Client development #

Use Attach(ctx, snapshot, rediscovery) for a validated API connection. Supply no rediscovery callback when the endpoint is fixed. A local client can supply Rediscover, which looks for a verified replacement without launching one. API recovery uses the supplied callback and validates the new endpoint before installing it. It does not know the client's home directory or executable.

Attachment currently requires protocol 2 and the operation_receipts, session_stream_generation, and agents_stream_overflow capabilities. Optional features check their own capabilities. Authentication, malformed health, and capability lookup failures propagate to callers.

Implementation ownership and verification #

The API agent owns connection extraction, health validation, explicit recovery, and controlled transport tests. The launcher agent owns local discovery, launch/upgrade coordination, daemon defaults, bootstrap, and packaging. The validation agent owns isolated real-daemon lifecycle scenarios. The lead owns CLI policy, confirmation, integration, documentation, and final review. Shared files have one writer, and daemon builds run serially.

Correctness tests cover independent startup and startup parity, protected records, operator overrides, compatible different builds, attachment failures without process changes, canceled waits, concurrent starters, interactive keep/restart, approval races, and upgrade during active sessions. Transport tests cover health validation and recovery boundaries that the real daemon cannot intentionally violate. No obsolete wire-format readers or compatibility fixtures are retained.

After focused tests, verification runs Go race tests, Gleam checks, Erlang compilation with warnings treated as errors, Go vet, and ./test.sh. Cross-review checks ownership boundaries, cancellation and resource cleanup, error handling, unnecessary forwarding helpers, and tests that only mirror implementation.