fix: bind capture adoption to session lifetimes

docs/adr/0030-process-lock-exclusion.md

@@ -40,6 +40,32 @@ guard cannot constrain legacy code after its final check. The support boundary t
 requires deployment control; host-kit does not claim to detect or evict every legacy user.
 
 Daemon registration has a separate cutover boundary: keep the same `daemon.lock` path and
-refuse legacy files rather than automatically reclaiming them. Its startup tests must cover
-an already-running older daemon and concurrent old/new startup. This does not expand the
-host-kit mixed-protocol support contract.
+refuse legacy files rather than automatically reclaiming them. A legacy daemon creates an
+exclusive file; a hardened daemon creates a directory at that same path. The old acquisition
+cannot unlink a directory, and the new acquisition retains an existing file.
+
+The [registration tests](../../src/__tests__/daemon-registration-owner.test.ts) exercise real
+children using the c237027737 legacy acquisition and the current owner. They cover an older
+daemon already running, a hardened owner waiting to publish metadata, and concurrent startup.
+The client refuses an older registration before signaling or changing it. This proves the daemon
+cutover; it does not expand the host-kit mixed-protocol support contract. Older clients still
+require the deployment controls above.
+
+## Registration operations
+
+[Shared retirement](../../src/daemon-registration-owner.ts) owns verified termination, protected
+metadata inspection and removal, and release. Takeover, failed startup, replay cleanup, timeout
+reset and manual stop await its result. Abandoned recovery uses the same protected retirement
+sequence without signaling a live process. Daemon publication and shutdown use functions bound
+to their acquired claim.
+
+```mermaid
+flowchart LR
+    C[Client lifecycle and timeout] --> R[Shared retirement]
+    M[Manual stop] --> R
+    P[Abandoned recovery and pruning] --> R
+    R --> L[Acquired registration claim]
+    D[Daemon startup and shutdown] --> O[Functions bound to own claim]
+    O --> L
+    L --> F[Protected metadata and reports]
+```

packages/capture-kit/src/capture-admission/__tests__/audio-probe-session-resource.test.ts

@@ -1,3 +1,4 @@
+import { makeCaptureSessionBinding } from '../../durable-capture/session-binding.fixtures.ts';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { expect, test, vi } from 'vitest';
@@ -44,6 +45,10 @@ test('audio-probe disposes on a failed finish because terminating the helper is
   );
   const session: DurableCaptureSessionState = {};
   sessionStore.set(sessionName, session);
+  const binding = makeCaptureSessionBinding(sessionStore, sessionName, {
+    read: (session) => session.audioProbe,
+    replace: (session, audioProbe) => ({ ...session, audioProbe }),
+  });
   const statusPath = path.join(sessionStore.resolveSessionDir(sessionName), 'audio-probe.json');
   const terminate = vi.fn(async () => {});
   let resolveExit!: (result: HostCommandResult) => void;
@@ -85,9 +90,7 @@ test('audio-probe disposes on a failed finish because terminating the helper is
   });
   await adoptStartedAudioProbe({
     admissionLedger: createAudioProbeAdmissionLedger(),
-    session,
-    sessionName,
-    sessionStore,
+    binding,
     device,
     owner: localRuntimeOwner('apple'),
     fence,

packages/capture-kit/src/capture-admission/__tests__/durable-capture-resource.fixtures.ts

@@ -1,3 +1,4 @@
+import { makeCaptureSessionBinding } from '../../durable-capture/session-binding.fixtures.ts';
 import { vi } from 'vitest';
 import type { AppLogCompletion, AppLogLiveHandle } from '@agent-device/contracts/app-log-runtime';
 import type { CleanupOutcome, FinishOutcome } from '@agent-device/contracts/durable-resource';
@@ -72,6 +73,10 @@ export function makeDurableCaptureContext(
   const session: TestCaptureSession = {};
   sessionStore.set(sessionName, session);
   return {
+    binding: makeCaptureSessionBinding(sessionStore, sessionName, {
+      read: (session) => session.appLog,
+      replace: (session, appLog) => ({ ...session, appLog, appLogFailure: undefined }),
+    }),
     admissionLedger: createDurableCaptureAdmissionLedger({ displayName: 'test capture' }),
     session,
     sessionName,

packages/capture-kit/src/capture-admission/__tests__/screen-recording-boundary-faults.test.ts

@@ -1,3 +1,4 @@
+import { makeCaptureSessionBinding } from '../../durable-capture/session-binding.fixtures.ts';
 import path from 'node:path';
 import { expect, test, vi } from 'vitest';
 import { createDurableResourceEnvelope } from '../../durable-resource-envelope.ts';
@@ -217,9 +218,14 @@ function makeContext(resource: ReturnType<typeof createScreenRecordingTestResour
   const sessionName = 'recording';
   const session: DurableCaptureSessionState = {};
   sessionStore.set(sessionName, session);
+  const binding = makeCaptureSessionBinding(sessionStore, sessionName, {
+    read: (session) => session.screenRecording,
+    replace: (session, screenRecording) => ({ ...session, screenRecording }),
+  });
   return {
     admissionLedger: createDurableCaptureAdmissionLedger({ displayName: 'screen recording' }),
     session,
+    binding,
     sessionName,
     sessionStore,
     device,

packages/capture-kit/src/capture-admission/__tests__/screen-recording-session-resource.test.ts

@@ -1,3 +1,4 @@
+import { makeCaptureSessionBinding } from '../../durable-capture/session-binding.fixtures.ts';
 import { expect, test, vi } from 'vitest';
 import { PendingTransferGuard } from '@agent-device/contracts/async-lifecycle';
 import { localRuntimeOwner } from '@agent-device/contracts/platform-runtime';
@@ -35,6 +36,10 @@ test('screen recording persists durable truth before adopting only handle and en
   const sessionName = 'recording';
   const session: TestRecordingSession = { name: sessionName, device };
   sessionStore.set(sessionName, session);
+  const binding = makeCaptureSessionBinding(sessionStore, sessionName, {
+    read: (session) => session.screenRecording,
+    replace: (session, screenRecording) => ({ ...session, screenRecording }),
+  });
   const owner = localRuntimeOwner('android');
   const fence = { token: 'recording-fence', generation: 1 } as const;
   const finish = vi.fn(async () => ({
@@ -79,9 +84,7 @@ test('screen recording persists durable truth before adopting only handle and en
 
   await adoptStartedScreenRecording({
     admissionLedger: createScreenRecordingAdmissionLedger(),
-    session,
-    sessionName,
-    sessionStore,
+    binding,
     device: session.device,
     owner,
     fence,
@@ -103,7 +106,10 @@ test('screen recording persists durable truth before adopting only handle and en
   if (!active) throw new Error('Expected screen-recording session');
   await expect(
     finishLiveScreenRecording({ intent: 'capture', session: active, sessionName, sessionStore }),
-  ).resolves.toMatchObject({ backend: 'android', outPath: '/tmp/recording.mp4' });
+  ).resolves.toMatchObject({
+    backend: 'android',
+    outPath: '/tmp/recording.mp4',
+  });
   expect(finish).toHaveBeenCalledOnce();
   expect(sessionStore.get(sessionName)?.screenRecording).toBeUndefined();
 });
@@ -115,6 +121,10 @@ test('a failed recording finish keeps the record open and never disposes the rec
   const sessionName = 'recording';
   const session: TestRecordingSession = { name: sessionName, device };
   sessionStore.set(sessionName, session);
+  const binding = makeCaptureSessionBinding(sessionStore, sessionName, {
+    read: (session) => session.screenRecording,
+    replace: (session, screenRecording) => ({ ...session, screenRecording }),
+  });
   const owner = localRuntimeOwner('android');
   const fence = { token: 'recording-fence', generation: 1 } as const;
   const finishError = new Error('failed to retrieve playable Android recording');
@@ -150,9 +160,7 @@ test('a failed recording finish keeps the record open and never disposes the rec
   });
   await adoptStartedScreenRecording({
     admissionLedger: createScreenRecordingAdmissionLedger(),
-    session,
-    sessionName,
-    sessionStore,
+    binding,
     device: session.device,
     owner,
     fence,
@@ -182,6 +190,10 @@ test('a record stop that fails after collecting resumes through the fence withou
   const sessionName = 'recording';
   const session: TestRecordingSession = { name: sessionName, device };
   sessionStore.set(sessionName, session);
+  const binding = makeCaptureSessionBinding(sessionStore, sessionName, {
+    read: (session) => session.screenRecording,
+    replace: (session, screenRecording) => ({ ...session, screenRecording }),
+  });
   const owner = localRuntimeOwner('android');
   const fence = { token: 'recording-fence', generation: 1 } as const;
   const signals = vi.fn(async () => ({ observation: { recorder: 'confirmed' as const } }));
@@ -216,9 +228,7 @@ test('a record stop that fails after collecting resumes through the fence withou
   );
   await adoptStartedScreenRecording({
     admissionLedger: createScreenRecordingAdmissionLedger(),
-    session,
-    sessionName,
-    sessionStore,
+    binding,
     device: session.device,
     owner,
     fence,
@@ -239,7 +249,7 @@ test('a record stop that fails after collecting resumes through the fence withou
     if (!active) throw new Error('Expected screen-recording session');
     return finishLiveScreenRecording({
       intent: 'capture',
-      session: active,
+      session: sessionStore.get(sessionName) ?? session,
       sessionName,
       sessionStore,
     });

packages/capture-kit/src/capture-admission/__tests__/session-store.fixtures.ts

@@ -1,13 +1,13 @@
 import path from 'node:path';
 import { safeSessionName } from '@agent-device/host-kit/session-paths';
-import type { DurableCaptureSessionStore } from '../../durable-capture/index.ts';
 import { mkdtempForTestSync } from '../../tmp-dir.fixtures.ts';
 
-export type CaptureAdmissionSessionStore<S> = DurableCaptureSessionStore<S> &
-  Readonly<{
-    get(name: string): S | undefined;
-    sessionsDir: string;
-  }>;
+export type CaptureAdmissionSessionStore<S> = Readonly<{
+  set(name: string, session: S): void;
+  resolveSessionDir(name: string): string;
+  get(name: string): S | undefined;
+  sessionsDir: string;
+}>;
 
 /**
  * The whole of the daemon `SessionStore` these admission modules ever address — `set`,

packages/capture-kit/src/capture-admission/audio-probe-session-resource.ts

@@ -9,7 +9,10 @@ import type {
   RuntimeOwnerRef,
 } from '@agent-device/contracts/platform-runtime';
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import type { DurableCaptureSessionStore } from '../durable-capture/index.ts';
+import type {
+  DurableCaptureSessionBinding,
+  DurableCaptureSessionStore,
+} from '../durable-capture/index.ts';
 import { createDurableCaptureResource } from './durable-capture-resource.ts';
 import type { DurableCaptureFinishIntent } from './durable-capture-resource.ts';
 import type { AudioProbeAdmissionLedger } from './audio-probe-admission-ledger.ts';
@@ -48,9 +51,7 @@ export const audioProbeDurableResource = createDurableCaptureResource<
 
 export function adoptStartedAudioProbe(params: {
   admissionLedger: AudioProbeAdmissionLedger;
-  session: DurableCaptureSessionState;
-  sessionName: string;
-  sessionStore: DurableCaptureSessionStore<DurableCaptureSessionState>;
+  binding: DurableCaptureSessionBinding<'audio-probe', AudioProbeLiveHandle>;
   device: DeviceInfo;
   owner: RuntimeOwnerRef;
   fence: ResourceOwnershipFence;

packages/capture-kit/src/capture-admission/durable-capture-resource.ts

@@ -23,8 +23,8 @@ import type { DurableSessionResourceKind } from './durable-session-resource-kind
 
 export type { DurableCaptureFinishIntent, DurableSessionResourceKind };
 
-type AdoptStartedSessionCaptureParams<K extends string, H extends AsyncDisposable, S> = Omit<
-  AdoptStartedDurableCaptureParams<K, H, S>,
+type AdoptStartedSessionCaptureParams<K extends string, H extends AsyncDisposable> = Omit<
+  AdoptStartedDurableCaptureParams<K, H>,
   'reportUndurableCleanup'
 > &
   Readonly<{ admissionLedger: DurableCaptureAdmissionLedger }>;
@@ -48,7 +48,7 @@ export function createDurableCaptureResource<
   S,
 >(definition: DurableCaptureResourceDefinition<K, H, C, S>) {
   const sessionResourcePath = (
-    sessionStore: DurableCaptureSessionStore<S>,
+    sessionStore: Readonly<{ resolveSessionDir(name: string): string }>,
     sessionName: string,
   ): string => definition.store.resolvePath(sessionStore.resolveSessionDir(sessionName));
   const recoveryParams = (
@@ -70,7 +70,7 @@ export function createDurableCaptureResource<
     }): ResourceOwnershipFence {
       return createNextDurableCaptureFence(definition, params);
     },
-    adoptStarted(params: AdoptStartedSessionCaptureParams<K, H, S>): Promise<void> {
+    adoptStarted(params: AdoptStartedSessionCaptureParams<K, H>): Promise<void> {
       return adoptStartedDurableCapture(
         definition,
         {
@@ -80,7 +80,7 @@ export function createDurableCaptureResource<
             else params.admissionLedger.blockUndurableCleanup(device, outcome.reason);
           },
         },
-        sessionResourcePath(params.sessionStore, params.sessionName),
+        definition.store.resolvePath(params.binding.sessionDir),
       );
     },
     finishLive(params: {

packages/capture-kit/src/capture-admission/perf-capture-session-resource.ts

@@ -9,7 +9,10 @@ import type {
   RuntimeOwnerRef,
 } from '@agent-device/contracts/platform-runtime';
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import type { DurableCaptureSessionStore } from '../durable-capture/index.ts';
+import type {
+  DurableCaptureSessionBinding,
+  DurableCaptureSessionStore,
+} from '../durable-capture/index.ts';
 import { createDurableCaptureResource } from './durable-capture-resource.ts';
 import type { DurableCaptureFinishIntent } from './durable-capture-resource.ts';
 import type { PerfCaptureAdmissionLedger } from './perf-capture-admission-ledger.ts';
@@ -46,9 +49,7 @@ export const perfCaptureDurableResource = createDurableCaptureResource<
 
 export function adoptStartedPerfCapture(params: {
   admissionLedger: PerfCaptureAdmissionLedger;
-  session: DurableCaptureSessionState;
-  sessionName: string;
-  sessionStore: DurableCaptureSessionStore<DurableCaptureSessionState>;
+  binding: DurableCaptureSessionBinding<'perf-capture', PerfNativeCaptureLiveHandle>;
   device: DeviceInfo;
   owner: RuntimeOwnerRef;
   fence: ResourceOwnershipFence;

packages/capture-kit/src/capture-admission/screen-recording-session-resource.ts

@@ -16,6 +16,7 @@ import type { StopObservation } from '@agent-device/contracts/recording-stop-obs
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import type {
   DurableCaptureRecoveryControl,
+  DurableCaptureSessionBinding,
   DurableCaptureSessionStore,
 } from '../durable-capture/index.ts';
 import { createDurableCaptureResource } from './durable-capture-resource.ts';
@@ -50,9 +51,7 @@ export const screenRecordingDurableResource = createDurableCaptureResource<
 
 export function adoptStartedScreenRecording(params: {
   admissionLedger: ScreenRecordingAdmissionLedger;
-  session: DurableCaptureSessionState;
-  sessionName: string;
-  sessionStore: DurableCaptureSessionStore<DurableCaptureSessionState>;
+  binding: DurableCaptureSessionBinding<'screen-recording', ScreenRecordingLiveHandle>;
   device: DeviceInfo;
   owner: RuntimeOwnerRef;
   fence: ResourceOwnershipFence;