Does: one process per data directory — composes a worker or a gateway and serves the contract on a unix socket. Flows: startup, device.exec, gateway.
Dispatch:
- One
Dispatcherinstance serves the socket, the uplink and HTTP; HTTP callsDaemonServer.dispatchin process. - Handlers never see raw input and never check roles:
runDispatch(dispatch.ts) does both first. - The
authorizehook lets an unknown lease id pass, so the handler answersUNKNOWN_LEASE, notFORBIDDEN. - Lists filter in the handler, not in
authorize: anagent'slease.list, andstatus.get'sleasesandwaiting, hold only what its principal owns.
Start and stop:
- The socket claim comes before any write to
admin.tokenand before converge. A daemon that lost the claim never touchesadmin.token. admin.tokenis removed on stop before the endpoint is released, so an old shutdown cannot remove a replacement's credential.- A worker with real drivers takes the worker lock (
ports/worker-lock.ts) beforediscoverDrivers, makes sure it holds it after the socket claim, and releases it after the drivers are disposed and on a failed start; substituted drivers and gateways never take it. - On a worker, no request but
hello,status.get,daemon.stopanddaemon.updatewithqueryruns before converge ends. A gateway's dispatcher never parks. daemon.stopis handled by the server, before the version and stopping gates.daemon.updateskips only the version gate.daemon.startedis emitted only after converge, and never afterdaemon.stopping. A stop during converge arms nothing.DaemonAlreadyRunningErrorskipssettleanddispose: the live daemon may share the drivers' adb server. The entry then exits at once (process.exit), since a start that lost the claim keeps its drivers' children.- A bind failure of the HTTP listener fails the start and stops the daemon (
http-start-failed). daemon.stopreleases nothing; leases persist with their deadlines.disposestops the event history after the drivers are disposed, and closesstate.dblast.- A history file that fails costs only history. A start the history refuses (a newer stored projection version, a failed migration) stops the daemon (
history-refused). - A daemon works in its own role's data directory. Its one look outside is the update's
socketHeldprobe of the other role's socket (composition-support.ts).
Connections:
- Role and principal are fixed at
hellofor the connection's life. The uplink connection isadminby acceptance; otherwise admin comes only from a credential athello, never from the socket itself. - No protocol overlap leaves the connection open: every request but
daemon.stopanddaemon.updategetsPROTOCOL_VERSION_UNSUPPORTED. - A closed connection only silences its pushes; the request, the lease and a running command go on.
lease-lostskips the connection that asked for that release.
Update:
- A gateway's update holds no leases, so it never waits.
querystarts nothing. A call during an update follows it;forceonwaitinginstalls now.DaemonServer.startcallsreadResultFile()after convergence and before health isrunning, so arunningdaemon already shows the failure.announceResultFile()emitsdaemon.update-failedonce the daemon serves, so a parkedevents.subscribereceives it.
Relays (worker side):
relay.requestruns only on the uplink connection.- A
twoWayrelay runs no body cut-off. Its target answers a refusal before touching the pipe, or a 2xx with no body and then uses the pipe; the call answers once both directions have ended. The silence bound is the gateway's. filesis the one relay target the core names: the lease files of a worker, served for a gateway (ADR 0067 §7). A module cannot take the name.GatewayUplinkretries forever.
Cooperative identity, not a hostile-process boundary.
- Every socket peer is the same OS user; file modes are the real boundary. An existing data directory is never chmod'ed; the daemon warns when group or others can reach it. On Windows no directory guards the pipe: see ports.
- A
hello.principalis a claim. Ownership checks stop accidents, not attacks. - A worker that joins a fleet grants its gateway
adminover itself, and must not be able to crash, stall or corrupt it: see gateway. - An
agenttoken is shell access to the worker:device.execruns host tools as the daemon's user, with only the keysexecBaseEnvironment(exec-env.ts) keeps plus the command's own.