fix(lease): release held leases orphaned by a daemon restart

A held lease's liveness is its daemon connection, so any held lease
still persisted at startup is orphaned by definition -- yet
StartupConverger.converge() re-armed its TTL timer anyway, parking the
device for up to a full heldTtlBackstopMs with no holder.

StartupConverger now releases every held lease (reason "orphaned")
through the normal release path before timers are restored and before
running-capacity convergence, so the freed device is reclaimed and
visible to both. Detached leases are untouched -- their liveness is
the TTL, not a connection -- and keep today's restored timer.

The release capability is injected as a narrow OrphanedLeaseRelease
port, wired in LeaseEngine to the existing LeaseReleaseCoordinator, in
the same style as the converger's existing LeaseTimerRestorer and
InterruptedReclaimRecovery neighbours.

Closes #13

Author: V3RON

docs/ARCHITECTURE.md

@@ -75,11 +75,19 @@ commits the resulting running or non-running state. Global and platform limits
 are checked atomically; no driver-specific runtime details participate in this
 decision.
 
-At startup, `StartupConverger` restores persisted lease TTL timers, recovers
-unleased interrupted reclaims through the warm-pool recovery port, then
-deterministically shuts down excess unleased, unclaimed `ready` registry
-devices through `CleanupActionExecutor`. Leased devices are never touched, so
-a lowered limit may remain visibly over-limit until leases naturally release.
+At startup, `StartupConverger` first releases every persisted `held` lease
+(reason `orphaned`) through the normal release path — a held lease's liveness
+is its daemon connection, so it cannot have a live holder across a restart,
+and this runs before timers are restored so an orphaned lease's timer is
+never re-armed. It then restores persisted TTL timers for the remaining
+(`detached`) leases, whose liveness is the TTL rather than a connection,
+recovers unleased interrupted reclaims through the warm-pool recovery port,
+and finally deterministically shuts down excess unleased, unclaimed `ready`
+registry devices through `CleanupActionExecutor`. Running this release step
+before timer restoration and capacity convergence means the devices it frees
+are visible to both. Leased devices that survive the orphan sweep are never
+touched, so a lowered limit may remain visibly over-limit until leases
+naturally release.
 
 ## Device state machine
 
@@ -183,9 +191,10 @@ capacity coordinator into these direct transactional call chains:
   `CleanupActionExecutor`; the executor revalidates registry ownership,
   lease/state safety, and delegates the driver operation to
   `ManagedDeviceLifecycle`.
-- `StartupConverger` runs timer restoration, interrupted-reclaim recovery, and
-  running-capacity convergence in that order. `NukeService` coordinates lease
-  release, pending-request cancellation, and registry-scoped reset operations.
+- `StartupConverger` runs orphaned held-lease release, timer restoration,
+  interrupted-reclaim recovery, and running-capacity convergence in that
+  order. `NukeService` coordinates lease release, pending-request
+  cancellation, and registry-scoped reset operations.
 
 The serialized decision gate protects only short read-decide-commit sections.
 Driver work remains outside it. Component boundaries use direct calls for

docs/EVENTS.md

@@ -15,7 +15,7 @@ in short: `subject.past-tense-fact`, emitted post-commit, facts not commands.
 | `lease.queued` | request id, queue position | no capacity; request entered the wait queue | LeaseAcquisitionCoordinator | implemented |
 | `lease.granted` | lease id, device id, requester, mode (held/detached) | a device was assigned and handed out | LeaseLifecycle | implemented |
 | `lease.renewed` | lease id, new deadline | detached-mode renew succeeded, **or** a held-mode connection that declared the `heartbeat` capability answered a `lease.heartbeat` push (fires once per lease per `lease.heartbeatIntervalMs` while the holder stays alive) | LeaseLifecycle | implemented |
-| `lease.released` | lease id, device id, reason (closed/explicit/killed) | holder connection closed or explicit release | LeaseLifecycle | implemented |
+| `lease.released` | lease id, device id, reason (closed/explicit/killed/orphaned) | holder connection closed, explicit release, or (orphaned) a `held` lease found still persisted at daemon startup, which cannot have a live holder across a restart | LeaseLifecycle | implemented |
 | `lease.expired` | lease id, device id | TTL backstop fired without a heartbeat sliding it first — for a capability-declaring holder this means it stopped ponging (crashed, hung, or lost its socket); for one that never declared the capability it means the grant-time TTL (or the last explicit `pitlane lease renew`) simply ran out, exactly as before this change | LeaseLifecycle | implemented |
 | `lease.rejected` | request spec, reason (timeout/no-wait/unresolvable-spec/already-leased/boot-timeout/killed) | a request ended without a grant | LeaseAcquisitionCoordinator / WaitQueue | implemented |
 

src/bus/index.ts

@@ -17,7 +17,7 @@ export interface EventMap {
   "lease.released": {
     readonly leaseId: string;
     readonly deviceId: string;
-    readonly reason: "closed" | "explicit" | "killed";
+    readonly reason: "closed" | "explicit" | "killed" | "orphaned";
   };
   "lease.expired": { readonly leaseId: string; readonly deviceId: string };
   "lease.rejected": {

src/core/lease-engine.test.ts

@@ -353,7 +353,7 @@ describe("LeaseEngine", () => {
     const unleasedDevice = await seedReady(harness);
     await harness.registry.createLease({
       deviceId: leasedDevice.id,
-      mode: "held",
+      mode: "detached",
       requesterId: "active",
       ttlDeadline: 2_000,
     });
@@ -425,7 +425,7 @@ describe("LeaseEngine", () => {
       const device = await seedReady(harness);
       await harness.registry.createLease({
         deviceId: device.id,
-        mode: "held",
+        mode: "detached",
         requesterId,
         ttlDeadline: 2_000,
       });

src/core/lease-engine.ts

@@ -164,6 +164,11 @@ export class LeaseEngine {
         },
       },
       registry: options.registry,
+      releases: {
+        releaseOrphaned: async (leaseId) => {
+          await this.#releaseCoordinator.release(leaseId, "orphaned");
+        },
+      },
       timers: this.#leases,
     });
   }

src/core/lease-lifecycle.ts

@@ -124,7 +124,7 @@ export class LeaseLifecycle {
 
   async beginRelease(
     leaseId: string,
-    reason: "closed" | "explicit" | "killed" | "expired",
+    reason: "closed" | "explicit" | "killed" | "orphaned" | "expired",
   ): Promise<ReleasedLease> {
     const released = await this.options.registry.beginRelease(leaseId);
     this.options.expiryScheduler.cancel(leaseId);

src/core/lease-release-coordinator.ts

@@ -3,7 +3,7 @@ import type { ReleasedLease } from "./registry.js";
 import type { SerializedDecision } from "./serialized-decision.js";
 import type { WarmPoolCoordinator } from "./warm-pool-coordinator.js";
 
-export type LeaseReleaseReason = "closed" | "explicit" | "killed";
+export type LeaseReleaseReason = "closed" | "explicit" | "killed" | "orphaned";
 
 export interface LeaseReleaseCommands {
   release(leaseId: string, reason: LeaseReleaseReason): Promise<void>;

src/core/startup-converger.test.ts

@@ -54,9 +54,12 @@ function createHarness(
   const order: string[] = [];
   const claimed = new Set<string>();
   const cleanupCalls: string[] = [];
+  const releasedLeaseIds: string[] = [];
+  let leaseIdsAtTimerRestore: string[] | undefined;
   const timers = {
     restoreExpiryTimers: vi.fn(async () => {
       order.push("timers");
+      leaseIdsAtTimerRestore = leases.map((lease) => lease.id);
     }),
   };
   const recovery = {
@@ -75,6 +78,17 @@ function createHarness(
       return true;
     }),
   };
+  const releases = {
+    releaseOrphaned: vi.fn(async (leaseId: string) => {
+      order.push(`release:${leaseId}`);
+      releasedLeaseIds.push(leaseId);
+      const leaseIndex = leases.findIndex((lease) => lease.id === leaseId);
+      const lease = leases[leaseIndex];
+      if (lease === undefined) return;
+      leases.splice(leaseIndex, 1);
+      updateState(lease.deviceId, "ready");
+    }),
+  };
   const converger = new StartupConverger({
     capacity: {
       get runningCapacity() {
@@ -90,6 +104,7 @@ function createHarness(
         return { devices, leases };
       },
     },
+    releases,
     timers,
   });
 
@@ -99,7 +114,22 @@ function createHarness(
     if (current !== undefined) devices[index] = { ...current, state };
   }
 
-  return { claimed, cleanup, cleanupCalls, converger, devices, order, recovery, timers };
+  return {
+    claimed,
+    cleanup,
+    cleanupCalls,
+    converger,
+    devices,
+    get leaseIdsAtTimerRestore() {
+      return leaseIdsAtTimerRestore;
+    },
+    leases,
+    order,
+    recovery,
+    releasedLeaseIds,
+    releases,
+    timers,
+  };
 }
 
 describe("StartupConverger", () => {
@@ -151,15 +181,15 @@ describe("StartupConverger", () => {
         deviceId: first.id,
         grantedAt: 0,
         id: "lease-1",
-        mode: "held" as const,
+        mode: "detached" as const,
         requesterId: "a",
         ttlDeadline: 10,
       },
       {
         deviceId: second.id,
         grantedAt: 0,
         id: "lease-2",
-        mode: "held" as const,
+        mode: "detached" as const,
         requesterId: "b",
         ttlDeadline: 10,
       },
@@ -201,4 +231,77 @@ describe("StartupConverger", () => {
     expect(harness.cleanupCalls).toEqual(["ready"]);
     expect(harness.timers.restoreExpiryTimers).toHaveBeenCalledTimes(2);
   });
+
+  it("releases an orphaned held lease before timers are restored, freeing its device", async () => {
+    const held = device("held-device", "ios", "leased", 1);
+    const leases = [
+      {
+        deviceId: held.id,
+        grantedAt: 0,
+        id: "lease-held",
+        mode: "held" as const,
+        requesterId: "a",
+        ttlDeadline: 1000,
+      },
+    ];
+    const harness = createHarness([held], leases, { android: 1, global: 1, ios: 1 });
+
+    await harness.converger.converge();
+
+    expect(harness.releases.releaseOrphaned).toHaveBeenCalledTimes(1);
+    expect(harness.releases.releaseOrphaned).toHaveBeenCalledWith("lease-held");
+    expect(harness.order.indexOf("release:lease-held")).toBeLessThan(
+      harness.order.indexOf("timers"),
+    );
+    // The orphaned lease is gone from the registry by the time timers are restored, so its
+    // timer is never re-armed.
+    expect(harness.leaseIdsAtTimerRestore).toEqual([]);
+    expect(harness.devices.find((item) => item.id === held.id)?.state).toBe("ready");
+  });
+
+  it("keeps a detached lease's timer restoration untouched", async () => {
+    const detachedDevice = device("detached-device", "ios", "leased", 1);
+    const leases = [
+      {
+        deviceId: detachedDevice.id,
+        grantedAt: 0,
+        id: "lease-detached",
+        mode: "detached" as const,
+        requesterId: "a",
+        ttlDeadline: 1000,
+      },
+    ];
+    const harness = createHarness([detachedDevice], leases, { android: 1, global: 1, ios: 1 });
+
+    await harness.converger.converge();
+
+    expect(harness.releases.releaseOrphaned).not.toHaveBeenCalled();
+    expect(harness.leaseIdsAtTimerRestore).toEqual(["lease-detached"]);
+    expect(harness.devices.find((item) => item.id === detachedDevice.id)?.state).toBe("leased");
+  });
+
+  it("frees the orphaned lease's device before running-capacity convergence, making it a shutdown candidate", async () => {
+    const held = device("held-device", "ios", "leased", 1);
+    const leases = [
+      {
+        deviceId: held.id,
+        grantedAt: 0,
+        id: "lease-held",
+        mode: "held" as const,
+        requesterId: "a",
+        ttlDeadline: 1000,
+      },
+    ];
+    // maxRunning for ios is 0, so once the device is freed to "ready" it is over capacity
+    // and must be visible to the excess-capacity sweep that follows.
+    const harness = createHarness([held], leases, { android: 1, global: 0, ios: 0 });
+
+    await harness.converger.converge();
+
+    const releaseIndex = harness.order.indexOf("release:lease-held");
+    const cleanupIndex = harness.order.indexOf("cleanup:held-device");
+    expect(releaseIndex).toBeGreaterThanOrEqual(0);
+    expect(cleanupIndex).toBeGreaterThan(releaseIndex);
+    expect(harness.cleanupCalls).toEqual(["held-device"]);
+  });
 });

src/core/startup-converger.ts

@@ -21,6 +21,16 @@ export interface InterruptedReclaimRecovery {
   recoverInterruptedReclaim(device: DeviceRecord): Promise<void>;
 }
 
+/**
+ * Releases a lease orphaned by a daemon restart. A held lease's liveness is
+ * its daemon connection, so any held lease found at startup has no holder by
+ * definition; this port drives it through the normal release path (reason
+ * `orphaned`) so the device is reclaimed and `lease.released` is emitted.
+ */
+export interface OrphanedLeaseRelease {
+  releaseOrphaned(leaseId: string): Promise<void>;
+}
+
 /** Read-only operation claim view used to avoid an in-flight device operation. */
 export interface DeviceClaimReader {
   isClaimed(deviceId: string): boolean;
@@ -33,6 +43,7 @@ export interface StartupConvergerOptions {
   readonly decisions: SerializedDecision;
   readonly interruptedReclaimRecovery: InterruptedReclaimRecovery;
   readonly registry: StartupRegistry;
+  readonly releases: OrphanedLeaseRelease;
   readonly timers: LeaseTimerRestorer;
 }
 
@@ -44,6 +55,7 @@ export class StartupConverger {
   constructor(private readonly options: StartupConvergerOptions) {}
 
   async converge(): Promise<void> {
+    await this.#releaseOrphanedHeldLeases();
     await this.options.timers.restoreExpiryTimers();
     await this.#recoverInterruptedReclaims();
 
@@ -62,6 +74,25 @@ export class StartupConverger {
     }
   }
 
+  /**
+   * A held lease's liveness is its daemon connection, so any lease still in
+   * `held` mode at startup is orphaned by definition — it cannot have a live
+   * holder across a restart. Release it (reason `orphaned`) before timers are
+   * restored, so its timer is never re-armed, and before capacity
+   * convergence, so the freed device is visible to it. Detached leases are
+   * untouched here; their liveness is the TTL, not a connection.
+   */
+  async #releaseOrphanedHeldLeases(): Promise<void> {
+    const orphanedLeaseIds = await this.options.decisions.run(() =>
+      this.options.registry.snapshot.leases
+        .filter((lease) => lease.mode === "held")
+        .map((lease) => lease.id),
+    );
+    for (const leaseId of orphanedLeaseIds) {
+      await this.options.releases.releaseOrphaned(leaseId);
+    }
+  }
+
   async #recoverInterruptedReclaims(): Promise<void> {
     const interrupted = await this.options.decisions.run(() => {
       const snapshot = this.options.registry.snapshot;