@kolu/surface-daemon-supervisor reference
The client half: the code that spawns, watches, recycles and upgrades a daemon.
It runs in the client process, never the daemon, and carries no @kolu/* app
dependency. Its only workspace edges are the daemon half and @kolu/surface,
which it dials the frozen control core through.
The face is Effect-native
Every verb on this page returns an Effect, and so does every plug it takes
from a consumer: connect, probe, driver.spawn, RestartSteps’ three
steps, drain and awaitExit. There is no Promise-shaped twin, so a boot that
loses a race, a restart you abandoned and a drain past its ceiling each tear
their own work down.
Three seams are synchronous facts rather than operations:
| Seam | Why it is not an Effect |
|---|---|
Endpoint.current() | A read of held state, whose eager throw callers rely on. |
DaemonConnection’s dispose() | The supervisor tears down from paths that cannot await. |
DaemonConnection’s onClose(cb) | The same: it is called from paths that cannot await. |
Nothing on EndpointSpec is Promise-shaped.
readProcessIdentity,readSocketHoldersandreadProcessStateeach stateEffect.Effect<…, OsfactsClientError>.- The error channel is the union of
osfacts-client, the package that satisfies those seams and takeseffectas its one runtime dependency. Their success halves (SocketOccupancy,SocketHolder) come from there too. - An identity read that fails is a typed failure the endpoint answers (report
dead, then propagate), not a defect that strands the UI atconnecting. awaitExittakes noAbortSignaland noAbortController. Fiber interruption tells a poll-based exit oracle to stop once the drain ceiling has won, and interruption cannot be refused.- Why: Why the supervisor is a separate package.
The dial leaf — /dial
@kolu/surface-daemon-supervisor/dial carries exactly three things:
dialSocket (the unix-socket connect/error race, won once),
DaemonContractSkewError plus its brand-checked isContractSkewError, and the
DaemonConnection shape a handshake produces.
| entry | carries | what it does not compile |
|---|---|---|
@kolu/surface-daemon-supervisor/dial | dialSocket, DaemonContractSkewError, isContractSkewError, DaemonConnection | endpoint.ts — drivers, convergence, osfacts-client |
@kolu/padi-client/dialneeds those three and nothing more, and it is the entry an out-of-repo consumer hydrates on its own. What that consumer reaches, itstsccompiles.- Reaching them through the barrel instead compiles
endpoint.ts: the drivers, the convergence probe, and through the process-identity seamosfacts-client, a second npins pin to graft and guard. endpoint.tsimports the three from the leaf and re-exports them, so the barrel’s surface is unchanged. Its whole compile cost isnode:netandeffect.@kolu/padi-client’s hydrate guard asserts that no bare daemon barrel is in its import closure.- The copy/compile split stands: a consumer still copies the supervisor’s
directory, whose manifest still names
osfacts-client.
The endpoint
The endpoint is the state machine that takes a daemon from nothing to a live, handshaken connection, and reports what it finds while it does.
| Export | Subpath | What it is |
|---|---|---|
createEndpoint({ home, readProcessIdentity, readSocketHolders, readProcessState, policy, probe, connect, … }) | . | Builds the state machine from your injects and policy. |
Endpoint | . | The handle it returns: states, the live connection, the restart hold. |
destructiveRecycleSteps() | . | Named no-preservation steps for a fail-closed recycle. |
survivableSpawnDriver(cfg, deps?) | . | The default driver: a systemd service, or a detached child. |
scrubDaemonNodeOptions(nodeOptions) | . | Strips dev-only Node flags from an inherited NODE_OPTIONS. |
recycle(endpoint, steps) · serializeRestart(endpoint) | . | The restart sequence, and its single-flight trigger. |
waitForPidGone(pid, opts?) | . | Polls until a pid is reaped. |
reapHolder(pid, readProcessState, opts?) | . | The two-deadline stop every kill site shares. |
ReadSocketHolders | . | The type of the socket-holder inject. |
ReadProcessState | . | The type of the process-state inject. |
SocketOccupancy · SocketHolder | . | The three-way answer to “who holds this socket?”. |
SocketSquatterForeignError · isSocketSquatterForeignError(err) | . | A foreign holder of the rendezvous socket, never killed. |
SocketProbeIndeterminateError · isSocketProbeIndeterminateError(err) | . | A connect probe that timed out, proving nothing. |
DaemonContractSkewError · isContractSkewError(err) | ., /dial | The one typed connect rejection that proves incompatibility. |
ENDPOINT_STATES · ENDPOINT_STATE_DOWN · isDownEndpointState(s) | /states, . | The state tuple and its down/terminal classification. |
createEndpoint
Builds the state machine and returns an unforgeable public Endpoint.
createEndpoint({ home, readProcessIdentity, readSocketHolders, readProcessState, policy, probe, connect: (socketPath) => …, … })
const policy: ConvergencePolicy<"not-drainable"> = {
capability: "not-drainable",
baked,
onContractSkew: { kind: "recycle" },
onBuildMismatch: { kind: "nudge-human" },
};
const endpoint = createEndpoint<TopClient, TopIdentity>({
hostId: "local",
home, // SAME call as the daemon — disagreement impossible
readProcessIdentity,
readSocketHolders, // osfacts-client's osfactsSocketHolders(<the same resolved bin>)
readProcessState, // processStateReader(<the same resolved bin>) — a stopped holder skips the graceful reap leg
policy,
probe: probeDaemonIdentity({ capability: "not-drainable" }),
driver: survivableSpawnDriver({
binPath: daemonEntry,
args: [],
// COMPLETE child env for the detached spawn: the daemon's base plus its
// locator vars. A partial env here would spawn a daemon with no PATH/HOME.
env: {
...spawnEnvBase(),
FLEET_TOP_GATE: home.gatePath,
FLEET_TOP_SOCKET: home.socketPath,
},
unitPrefix: "fleet-top",
}),
// the framework hands you the path
connect: (socketPath) => connectTop(socketPath),
log: stderrLogger(),
onStatus: (hostId, status) =>
process.stderr.write(`[supervisor] ${hostId}: ${status.state}\n`),
});
return Effect.gen(function* () {
// #region converge
// The only boot verb — policy (who I am + how I converge) is fixed on the endpoint.
const outcome = yield* converge(endpoint);
| Option | What you pass |
|---|---|
home | DaemonHomePaths, the same spine primitive daemonMain takes. Gate and socket come from it. |
readProcessIdentity | Start-qualified gate ownership, as a ReadProcessIdentityAsync. |
readSocketHolders | Gate-less squatter recovery, as a ReadSocketHolders. |
readProcessState | Whether the holder is stopped, so its graceful reap leg is skippable. A ReadProcessState. |
policy | Your whole convergence surface: who I am, and how I converge. |
probe | The convergence probe, usually probeDaemonIdentity. |
connect | Receives the socket path from the framework, so callers never re-thread it. |
- All three OS-fact readers are required, never defaulted, because the endpoint performs no platform traversal of its own.
readProcessIdentityis(pid: number) => Effect.Effect<ProcessIdentity | undefined, OsfactsClientError>. It runs off the serving loop, so an osfacts spawn never blocks it. PreferprocessIdentityAsync(bin), withbinresolved once at the composition root.- The awaitable type lives in this package beside
EndpointSpec. The daemon half keeps only the syncReadProcessIdentity, which the synchronous gate-claim paths use. - The boot trio lives in a package
WeakMap, not on the returned object.
An unreadable gate
The endpoint’s holder probe folds the daemon half’s three-way gate-read law exhaustively. An unreadable gate (EACCES or EIO) is not free and not stale.
- When
readGateIdentityyieldsunreadable,ensureand recycle throw before any unlink, kill or spawn. - Status still emits
connecting → dead, then rethrows, so the UI never wedges. - A mode-
000gate is the unit pin (recycleForeignGate.test.ts).
The incompatible state
incompatible is the proven contract-skew verdict: a respawn from the realised
closure already skewed, or a refuse-policy survivor skews at handshake.
- It is reported with both contract versions on the status
(
{ state: "incompatible", daemonVersion, requiredVersion }). - It is never collapsed into
dead/degraded. A consumer deriving affordances from the state sum must not offer a restart against it, because restarting cannot fix a skew. Only changing the closure can. - A restart hold does not coerce it. A skew inside a restart is that restart’s terminal verdict, not a transition.
Endpoint
The handle createEndpoint returns, generic over the client C and the
identity I.
- Its states are
connecting → connected | dead | incompatible, thenconnected → degradedif the daemon dies mid-session. - The public verbs are
converge(endpoint)andrecycle(endpoint, steps). - The boot-method trio (
ensure/adoptOrEnsure/adoptOrSpawnOrRefuse) is absent from the publicEndpointtype and from the runtime object. - Private binds live only in a package
WeakMapkeyed by the genuinecreateEndpointhandle. Kit modules (converge,recycle) and same-package tests resolve them through a package-internal relative import ofendpoint.private.ts. There is no publicasEndpointInternaland no./testingsubpath. current()is the live connection.holdRestartingis the recycle emit-guard.
destructiveRecycleSteps()
Named no-preservation steps for a fail-closed recycle. All steps are still required.
survivableSpawnDriver(cfg, deps?)
The default DaemonDriver: systemd-run --user under a service, and a
detached +unref child otherwise.
DaemonDriver.spawnis anEffect<void>value, not a method. Re-running it is “spawn again”.
cfg.env per launch mode
survivableSpawnDriver’s cfg.env is read differently by the mode the driver
picks, so compose it for the mode you will hit.
| Mode | How env is read |
|---|---|
| Detached (the production default) | env is the complete child env. Nothing from the parent is layered under it, so a partial set spawns a daemon with no PATH or HOME. |
| Under systemd | env overlays the unit’s PAM/manager env via --setenv, so a partial set is fine. |
- On the detached path, carry the daemon’s whole base. Compose it from a fixed
allowlist, as the snippet above does. kolu mines
kolu-pty’sSPAWN_ENV_ALLOWLIST. - Launch mode and env inheritance are one union field, so the illegal
combination is unspellable.
fromSourceomitted (orfalse) is a normal launch: systemd-eligible, withenvcomplete. - An object
{ inheritParentEnv }forces the detached branch even under a session, for an actual source launch or a built binary a box forces detached. inheritParentEnvdecides whetherenvlayers over the supervisor’s full parent env. Usetrueonly for an actual from-source launch (the dev nix-shell env). A built forced-detached daemon uses{ inheritParentEnv: false }and getsenvalone.- Why: Why the framework takes values, not loose fields.
scrubDaemonNodeOptions(nodeOptions)
Strips dev-only Node flags from an inherited NODE_OPTIONS, so a spawned
daemon never opens the supervisor’s inspector or writes its profiles.
- It returns
undefinedwhen nothing of value remains, so the variable is dropped rather than emptied. - It is opt-in per driver.
recycle(endpoint, steps) · serializeRestart(endpoint)
recycle is the composed capture → drain → recycle → reattach sequence, as
one Effect. serializeRestart returns a single-flight triggerRestart.
RestartSteps’ three members areEffects too.captureis a value, because an effect is already the description of work not yet done.triggerRestartcoalesces rather than queues: a second caller joins the restart already in flight and gets its outcome, instead of waiting and then running a second one.
waitForPidGone(pid, opts?)
An Effect<boolean> that polls isHolderLive until the pid is reaped
(ESRCH), so a respawn never races a live gate holder.
reapHolder(pid, readProcessState, opts?)
An Effect<ReapOutcome, OsfactsClientError>: the two-deadline stop every
supervisor kill site shares.
SIGTERM → wait REAP_TERM_CEILING_MS (120 s) → SIGKILL → wait
REAP_KILL_CEILING_MS (5 s).
readProcessStateis required, as the injected OS fact, never a default.- A holder observed stopped (
T/t) skips the graceful leg, because a stopped process cannot run a shutdown handler.SIGKILLlands at once. - A read that cannot complete travels the error channel, where the endpoint
reports
deadand rethrows. It is never a silent “not stopped”. - It answers
{ kind: "reaped", endedBy, waitedMs, reason? }or{ kind: "survived", waitedMs, reason? }. An operator reads which signal ended it, how long it took, and whether the graceful window was skipped.
ReadSocketHolders
The type of the readSocketHolders inject:
(socketPath: string) => Effect.Effect<SocketOccupancy, OsfactsClientError>.
- The reader that satisfies it is
osfactsSocketHolders(bin)fromosfacts-client, bound to an already-resolved osfacts binary path (bakedOsFactsBin(<your env var>)). This package never learns which variable a consumer bakes. - It calls
osfacts socket-holders <path> --procs. The platform split, the parse, the honesty policy and the fold live in the tool and its client, not here. - Bind it to the same resolved path as
processIdentityAsync, so one root spells its environment variable once for all the OS facts.
ReadProcessState
The type of the readProcessState inject:
(pid: number) => Effect.Effect<ProcessState | undefined, OsfactsClientError>.
- The reader that satisfies it is
processStateAsync(bin)fromosfacts-client, bound to the same already-resolved osfacts binary path (osfacts snapshot --pids <pid> --status). undefinedis the honest dead-pid answer.- The
T/t⇒ stopped fold lives once in this package, not in the reader.
SocketOccupancy · SocketHolder
The three-way answer to who holds a socket, never one possibly-empty list.
| Answer | What it means |
|---|---|
{ kind: "held", holders } | holders is a non-empty tuple by type (readonly [SocketHolder, ...SocketHolder[]]), so a consumer never writes an unreachable empty-check. |
{ kind: "none" } | Proven nothing holds it. Only linux’s world-readable /proc/net/unix can prove this. |
{ kind: "unattributed", detail } | Something may hold it and the OS would not say what: a bound-but-unreadable holder, or a search that could not complete. |
- Only
noneis evidence of freedom, and the endpoint still re-probes before spawning. - Both types are re-exported from
osfacts-client, whosefoldSocketOccupancy(reading)produces them from aSocketHoldersReading. One fold, so kolu and drishti cannot spell the three-way differently.
SocketSquatterForeignError · isSocketSquatterForeignError(err)
Thrown when the process holding the rendezvous socket did not complete the kaval handshake. Such a foreign or non-conforming holder is never killed.
- It carries
socketPath,holders: SocketHolder[]anddetail?: string, so the refusal names the squatter. - Each holder is a pid and an optional
command. The command is absent, never"?", when the identity read lost the race, so a sentinel cannot be mistaken for a process actually named?. - When the OS named nobody,
detailis theunattributedreading’s own words (the holder search could not complete (darwin_proc_fds: BLIND_OR_EMPTY)), which the message renders instead of “an unidentifiable process”. - On darwin the nameless case is the ordinary one, so the explanation, not just the decision, has to survive the fold.
- The guard is brand-checked and realm-robust.
SocketProbeIndeterminateError · isSocketProbeIndeterminateError(err)
Thrown when a one-shot socket connect probe times out (SocketServeState
"indeterminate"). It proves neither free nor dead.
- The endpoint never kills, unlinks or spawns on it.
- It carries
gatePath,socketPathand an optionalgatePid. - Failures after
connectingemitdead, then rethrow, so status never wedges.
DaemonContractSkewError · isContractSkewError(err)
The one typed connect rejection that proves incompatibility. It is also exported
from /dial.
- It is constructed from fields (
{ subject, daemonVersion, requiredVersion, pid? }), with the message derived from them, so no consumer re-parses the prose. readonly daemonVersionandrequiredVersionride the instance, so downstream translators (a typed RPC rethrow, a status arm) read them structurally.- The optional
readonly pidis the skewed daemon’s self-reported OS pid. The gate-less-squatter recovery of an old orphan throws here before a connection exists, and this is its identity attestation. - The guard is brand-checked (realm-robust), never
instanceof.
ENDPOINT_STATES · ENDPOINT_STATE_DOWN · isDownEndpointState(s)
The state tuple and its total down/terminal classification. Both live in the
zero-dependency, browser-safe /states subpath, and are re-exported from the
package root.
ENDPOINT_STATE_DOWNis aRecord<EndpointState, boolean>, so a new state is a compile error at the home until it is classified.- Consumers (a dial-ended check, a client presentation table) read
isDownEndpointStateinstead of hand-spelling thedegraded || dead || incompatibledisjunct.
The convergence kit
converge(endpoint) is the only boot verb. It probes the running daemon’s
identity, asks a pure decide, admits drain through the per-boot budget when
the daemon is drainable, and enacts through the endpoint’s private boot methods.
kaval declares recycle-on-skew. padi declares
drain-newer-else-refuse with a drain-capable handshake. The step-by-step for
both is in
How to recycle and upgrade a daemon, and the
rules the kit enforces are in
Daemon invariants.
// The only boot verb — policy (who I am + how I converge) is fixed on the endpoint.
const outcome = yield* converge(endpoint);
converge(endpoint)
A single fold over every observation, then decide, then a budget-gated drain,
then a private bind. It takes a genuine createEndpoint handle only.
- It returns a typed
ConvergenceOutcomewhose kinds either always carry their anomaly or never do. There are no optionals. - Anomaly arms carry typed evidence as data:
runningandexpectedidentities,drainedandobservedinstance keys.detailis human garnish only. - Same-lineage admitted drains continue (F1a).
- A null re-probe is
identity-unverifiable(F1b). - Give-up re-decides characterization without re-draining.
- Connector arms (ssh) use
convergeAdmitwith the same policy object.
Single observation authority
Every observed identity flows through one internal fold (foldObserved): the
initial probe, bind characterization, the post-drain successor, the post-give-up
bind, and the drainable re-probe.
- Every bind transition (plain, recycle, post-drain, give-up) flows through one
BindResultconsumer (consumeBindResult). Call sites never inspectr.kind. - The fold always runs
decide(policy, identity | null), never a hand-copied compat/match subset. - It owns connection lifecycle, so refused, not-adopted and probe-failed exits
call the idempotent
releaseHeldunconditionally. There is noholdingmirror. - It preserves four-valued characterizations
(
characterized | absent | failed | uncorrelated). - It reports
unconverged.running: nullwhen the running identity is honestly unknown, and never fabricatesexpected. - A characterization probe throw is
probe-failedwith the true message, never a catch-to-null intoidentity-unverifiable. - Named probe instance keys must match
conn.startedAt. A mismatch isuncorrelated.
convergeAdmit(opts)
The connector arm, an Effect<ConvergeAdmitVerdict>. It takes
{ running, budget, drain, awaitExit, … }.
budgetis aConnectorDrainBudget, which makes recycle and nudge-human unspellable.drainandawaitExitareEffects.awaitExitsucceeds only on process exit, never on link loss (F3).
probeDaemonIdentity(opts)(socketPath)
The endpoint probe for the frozen fragment, as a full ConvergenceProbe. It
takes { capability, drainCeilingMs? }.
- It answers
nullonly for an honestECONNREFUSEDorENOENT. - Every other dial or hello failure throws, including a control-core version
other than the frozen
1.0, and an unspeakable peer (UnspeakableProtocolError). - It throws when a live pre-fragment daemon answers the socket but has no
core.helloroute.
A consumer with a named upgrade window may catch only that structured route-missing failure and project it as an older-build observation. Kaval does this, so its not-drainable policy reports the existing human nudge.
- Such a consumer never turns the served-daemon fact into
null, and catches no other probe error. - The narrowing derives on the Effect RPC failure. The oRPC
NOT_FOUNDframe does not exist on this wire. - A peer from a previous epoch is a different observation. See The third observation.
probeDaemonIdentityFrom(opts)
The single probe-assembly authority for an already-dialled connector.
probeDaemonIdentityFrom({ client, dispose, capability: "not-drainable" })omits the exit-oracle fields.probeDaemonIdentityFrom({ client, dispose, capability: "drainable", awaitExit, drainCeilingMs })requires both of them.- ssh keeps its stronger process-exit oracle instead of treating link loss as exit.
readControlCoreHello(client) · ControlCoreProbeClient
Reads and validates the frozen hello on its one baked 30 s deadline: the
frozen-version check, plus the joint buildId/commit fact.
ControlCoreProbeClientis the already-dialled client shape it takes:client.surface.control.core.hello(), which is itself anEffect.
dialSocket(socketPath)
The package’s own unix-socket dial, as an Effect<Socket>, so the control-core
leg owns its framing tap.
- A dial interrupted before it settles destroys the half-open socket rather than abandoning it.
isNoListenerError(error)
The one ECONNREFUSED/ENOENT classifier shared by generic and pre-fragment
daemon probes.
decide(policy, running)
The pure fold, and the sole decision authority under converge. It reads
policy.baked; there is no free-standing baked argument.
createDrainBudget · createConnectorDrainBudget · outcomeAdopted · outcomeAnomaly
Opaque budget handles and outcome constructors. There are no public admit can-openers, and the connector mint is type-gated.
InstanceKey · instanceKeyFromStartedAt · instanceKeyTag
A named instance, or pre-instance when startedAt is absent, which means
older. The absence is never overloaded onto null.
BindResult · BoundResidentCharacterization
The private-bind result. Adopted residents carry a four-valued characterization:
characterized | absent | failed | uncorrelated.
drainAndAwaitExit(drain, awaitExit, { ceilingMs })
The framework-run drain-and-confirm-exit skeleton both enactments share. Its
signature is
drainAndAwaitExit(drain: Effect<void>, awaitExit: Effect<void>, { ceilingMs }).
- Both plugs are forked into the primitive’s own scope, so the ceiling winning interrupts the exit oracle.
awaitExit’s error channel isneverby type, which states the F3 contract in the signature rather than in a comment.
ConvergenceAnomaly
adopted-stale | skew-refused | unconverged | cross-supervisor. Each arm
carries typed evidence.
unconverged.runningis nullable, for an unknown identity.link-failedis session-owned.
UnconvergedCause
budget-exhausted | drain-not-taken | adopt-bind-failed | identity-unverifiable | probe-failed | unspeakable-protocol,
with the evidence as data under unconverged.
- The
unspeakable-protocolarm carriessocketPath,gatePathand the pid that was classified. - It rides a refusal only when the gate stopped naming that pid before the takeover could act.
UnspeakableEvidence · unspeakableClause(evidence)
Why a peer is unspeakable, as data: { trigger: "undecodable-frame", frame } or
{ trigger: "silence", silentForMs }.
- There is no third arm.
unspeakableClauseis shared, so the dial path, the corroboration site and the fold cannot drift in what they tell an operator.
UnspeakableProtocolError · isUnspeakableProtocolError(err)
The transport fact, raised by probeDaemonIdentity’s dial at one of the two
triggers. It is never raised by the hello deadline, a close, or a member error.
- It carries
socketPathand theevidencefield. - Uncorroborated, it is an ordinary
probe-failed. - The guard is brand-checked and realm-robust.
UnspeakablePeerError · isUnspeakablePeerError(err)
The corroborated verdict: the same fact plus the two attestations the endpoint
adds. The gate at this rendezvous is ours, and its pid passed the holder
identity law.
- It carries
gatePathandpidbeside the transport fields. - Only this becomes the
unspeakable-protocolobservation.
UNSPEAKABLE_SILENCE_MS
The silence bound, 8 s. It is pinned between two facts of the link.
- The link pings every 5 s, and a peer of this epoch pongs below its handlers, so a merely slow daemon has still demonstrably spoken.
- The link’s keep-alive backstop ends a silent connection only past 60 s, after which there is nothing left to classify.
contractIsNewer · contractIsCompatible · buildsMatch
Re-exported from @kolu/surface-daemon. Contract versions are ordered; build
ids are match-only.
The third observation — unspeakable-protocol
A daemon from a previous protocol epoch cannot be asked its version at all, because version negotiation happens inside the protocol that was replaced. Convergence therefore has a third narrowly-typed peer observation beside “identity” and “absent”.
Such a peer betrays itself in exactly two ways, and which one you get depends on who greets whom:
| Trigger | What happens | Evidence |
|---|---|---|
undecodable-frame | The peer speaks first, in a framing we cannot parse. | A bounded, JSON-quoted frame excerpt. |
silence | The peer waits for a greeting in a protocol we do not speak: it accepts the connection, takes our frames, and answers nothing. | silentForMs, the bound it stayed mute through. |
- The
silencearm is measured against the previous release: its oRPCServerPeerwaits for its own client hello, our ndjson frames never look like one, and the connection dies by timeout with no first frame to fail decoding. - Both triggers are the same verdict, so they are one error type with the trigger as a tagged field, never two classes a consumer would have to union.
- The fact is raised under those triggers alone. The observation additionally requires two attestations: the gate file at this rendezvous is ours, and its pid passed the holder identity law.
- An uncorroborated trigger stays
probe-failed, and a foreign socket-squatter keeps theSocketSquatterForeignErrorpath. A merely slow peer and a stranger on our socket both stop at the transport fact. - Classification happens at the trigger, not by waiting out the frozen hello’s
30 s deadline. That keeps
awaitHelloGoneresponsive inside a drain ceiling when the peer will never answer.
The takeover
The disposition is takeover, for every policy. The contract-skew policy is not consulted, because an undecodable wire is not a skew and the drain verb does not exist on it. What is available is the act the drain verb requests: the daemon’s own in-process shutdown, asked for with a signal instead of a message.
| step | what happens |
|---|---|
| re-attest | The gate must still name the exact pid that was classified. If it names anyone else, nothing is signalled and the pass refuses with the unspeakable-protocol cause. |
SIGTERM | The old daemon’s own shutdown runs (persist, close, release the gate), bounded by REAP_TERM_CEILING_MS (120 s). |
SIGKILL | Only past the graceful deadline, bounded by REAP_KILL_CEILING_MS (5 s). Still alive after it, and the endpoint reports dead and fails loud. |
| spawn | A daemon of this epoch is started and connected at the same rendezvous. It seeds from disk, so loss is bounded by the old daemon’s autosave debounce. |
- The graceful leg is skipped entirely when the holder is observed stopped
(
T/t): a stopped process cannot run a shutdown handler, because the signal is queued, not delivered. - On that skipped path
SIGKILLlands immediately. That is thereason: "stopped"in the outcome. - The takeover is logged as one operator-readable line: what was stopped, why it was provably ours, which signal ended it, how long the wait took, and whether the graceful leg was skipped.
- The outcome is
recycled, because the holder was replaced, not adopted. - Kaval’s
recyclereaches the same act by the same path. - Why: Recycling a daemon without lying to its clients.