feat!(daemon,contract): one TTL-first lease on every transport (ADR 0004, PR B)

[V3RON]

The daemon-side half of ADR 0004, where the wire breaks. PR A gave the CLI and the MCP session a renew timer over an ordinary lease; this PR removes the mechanism they were shadowing. After it there is one kind of lease — it carries a TTL, a client-initiated lease.renew arriving before the deadline is the only thing that keeps it alive, and nothing about a connection (its close, its daemon's death, a restart) ends one.

Base is claude/adr-0004-a-client-renew, rebased onto its final commit c81c644. Part of #114

What changed, layer by layer

Contract (src/contract/) — ADR 0004 §1/§4, and ADR 0003 §6 for the version rule.
lease.heartbeat leaves the operation registry and the push families, and the heartbeat hello capability goes with it. mode leaves lease.request's input and the lease record; the record instead gains two stored fields, ttlMs (the width it was granted with, or last renewed with) and lastRenewedAt (written at grant and on every renew). lastRenewedAt replaces the dispatcher's derived lastHeartbeatAt, which was computed as ttlDeadline - heldTtlBackstopMs and has no answer once every lease carries its own TTL. ttlMs is accepted on every request now; its upper bound is not expressible in the contract module (it is a daemon config value), so the schema keeps only "a TTL is a positive number". Protocol range is {min: 4, max: 4} with no shim; daemon.stop stays the frozen exception.

Core (src/core/) — ADR 0004 §1/§3/§4.
LeaseLifecycle grants at the request's own width or lease.defaultTtlMs, and a renew naming no ttlMs re-applies the lease's own stored width — never the default, so a four-hour lease does not shrink to fifteen minutes the first time something renews it. LeaseLifecycle.heartbeat (and its detached-lease guard), LeaseEngine.heartbeat, and the release coordinator's port for it are deleted. StartupConverger restores every persisted lease's timer from its own deadline and sweeps nothing: a restart proves nothing about whether a holder is alive. Config is lease.defaultTtlMs (15m) and lease.maxTtlMs (4h), validated together at load (defaultTtlMs <= maxTtlMs, both positive) with a violation failing the daemon start and naming the key.

Daemon (src/daemon/) — ADR 0004 §3/§5.
heldLeaseIds and every piece of bookkeeping around it are gone: the heartbeat push and its timer, release-on-connection-close, and the release-held step in stop(). DispatchSession drops heldLeaseIds/heartbeatCapability. Lease-scoped pushes are untouched (§5) — lease-lost, device-unhealthy and device-recovered still reach every live connection whose principal owns the lease. The only lease-shaped state a connection still keeps is the release it is itself performing, so its own lease-lost push is suppressed for the duration of that call. The ttlMs cap lands in the dispatcher, applied identically to a request and a renew, so every transport shares one answer.

HTTP (src/http/) — modeDefaultTtlMs and the tracker's per-lease TTL map are gone. ttlMs on a lease payload is read off the lease record, so a payload served after a daemon restart reports the lease's real width rather than a mode default standing in for a per-request value the gateway used to remember. A body-less POST /v1/leases/{id}/renew re-applies that stored width; a ttlMs above lease.maxTtlMs is 400 BAD_REQUEST on both lease routes (see the review fixes below for where that answer comes from). notices stays HTTP-side and never carries lease_lost.

Frontends — only what the daemon change forces. simlock/client loses the heartbeat option, the lease.heartbeat method, the wire's pong, and the synthesized onLeaseLost on connection loss (ADR 0004 narrows ADR 0003 §10): the leases it held are still granted, so onConnectionLost reports the connection and onLeaseLost only ever reports a lease the daemon actually ended. The CLI stops sending mode, accepts --ttl <duration>, renders lastRenewedAt as "last renewed", and on connection loss writes one DAEMON_CONNECTION_LOST line naming the lease id and its current ttlDeadline, releases nothing, and exits 1. MCP's lease_simulator inherits the contract's optional ttlMs, lease_status no longer filters on mode, and each lease's renew timer reconnects through a new connectToRunningDaemon that reaches an already-listening daemon and never launches one — auto-launch stays a tool-call concern, so an operator's daemon stop is not undone by an idle session.

The wire and config breaks

• Wire: lease.heartbeat (operation, push, hello capability) and mode (request input, lease record) are gone. ttlMs is accepted on every request and capped at lease.maxTtlMs — above it is BAD_REQUEST, never a silent clamp. The lease record carries ttlMs and lastRenewedAt. Protocol 4, no shim: a protocol-3 client and this daemon do not overlap and hello fails PROTOCOL_VERSION_UNSUPPORTED.
• Config: lease.detachedTtlMs, lease.heldTtlBackstopMs and lease.heartbeatIntervalMs are retired. All three are simply unrecognized — warned about and ignored like any other unknown key, no alias and no value carried over — while lease.defaultTtlMs and lease.maxTtlMs are new and validated as a pair. The two treatments differ on purpose: a leftover key has a safe reading ("ignore it"), a self-contradicting TTL pair has none, so the latter fails the start.
• Events (the deliberate 0.x exception to events rule 6, recorded in ADR 0004's Consequences): lease.granted drops mode; lease.released loses the closed and orphaned reasons.
• Behaviour: a SIGKILLed holder keeps its device until expiresAt, and daemon stop releases nothing. A holder that exits normally, is SIGTERMed, or whose parent dies still releases at once — that is its own policy, and it is now the only thing that frees a device early.

Persisted-record migration

A lease record written before this change has no ttlMs and no lastRenewedAt, and neither is recoverable from what is on disk (ttlDeadline - grantedAt is the grant-time width only until the first renewal moves the deadline). So each takes the documented default rather than a guess dressed up as arithmetic: ttlMs from lease.defaultTtlMs (the configured value — daemon/main.ts passes it to Registry.load), lastRenewedAt from grantedAt. A value that is present but unusable takes the same default: a duration must be finite and positive (a 0 would make every later renewal resolve to a deadline in the past), a timestamp only finite (zero is a legitimate point on the clock). A mode still on disk is dropped on load rather than preserved through the unknown-field forward-compatibility path: it is not a field from a newer schema, it is a concept that no longer exists.

Tests

Rewritten, not skipped or deleted. Nothing was deleted outright — every suite that scripted a heartbeat or asserted on mode now asserts the renew/expiry behaviour that replaced it.

• Contract/dispatcher: ttlMs accepted on any request, mode rejected, the cap enforced on both a request and a renew (and accepted at the boundary), a body-less renew re-applying the stored width.
• Config: the pair rule (within a file and across layers), non-positive values naming their key, and each retired key warning while the new keys keep their own defaults.
• Core: grant/renew widths and lastRenewedAt, startup restoring every timer with no sweep, the migration defaults (including mode dropped on the next write, and unusable ttlMs/lastRenewedAt values falling back), and the registry's renewLease writing all three fields together.
• DaemonServer: the heartbeat suite became a liveness suite — a lease survives a connection close and ends at its own deadline, a queued waiter is served by expiry rather than by a disconnect, a stop touches nothing, a restart restores the renewed deadline (and expires a lease whose deadline passed while nothing was running), and lease.heartbeat answers UNKNOWN_REQUEST.
• Frontends: the CLI's connection-loss path (exit 1, one structured line even with a renew in flight, no release attempted) and its reported deadline staying current across renewals; the MCP renew timer reconnecting through connectForRenew and never through the auto-launching connect, with the reconnected client's pushes reaching the session's listeners.
• e2e: heartbeat-ttl.test.ts → renew-ttl.test.ts, around client renewal, the config pair rule, and the TTL cap. held-lease-liveness.test.ts covers what actually changed: a SIGKILLed holder keeps its device until expiry (short lease.defaultTtlMs, assertions wait for expiry rather than for a disconnect), a SIGTERMed one still releases at once, and a lease survives both an ungraceful and a graceful restart and is renewable afterwards. http-api.test.ts covers the cap on both routes, including the allowDownload: true shape. parent-watch.test.ts runs with a deliberately long TTL, so a device freed within seconds can only be the holder's own release path. The suites that used a SIGKILL as a release were fixed to keep their intent: parallel-contention signals SIGTERM (its point is a holder that goes away the moment it is granted, not the daemon's reaction to a dead socket) and asserts eight requesters were served from no more devices than the cap allows, and capacity-cleanup-nuke releases explicitly before killing. mcp-session's restart test asserts the session keeps its lease and renews it over a connection its own timer built — ADR 0004 §2's second reconnect trigger, end to end.

Review fixes

Round 1 (0fcff93). Blocking: the CLI captured its lease deadline from the grant and never updated it, so the DAEMON_CONNECTION_LOST line named the grant-time deadline however long the holder had been renewing — after roughly one TTL of uptime, a moment in the past on a lease that is perfectly alive, and precisely the number a reader would act on; startLeaseRenewal gained an onRenewed hook and the CLI updates from it. Blocking: LeaseCommands still declared LeaseReleaseReason as "closed" | "explicit" | "killed", drifting from the coordinator's narrowed union and leaving releaseAll's Exclude<…, "closed"> vacuous. Plus: connectForRenew no longer falls back to connect; tests for the three untested properties; server.test.ts waits on the daemon's own "Connection closed" log instead of a sleep; the convergence-window comment now admits a lease-lost push can be missed there and says the client learns via UNKNOWN_LEASE on its next renew; stale comments corrected.

Round 2 (223c551). The one behaviour bug: POST /v1/lease-requests settles its 201 synchronously for an allowDownload: true request, so the dispatcher's cap rejection landed after the response and surfaced as a failed request resource instead of 400. The cap is now answered in the route, before tracker.submit. Plus: the registry migration validates a stored duration as positive and finite (and a timestamp as finite), falling back rather than throwing, as its comment already promised; onRenewed's doc corrected for PR A's newest-answer-wins rule, with both adoption paths routed through one adoptDeadline; four comments describing deleted machinery rewritten; the release-all snapshot skew documented; one shared settle() in the CLI tests; and the e2e restart case given a 30s TTL so a kill-and-restart cannot eat its own window.

Round 3 (f546f22, 2ac05e4, 4cf985d). The renew cadence now comes from the lease's own ttlMs — a duration, which needs no clock shared with the daemon — with ttlDeadline left as the bound that caps each wait; that is the reason ADR 0004 stores the width on the record, and both holders pass it. lease.release-all reports killed rather than explicit: docs/EVENTS.md splits the two by whether the lease's holder asked, and an operator taking every lease away is exactly what a lease-lost reader must tell apart from a holder's own release. The route-level TTL cap was removed from POST /v1/leases/{id}/renew, which awaits its dispatch and so inherits the shared answer after ownsLease — checking it earlier turned another requester's lease into a 400 about a TTL where the socket and docs/HTTP-API.md both say 403; it stays only on the async request route, with unit cover for both of that route's shapes. A simlock lease whose socket dies writes exactly one line: the in-flight lease.renew rejects with the same DAEMON_CONNECTION_LOST and is not a second thing to report. #clientForUse's connect-sharing retry no longer depends on which joined caller's finally ran first, and startLeaseRenewal stays silent about a lease after a holder stopped it from inside onError.

Folded in from PR A's final round, in files this branch now owns: an MCP release_simulator stops its lease's renew timer before sending the release (a renew landing in that window answers UNKNOWN_LEASE and would announce the agent's own release as a lost device, which ADR 0003 §8 forbids) and puts it back only when the lease is still the session's to keep; #endSession's abandoned loop stops with its budget instead of calling releaseLease on a closed client; the grant-after-close release drops its nested timer for the budget it already runs inside; close() documents that with no connection left it releases nothing and reconnects for nothing; and the FakeSimlockClient dead-connection guard is now table-driven over every operation rather than two of them.

Final review (7564ea3). Two from a probe of the merged shape: every caller that shared #connecting reached #adoptClient, so a client connected for one and joined by another was wired twice and stranded the first set of push relays (one push, two notices) — only the first adoption wires it now; and a release that failed transiently put the timer back even when a lease-lost push had ended that lease while the release was in flight, so the restart is now conditional on the lease still being in #renewals. Plus daemon/main.ts's stopAuxiliary comment, which still said a stop releases leases, and one assertion each for three properties the reviewer found unguarded by mutation: the shutdown budget stopping the release loop (not just the wait), the session renewing on the lease's own width, and an embedder supplying only connect still getting the non-launching default for renewals.

Validation

pnpm check (typecheck, e2e typecheck, lint, format check, unit, fake-driver e2e; slow-* excluded) green on the final tree: 82 unit files / 1412 tests, 15 e2e files / 50 tests (1 expected fail, 9 skipped as slow).

Deviations from the docs

One, and it is the docs that are being corrected: docs/CLI.md says a daemon that refuses to boot on a bad config surfaces to an auto-starting command as DAEMON_STARTUP_FAILED, while the launcher actually times out and the CLI reports INTERNAL (it never got a response to relay). e2e/renew-ttl.test.ts asserts the real behaviour; docs corrected in #122. Everything else in docs/CLI.md, docs/CLIENT.md, docs/HTTP-API.md, docs/CONFIGURATION.md, docs/ARCHITECTURE.md, docs/EVENTS.md and docs/known-pitfalls.md on claude/adr-0004-c-docs matches the code, including the exit-code split (1 for a dead connection with the lease standing, 14 for a lease the daemon ended), the retired-key treatment, the cap being a rejection rather than a clamp, and the MCP renew timer reconnecting without ever launching a daemon. No docs are edited here — PR C owns them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XsDU7hQcEDhK6kpH8M2YUz