refactor(apple): simplify warm runner ownership

docs/adr/0005-ios-runner-interaction-lifecycle.md

@@ -115,9 +115,14 @@ If xcodebuild still exits for another reason, the next command detects the stale
 process/liveness checks and avoids the old 15-second graceful-shutdown wait. The remaining latency is
 fresh xcodebuild runner startup, not a stale transport stall.
 
-A `close` then `open` on a runner still draining abandoned main-thread work now pays a fresh runner boot
-instead of inheriting the stalled one, so the wedge no longer survives the close/open cycle. Runners
-that were never reported busy keep the existing warm-reuse path unchanged.
+A `close` then `open` on a runner still draining abandoned main-thread work now pays a fresh runner
+boot instead of inheriting the stalled one, so the wedge no longer survives the close/open cycle.
+Runners that are ready and have no unanswered exchanges can remain warm when retention is requested;
+iOS-family simulators additionally require an observed live listener. Close retires unfinished
+startup and its recovery authority. The retained generation owns its idle timer and listener
+observation; successful reuse ends retention, listener loss or idle expiry disposes that generation,
+and graceful daemon shutdown stops idle retained generations before exiting. Active ready
+generations retain the existing handoff policy.
 
 The daemon no longer models a generic "recent success" cache as a runner-health signal. A proven
 healthy mutating response for the same app — recorded only after the `runnerFatal` check and only

docs/agents/device-verification.md

@@ -10,8 +10,9 @@ physical devices. Live verification steps apply when exercising a device-facing
 - Before any Android verification from source: `pnpm build`, `pnpm build:android`, `pnpm clean:daemon`.
   `build:android` refreshes and verifies both bundled Android helper artifacts for the current
   package version.
-- Graceful `shutdown` hands off a healthy runner that already answered a command, on the simulator
-  and physical iOS lanes alike; a new daemon may adopt the old binary. After
+- Graceful `shutdown` hands off an active healthy runner that already answered a command, on the
+  simulator and physical iOS lanes alike; a new daemon may adopt the old binary. A runner retained
+  idle after `close` is stopped before the daemon exits. After
   Swift runner changes, run `pnpm build:xcuitest` before verification. Use the session cleanup
   procedure below if ownership is stuck. The physical handoff's device steps are
   `docs/evidence/ios-physical-runner-handoff-2026-09-19.md`; nothing in it is proven until someone

packages/kernel/src/keyed-lock.test.ts

@@ -64,3 +64,92 @@ test('withKeyedLock allows reentrant work for the same key while holding the out
 
   assert.deepEqual(order, ['outer-start', 'inner', 'outer-end', 'competing']);
 });
+
+test('a deferred descendant of a released lock queues behind its current owner', async () => {
+  const locks = new Map<string, Promise<unknown>>();
+  const order: string[] = [];
+  let timerAttempted!: () => void;
+  const attempted = new Promise<void>((resolve) => {
+    timerAttempted = resolve;
+  });
+  let descendant!: Promise<void>;
+  await withKeyedLock(locks, 'device-a', async () => {
+    descendant = new Promise<void>((resolve, reject) => {
+      setTimeout(() => {
+        timerAttempted();
+        withKeyedLock(locks, 'device-a', async () => {
+          order.push('descendant');
+        }).then(resolve, reject);
+      }, 0);
+    });
+  });
+  let releaseOwner!: () => void;
+  const ownerGate = new Promise<void>((resolve) => {
+    releaseOwner = resolve;
+  });
+  let ownerStarted!: () => void;
+  const started = new Promise<void>((resolve) => {
+    ownerStarted = resolve;
+  });
+  const owner = withKeyedLock(locks, 'device-a', async () => {
+    order.push('owner');
+    ownerStarted();
+    await ownerGate;
+    order.push('released');
+  });
+  await started;
+  await attempted;
+  await new Promise<void>((resolve) => setImmediate(resolve));
+  assert.deepEqual(order, ['owner']);
+  releaseOwner();
+  await Promise.all([owner, descendant]);
+  assert.deepEqual(order, ['owner', 'released', 'descendant']);
+});
+
+test.each([false, true])(
+  'reentrant descendants settle before the next owner (reject=%s)',
+  async (reject) => {
+    const locks = new Map<string, Promise<unknown>>();
+    const order: string[] = [];
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    let markStarted!: () => void;
+    const started = new Promise<void>((resolve) => {
+      markStarted = resolve;
+    });
+    let descendant!: Promise<void>;
+    const owner = withKeyedLock(locks, 'device-a', async () => {
+      queueMicrotask(() => {
+        descendant = withKeyedLock(locks, 'device-a', async () => {
+          order.push('descendant');
+          markStarted();
+          await gate;
+          order.push('finished');
+          void withKeyedLock(locks, 'device-a', async () => {
+            await new Promise<void>((resolve) => setImmediate(resolve));
+            order.push('nested');
+          });
+          if (reject) throw new Error('descendant failed');
+        });
+        void descendant.catch(() => {});
+      });
+    });
+    const competing = withKeyedLock(locks, 'device-a', async () => {
+      order.push('competing');
+    });
+    await started;
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    const beforeRelease = [...order];
+    release();
+    const [, outcome] = await Promise.all([
+      owner,
+      descendant.catch((error: Error) => error),
+      competing,
+    ]);
+    assert.equal(outcome instanceof Error, reject);
+    assert.deepEqual(beforeRelease, ['descendant']);
+    assert.deepEqual(order, ['descendant', 'finished', 'nested', 'competing']);
+  },
+);

packages/kernel/src/keyed-lock.ts

@@ -3,6 +3,8 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 type LockFrame = {
   locks: Map<string, Promise<unknown>>;
   key: string;
+  active: boolean;
+  descendants: Set<Promise<void>>;
 };
 
 const keyedLockStorage = new AsyncLocalStorage<LockFrame[]>();
@@ -13,13 +15,37 @@ export async function withKeyedLock<T>(
   task: () => Promise<T>,
 ): Promise<T> {
   const activeLocks = keyedLockStorage.getStore() ?? [];
-  if (activeLocks.some((entry) => entry.locks === locks && entry.key === key)) {
-    return await task();
+  const held = activeLocks.find(
+    (entry) => entry.active && entry.locks === locks && entry.key === key,
+  );
+  if (held) {
+    let markSettled!: () => void;
+    const settled = new Promise<void>((resolve) => {
+      markSettled = resolve;
+    });
+    held.descendants.add(settled);
+    try {
+      return await task();
+    } finally {
+      held.descendants.delete(settled);
+      markSettled();
+    }
   }
   const previous = locks.get(key) ?? Promise.resolve();
   const current = previous
     .catch(() => {})
-    .then(() => keyedLockStorage.run([...activeLocks, { locks, key }], task));
+    .then(async () => {
+      const frame: LockFrame = { locks, key, active: true, descendants: new Set() };
+      try {
+        return await keyedLockStorage.run(
+          [...activeLocks.filter((entry) => entry.active), frame],
+          task,
+        );
+      } finally {
+        while (frame.descendants.size > 0) await Promise.all(frame.descendants);
+        frame.active = false;
+      }
+    });
   locks.set(key, current);
   return current.finally(() => {
     if (locks.get(key) === current) {