feat(daemon): add fenced managed lease admission

Author: thymikee

docs/adr/0021-host-simlock-managed-device-allocation.md

@@ -169,6 +169,16 @@ per managed-device lease. A failed or uncertain renewal fences only the affected
 binding, reconciles through Simlock, and either publishes the confirmed deadline or tears down. No
 command continues on Host's cached deadline alone.
 
+The daemon's lease-admission service is `createManagedLeaseAdmission` under
+`src/daemon/managed-device-allocation/`. One instance belongs to one binding incarnation;
+its coordinator must fence it before release, replacement, or supersession. `managedCommandHorizon`
+reuses the command's request envelope and reserves the canonical teardown budget including recording
+finalization. Unbounded commands require a bounded child request before managed execution.
+An `admitted` result reports only allocator-confirmed authority; `teardown-required` leaves that
+binding permanently fenced. Budget reservation is not proof of cleanup or runner quiescence.
+The neutral service enables no managed runtime or readiness path. Integration follows the reviewed
+managed-operation projection and must use canonical teardown before returning the allocation.
+
 Release is durable and retryable. Host does not publish a replacement grant while Simlock may still
 mutate the device. After either daemon restarts, the journal is reconciled through Simlock lookup: a
 live, authorized mapping reattaches; missing, terminal, stale, or unauthorized work follows

packages/contracts/src/platform-runtime-host.ts

@@ -1,6 +1,7 @@
 import type { DeviceInfo, Platform } from '@agent-device/kernel/device';
 import type { JsonObject, JsonValue } from './json.ts';
 import type { AndroidClipboardShellSupport } from './android-clipboard-support.ts';
+import type { ResourceOwnershipFence, RuntimeOwnerRef } from './platform-runtime.ts';
 
 export type HostCommandRequest = Readonly<{
   executable: string;
@@ -194,14 +195,11 @@ export type PlatformRequestScope = Readonly<{
   signal: AbortSignal;
   diagnostics: PlatformDiagnosticSink;
   progress: PlatformProgressSink;
-}>;
-
-export type ResolvedNativeAsset = Readonly<{
-  path: string;
-  version?: string;
-}>;
-
-/** Asset names stay package-owned literal unions rather than a shared universal catalog. */
-export type NativeAssetResolver<AssetName extends string> = Readonly<{
-  resolve(name: AssetName, signal?: AbortSignal): Promise<ResolvedNativeAsset>;
+  managedDevice?: Readonly<{
+    device: DeviceInfo;
+    owner: Extract<RuntimeOwnerRef, { kind: 'managed-local' }>;
+    fence: ResourceOwnershipFence;
+    ensureReady(): Promise<void>;
+    run<T>(task: () => Promise<T>): Promise<T>;
+  }>;
 }>;

src/daemon/managed-device-allocation/__tests__/command-horizon.test.ts

@@ -0,0 +1,22 @@
+import { afterEach, expect, test, vi } from 'vitest';
+import { managedCommandHorizon } from '../command-horizon.ts';
+import { NOW } from './lease-admission.fixtures.ts';
+
+afterEach(() => vi.restoreAllMocks());
+
+test('command horizons reuse descriptor budgets and reject unbounded requests', () => {
+  vi.spyOn(Date, 'now').mockReturnValue(NOW);
+  const req = { command: 'wait', session: 'managed', positionals: ['text', 'Ready', '180000'] };
+  const wait = managedCommandHorizon(req, NOW - 1_000);
+  expect(wait.deadline.remainingMs()).toBe(209_000);
+  expect(wait.teardownTimeoutMs).toBe(16_000);
+  expect(
+    managedCommandHorizon(
+      { command: 'install', session: 'managed', positionals: [] },
+      NOW,
+    ).deadline.remainingMs(),
+  ).toBe(180_000);
+  expect(() =>
+    managedCommandHorizon({ command: 'test', session: 'managed', positionals: [] }, NOW),
+  ).toThrow(expect.objectContaining({ details: { reason: 'managed-command-deadline-unbounded' } }));
+});

src/daemon/managed-device-allocation/__tests__/lease-admission.fixtures.ts

@@ -0,0 +1,59 @@
+import type {
+  LeaseRequestStatus,
+  ManagedLease,
+} from '@agent-device/contracts/managed-device-allocation';
+import { Deadline } from '@agent-device/host-kit/retry';
+import { createManagedLeaseReachability } from '../../../managed-device-reachability.ts';
+import { createScriptedManagedDeviceAllocator } from '../../../__tests__/test-utils/managed-device-allocator.fixtures.ts';
+import { createManagedLeaseAdmission } from '../lease-admission.ts';
+import { ALLOCATION_GRANTED_STATUS, ALLOCATION_LEASE } from './fixtures.ts';
+
+export const NOW = 1_700_000_000_000;
+export const controller = () => new AbortController();
+export const horizon = (milliseconds = 10_000) => ({
+  deadline: Deadline.fromTimeoutMs(milliseconds),
+  teardownTimeoutMs: 5_000,
+});
+export const renewedLease = (overrides: Partial<ManagedLease> = {}): ManagedLease => ({
+  ...ALLOCATION_LEASE,
+  ttlDeadline: NOW + 100_000,
+  ...overrides,
+});
+export const granted = (overrides: Partial<LeaseRequestStatus> = {}): LeaseRequestStatus => ({
+  ...ALLOCATION_GRANTED_STATUS,
+  lease: renewedLease(),
+  ...overrides,
+});
+export const unknownStatus: LeaseRequestStatus = {
+  ...ALLOCATION_GRANTED_STATUS,
+  state: 'unknown',
+  lease: undefined,
+};
+
+export function setupAdmission(
+  options: {
+    grant?: LeaseRequestStatus;
+    script?: NonNullable<Parameters<typeof createScriptedManagedDeviceAllocator>[0]>['script'];
+    safetyWindowMs?: number;
+  } = {},
+) {
+  const grant = options.grant ?? granted({ lease: renewedLease({ ttlDeadline: NOW + 5_000 }) });
+  if (!grant.lease) throw new Error('Fixture needs a lease');
+  const allocator = createScriptedManagedDeviceAllocator({ script: options.script });
+  const reachability = createManagedLeaseReachability({ platform: 'ios', lease: grant.lease });
+  const admission = createManagedLeaseAdmission({
+    allocator,
+    grant,
+    reachability,
+    renewalSafetyWindowMs: options.safetyWindowMs ?? 5_000,
+  });
+  return { allocator, admission, grant, reachability };
+}
+
+export function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((done) => {
+    resolve = done;
+  });
+  return { promise, resolve };
+}

src/daemon/managed-device-allocation/__tests__/lease-admission.test.ts

@@ -0,0 +1,224 @@
+import { beforeEach, afterEach, expect, test, vi } from 'vitest';
+import type {
+  LeaseRequestStatus,
+  ManagedLease,
+} from '@agent-device/contracts/managed-device-allocation';
+import {
+  NOW,
+  controller,
+  deferred,
+  granted,
+  horizon,
+  renewedLease,
+  setupAdmission,
+  unknownStatus,
+} from './lease-admission.fixtures.ts';
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(NOW);
+});
+afterEach(() => vi.useRealTimers());
+
+test('reuses only an allocator-confirmed horizon outside the safety window', async () => {
+  const { admission, allocator } = setupAdmission({ grant: granted() });
+  const task = vi.fn(async () => 'value');
+  expect(await admission.run(horizon(), controller().signal, task)).toMatchObject({
+    status: 'admitted',
+    ttlDeadline: NOW + 100_000,
+    value: 'value',
+  });
+  expect(allocator.calls).toEqual([]);
+  const near = setupAdmission({
+    grant: granted(),
+    safetyWindowMs: 100_000,
+    script: { renewLease: [renewedLease({ ttlDeadline: NOW + 200_000 })] },
+  });
+  expect((await near.admission.run(horizon(), controller().signal, task)).status).toBe('admitted');
+  expect(near.allocator.calls).toHaveLength(1);
+});
+
+test('same-lease waiters share renewal while a different lease proceeds independently', async () => {
+  const pending = deferred<ManagedLease>();
+  const first = setupAdmission({ script: { renewLease: [pending.promise] } });
+  const task = vi.fn(async () => {});
+  const a = first.admission.run(horizon(), controller().signal, task);
+  const b = first.admission.run(horizon(), controller().signal, task);
+  const other = setupAdmission({
+    grant: granted({ lease: renewedLease({ id: 'lease-2', ttlDeadline: NOW + 1_000 }) }),
+    script: { renewLease: [renewedLease({ id: 'lease-2' })] },
+  });
+  expect((await other.admission.run(horizon(), controller().signal, async () => {})).status).toBe(
+    'admitted',
+  );
+  expect(first.allocator.calls).toHaveLength(1);
+  expect(task).not.toHaveBeenCalled();
+  pending.resolve(renewedLease());
+  expect((await Promise.all([a, b])).map((result) => result.status)).toEqual([
+    'admitted',
+    'admitted',
+  ]);
+});
+
+test('a longer-horizon waiter obtains its own confirmation after joining a shorter renewal', async () => {
+  const short = deferred<ManagedLease>();
+  const long = deferred<ManagedLease>();
+  const { admission, allocator } = setupAdmission({
+    script: { renewLease: [short.promise, long.promise] },
+  });
+  const longTask = vi.fn(async () => {});
+  const a = admission.run(horizon(), controller().signal, async () => {});
+  const b = admission.run(horizon(200_000), controller().signal, longTask);
+  short.resolve(renewedLease());
+  expect((await a).status).toBe('admitted');
+  expect(longTask).not.toHaveBeenCalled();
+  expect(allocator.calls[1]).toEqual({
+    method: 'renewLease',
+    input: { leaseId: 'lease-1', ttlDeadline: NOW + 210_000 },
+  });
+  long.resolve(renewedLease({ ttlDeadline: NOW + 205_000 }));
+  expect((await b).status).toBe('admitted');
+});
+
+test.each([
+  { ttlDeadline: NOW - 1 },
+  { ttlDeadline: NOW + 14_999 },
+  { ttlDeadline: Number.NaN },
+  { ttlDeadline: Number.POSITIVE_INFINITY },
+  { id: 'wrong' },
+  { device: { address: 'wrong' } },
+  { environment: { SIMLOCK_IOS_DEVICE_SET: '/foreign' } },
+])('invalid renewal %j never becomes local authority', async (overrides) => {
+  const { admission, allocator } = setupAdmission({
+    script: { renewLease: [renewedLease(overrides)], getLeaseRequestStatus: [unknownStatus] },
+  });
+  const task = vi.fn(async () => {});
+  expect(await admission.run(horizon(), controller().signal, task)).toMatchObject({
+    status: 'teardown-required',
+    reason: 'authority-unconfirmed',
+  });
+  expect((await admission.run(horizon(), controller().signal, task)).status).toBe(
+    'teardown-required',
+  );
+  expect(task).not.toHaveBeenCalled();
+  expect(allocator.calls.map((call) => call.method)).toEqual([
+    'renewLease',
+    'getLeaseRequestStatus',
+  ]);
+});
+
+test('a lost renewal response is reconciled through the exact durable attempt', async () => {
+  const { admission, allocator } = setupAdmission({
+    script: { renewLease: [new Error('lost response')], getLeaseRequestStatus: [granted()] },
+  });
+  expect(
+    await admission.run(horizon(), controller().signal, async () => 'confirmed'),
+  ).toMatchObject({ status: 'admitted', ttlDeadline: NOW + 100_000 });
+  expect(allocator.calls[1]).toEqual({
+    method: 'getLeaseRequestStatus',
+    input: { requesterId: 'requester-a', attemptKey: 'attempt-1' },
+  });
+});
+
+test.each([
+  unknownStatus,
+  granted({ state: 'cancelled' }),
+  granted({ state: 'superseded' }),
+  granted({ state: 'pending' }),
+  granted({ state: 'refused' }),
+  granted({ requesterId: 'other' }),
+  granted({ attemptKey: 'other' }),
+  granted({ requestGeneration: 2 }),
+  granted({ identityIncarnationId: 'other' }),
+  granted({ lease: renewedLease({ ttlDeadline: NOW + 14_999 }) }),
+  new Error('lookup unavailable'),
+])('unconfirmed lookup %j requires canonical teardown', async (status) => {
+  const { admission } = setupAdmission({
+    script: { renewLease: [new Error('renewal failed')], getLeaseRequestStatus: [status] },
+  });
+  const task = vi.fn(async () => {});
+  expect((await admission.run(horizon(), controller().signal, task)).status).toBe(
+    'teardown-required',
+  );
+  expect(task).not.toHaveBeenCalled();
+});
+
+test('abort abandons one caller and does not cancel renewal or another waiter', async () => {
+  const pending = deferred<ManagedLease>();
+  const { admission, allocator } = setupAdmission({ script: { renewLease: [pending.promise] } });
+  const abort = controller();
+  const task = vi.fn(async () => {});
+  const a = admission.run(horizon(), abort.signal, task);
+  const b = admission.run(horizon(), controller().signal, async () => {});
+  abort.abort();
+  expect(await a).toEqual({ status: 'abandoned' });
+  pending.resolve(renewedLease());
+  expect((await b).status).toBe('admitted');
+  expect(task).not.toHaveBeenCalled();
+  expect(allocator.calls).toHaveLength(1);
+});
+
+test('caller deadline ends the wait while a late renewal can still confirm authority', async () => {
+  const pending = deferred<ManagedLease>();
+  const { admission, allocator } = setupAdmission({ script: { renewLease: [pending.promise] } });
+  const a = admission.run(horizon(), controller().signal, async () => {
+    throw new Error('expired operation');
+  });
+  await vi.advanceTimersByTimeAsync(10_000);
+  expect(await a).toEqual({ status: 'deadline-exceeded' });
+  pending.resolve(renewedLease());
+  expect((await admission.run(horizon(), controller().signal, async () => {})).status).toBe(
+    'admitted',
+  );
+  expect(allocator.calls).toHaveLength(1);
+});
+
+test.each(['released', 'replaced', 'superseded', 'fenced'] as const)(
+  '%s binding cannot be revived by a late renewal or lookup',
+  async (reason) => {
+    for (const recovering of [false, true]) {
+      const pending = deferred<ManagedLease | LeaseRequestStatus>();
+      const script = recovering
+        ? { renewLease: [new Error('lost')], getLeaseRequestStatus: [pending.promise] }
+        : { renewLease: [pending.promise] };
+      const { admission, allocator } = setupAdmission({ script });
+      const task = vi.fn(async () => {});
+      const a = admission.run(horizon(), controller().signal, task);
+      if (recovering) await vi.waitFor(() => expect(allocator.calls).toHaveLength(2));
+      admission.fenceBinding(reason);
+      pending.resolve(recovering ? granted() : renewedLease());
+      expect(await a).toMatchObject({ status: 'teardown-required', reason });
+      expect((await admission.run(horizon(), controller().signal, task)).status).toBe(
+        'teardown-required',
+      );
+      expect(task).not.toHaveBeenCalled();
+    }
+  },
+);
+
+test('an already aborted caller starts no allocator work and an operation failure stays primary', async () => {
+  const abort = controller();
+  abort.abort();
+  const { admission, allocator } = setupAdmission({ grant: granted() });
+  expect(await admission.run(horizon(), abort.signal, async () => {})).toEqual({
+    status: 'abandoned',
+  });
+  const failure = new Error('operation failed');
+  await expect(
+    admission.run(horizon(), controller().signal, async () => {
+      throw failure;
+    }),
+  ).rejects.toBe(failure);
+  expect(allocator.calls).toEqual([]);
+});
+
+test('fencing wakes a waiter even when durable renewal never responds', async () => {
+  const { admission } = setupAdmission({
+    script: { renewLease: [deferred<ManagedLease>().promise] },
+  });
+  const waiter = admission.run(horizon(), controller().signal, async () => {
+    throw new Error('fenced operation');
+  });
+  admission.fenceBinding('released');
+  expect(await waiter).toEqual({ status: 'teardown-required', reason: 'released' });
+});

src/daemon/managed-device-allocation/command-horizon.ts

@@ -0,0 +1,32 @@
+import { Deadline } from '@agent-device/host-kit/retry';
+import { AppError } from '@agent-device/kernel/errors';
+import { resolveDaemonRequestTimeoutMs } from '../request-timeout.ts';
+import { resolveDaemonSessionTeardownTimeoutMs } from '../session-teardown-budget.ts';
+import type { DaemonRequest } from '../types.ts';
+import type { ManagedCommandHorizon } from './lease-admission.ts';
+
+/** Reserve recording cleanup even when this command is the one that starts the capture. */
+export function managedCommandHorizon(
+  req: Omit<DaemonRequest, 'token'>,
+  startedAtMs: number,
+): ManagedCommandHorizon {
+  const timeoutMs = resolveDaemonRequestTimeoutMs(req);
+  if (
+    timeoutMs === undefined ||
+    !Number.isFinite(timeoutMs) ||
+    timeoutMs <= 0 ||
+    !Number.isFinite(startedAtMs)
+  ) {
+    throw new AppError(
+      'UNSUPPORTED_OPERATION',
+      'Managed commands require a finite request deadline.',
+      {
+        reason: 'managed-command-deadline-unbounded',
+      },
+    );
+  }
+  return Object.freeze({
+    deadline: Deadline.fromTimeoutMs(timeoutMs, startedAtMs),
+    teardownTimeoutMs: resolveDaemonSessionTeardownTimeoutMs(undefined, true),
+  });
+}