A Health Check Should Identify the Runtime It Found

A green health endpoint can answer the wrong question. It may prove that a process responds on a port without proving that it is the process, configuration, or local state your client expects.

APX hit this distinction in a concrete way. One daemon could serve the normal ~/.apx home while another started with a temporary APX_HOME. Under a wildcard-versus-loopback bind, both could hold the same port, and local traffic could quietly reach the more specific listener. No obvious bind error appeared. Both daemons could still report status: ok.

The thesis: local runtime health needs a minimal identity signal, not liveness alone.

Why ok was misleading

An APX daemon owns machine-local state: configuration, authentication tokens, registered projects, message history, and channel connections. The port is only an address. It does not define which state directory the process serves.

Imagine this sequence:

normal daemon  -> port 7430 -> ~/.apx
test daemon    -> port 7430 -> /tmp/test-home/.apx
CLI request    -> port 7430 -> test daemon

The test daemon is technically healthy. Its database opens. Its HTTP server replies. Yet it has the wrong token store, an empty project list, and no live channels. From the client view, authentication suddenly fails and conversations disappear. A boolean health check cannot explain why.

A PID file does not solve this across homes either. If each APX_HOME owns its own PID file, the two daemons cannot see each other's lock. The collision exists at the port boundary, outside either state directory.

Add identity without exposing paths

APX now includes home_id in its unauthenticated health response. The value is a truncated SHA-256 digest of the effective APX_HOME, not the filesystem path itself.

{
  "status": "ok",
  "version": "1.92.3",
  "uptime_s": 42,
  "home_id": "<path fingerprint>"
}

Before binding, a starting daemon asks the loopback health endpoint who is already serving the port. If the returned fingerprint belongs to a different home, startup stops with a useful error. The operator can stop the other daemon or assign a separate APX_PORT.

This is deliberately narrow. The check does not publish a private absolute path. It also does not reject every listener it cannot identify. An older APX version may not return home_id, and a normal restart can briefly overlap with the outgoing process. APX fails open for those ambiguous cases, preserving restart behavior while catching the collision it can prove.

APC defines context; APX identifies execution

Agent Project Context (APC) is the portable context layer. AGENTS.md and .apc/ carry durable project instructions, agent definitions, skills, and safe shared facts across tools and machines. They should not encode one computer's daemon port or state directory.

APX is the daily-use runtime and tooling layer. It turns that portable contract into local execution through its daemon, CLI, web admin, channels, sessions, and stores. Runtime identity therefore belongs in APX health and startup checks, not in APC project files.

That separation keeps the repository portable while making local operations diagnosable. The same APC project can move between machines; each APX runtime can still prove which local home it serves.

General rule

For any local agent daemon, ask three different questions:

1. Liveness: did something answer?
2. Readiness: can it serve requests?
3. Identity: is it serving the state this client expects?

Collapsing all three into ok creates failures that look impossible: healthy service, broken application. A small, non-secret identity fingerprint turns that mystery into an explicit startup decision.