feat(host): capture HostEnvironment once at entry points

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- The PNG worker no longer calls `process.emitWarning` when it is unavailable, and it starts with an empty environment (`env: {}`). The daemon registers a sink when it pre-warms the worker, so every transition to unavailable (spawn failure, missing entry, load error, exit) leaves exactly one `png_worker_unavailable` event, with a typed `reason` (`entry-not-found`, `spawn-failed`, `worker-error`, `worker-exited`) and its `detail`, in `daemon.log`, with or without `--debug`. Requests then continue on the in-process fallback without repeating the event.
+- Behavior change: `resolveHubAppReference`, shipped through `agent-device/plugins/webdriver`, now needs `cwd` to resolve a relative app path. Without it the call fails with `INVALID_ARGS` and `details.reason: provider_app_cwd_missing`; it used to resolve against the process's working directory. Absolute paths, URLs and provider references are unaffected. The daemon fills it from the client's working directory (or its host's) for every provider lease request, so `connect` and `lease_allocate` are unchanged.
 - The `daemon-not-running` hint now always names `--state-dir <dir>`, and a daemon force-retired for outlasting its drain is reported as `Replaced unreachable daemon` instead of `Replaced idle daemon`. `daemon-drain-timeout` and the post-drain force retire are documented in the client API and `help`.
 - Fix `ensureDaemon()`, the CLI and MCP killing a daemon they had just asked to leave. After the daemon answers the quiesce request with `draining`, the client now waits up to 60 s for it to exit by itself and clean up its registration, so plugin disposal and lease finalization finish (on Windows a signal ends the process outright, and on POSIX a drain longer than 3 s was killed). A daemon still running at the deadline that fails its liveness probes is force-retired; one that still answers is left running and the call fails with `details.reason: 'daemon-drain-timeout'`, with a hint naming `agent-device daemon stop --state-dir <path>`.
 - `@agent-device/testmu` is now a version 2 provider plugin. `import testmu from '@agent-device/testmu'` gives a factory, `testmu({ credentials: { username, accessKey } })`, that reads those credentials instead of `LT_USERNAME` and `LT_ACCESS_KEY`; without options it reads the variables as before. The package still declares the version 1 plugin entry, so `agent-device plugins add @agent-device/testmu` keeps working on hosts that predate the version 2 contract.

packages/capture-kit/src/capture-admission/app-log-files.ts

@@ -12,7 +12,7 @@ export type AppLogRotationConfig = Readonly<{
 }>;
 
 /** Shared lower-level file policy for daemon markers and runtime output sinks. */
-export function ensureAppLogPath(outPath: string, env: NodeJS.ProcessEnv = process.env): void {
+export function ensureAppLogPath(outPath: string, env: NodeJS.ProcessEnv): void {
   const directory = path.dirname(outPath);
   if (!fs.existsSync(directory)) fs.mkdirSync(directory, { recursive: true });
   assertAppLogFileIsNotSymbolicLink(outPath);

packages/capture-kit/src/host-environment.fixtures.ts

@@ -0,0 +1,11 @@
+import { captureHostEnvironment } from '@agent-device/host-kit/process';
+import type { HostEnvironment } from '@agent-device/kernel/source-value';
+
+/**
+ * The host a capture-kit test hands to code that takes one explicitly: a snapshot of the process
+ * as it is when called, so `vi.stubEnv` made earlier in the test reaches it. Test-kit depends on
+ * capture-kit, so capture-kit keeps this local.
+ */
+export function createTestHost(): HostEnvironment {
+  return captureHostEnvironment(process);
+}

packages/capture-kit/src/png-worker-client-unavailable.test.ts

@@ -0,0 +1,57 @@
+import { EventEmitter } from 'node:events';
+import { expect, test, vi } from 'vitest';
+import { PNG } from './png.ts';
+
+test('a worker whose entry is missing is reported once and later registrations hear it', async () => {
+  vi.resetModules();
+  vi.doMock('./internal-entry.ts', () => ({ resolveInternalEntryModulePath: () => null }));
+  const { decodePngAsync, prewarmPngWorker } = await import('./png-worker-client.ts');
+  const png = PNG.sync.write(new PNG({ width: 1, height: 1 }));
+  const first = vi.fn();
+  const second = vi.fn();
+
+  prewarmPngWorker(first);
+  const decoded = await decodePngAsync(png, 'fallback');
+  prewarmPngWorker(second);
+
+  expect(decoded.width).toBe(1);
+  expect(first.mock.calls).toEqual([[{ kind: 'entry-not-found' }]]);
+  expect(second.mock.calls).toEqual([[{ kind: 'entry-not-found' }]]);
+  vi.doUnmock('./internal-entry.ts');
+});
+
+test('a worker that dies after it started is reported once, and its pending job still completes', async () => {
+  vi.resetModules();
+  class FakeWorker extends EventEmitter {
+    static last: FakeWorker | undefined;
+    constructor() {
+      super();
+      FakeWorker.last = this;
+    }
+    postMessage(): void {}
+    ref(): void {}
+    unref(): void {}
+    terminate(): Promise<number> {
+      return Promise.resolve(0);
+    }
+  }
+  vi.doMock('node:worker_threads', async (importOriginal) => ({
+    ...(await importOriginal<typeof import('node:worker_threads')>()),
+    Worker: FakeWorker,
+  }));
+  const { decodePngAsync, prewarmPngWorker } = await import('./png-worker-client.ts');
+  const png = PNG.sync.write(new PNG({ width: 1, height: 1 }));
+  const unavailable = vi.fn();
+  prewarmPngWorker(unavailable);
+  expect(unavailable).not.toHaveBeenCalled();
+
+  const decoded = decodePngAsync(png, 'under-request');
+  const worker = FakeWorker.last;
+  if (!worker) throw new Error('the pre-warm did not start a worker');
+  worker.emit('error', new Error('worker crashed'));
+  worker.emit('exit', 1);
+
+  expect((await decoded).width).toBe(1);
+  expect(unavailable.mock.calls).toEqual([[{ kind: 'worker-error', detail: 'worker crashed' }]]);
+  vi.doUnmock('node:worker_threads');
+});

packages/capture-kit/src/png-worker-client.ts

@@ -1,5 +1,4 @@
 import { Worker } from 'node:worker_threads';
-import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';
 import { AppError, toAppErrorCode } from '@agent-device/kernel/errors';
 import type { Rect } from '@agent-device/kernel/snapshot';
 import { resolveInternalEntryModulePath } from './internal-entry.ts';
@@ -29,6 +28,12 @@ import {
 
 const PNG_WORKER_ENTRYPOINT = 'png-worker';
 
+/** Why the worker left service for good; `detail` carries the underlying error text. */
+export type PngWorkerUnavailableReason = {
+  kind: 'entry-not-found' | 'spawn-failed' | 'worker-error' | 'worker-exited';
+  detail?: string;
+};
+
 /** Worker-infrastructure failure: the generic runner falls back to the sync path. */
 class PngWorkerUnavailableError extends Error {}
 
@@ -38,22 +43,16 @@ type PendingJob = {
 };
 
 let worker: Worker | null = null;
-let workerUnavailable = false;
-let warnedWorkerUnavailable = false;
+let unavailableReason: PngWorkerUnavailableReason | undefined;
+let reportUnavailable: ((reason: PngWorkerUnavailableReason) => void) | undefined;
 let nextJobId = 0;
 const pendingJobs = new Map<number, PendingJob>();
 
-/** Permanently degrades to the sync path and reports the reason once. */
-function markWorkerUnavailable(reason: string): void {
-  workerUnavailable = true;
-  if (warnedWorkerUnavailable) return;
-  warnedWorkerUnavailable = true;
-  // Worker failures can surface outside a diagnostics scope (e.g. daemon
-  // startup pre-warm), so pair the scoped diagnostic with a process warning.
-  emitDiagnostic({ level: 'warn', phase: 'png_worker_unavailable', data: { reason } });
-  process.emitWarning(
-    `PNG worker unavailable, falling back to in-process PNG processing: ${reason}`,
-  );
+/** Permanently degrades to the sync path; the daemon's sink hears each transition once. */
+function markWorkerUnavailable(reason: PngWorkerUnavailableReason): void {
+  if (unavailableReason) return;
+  unavailableReason = reason;
+  reportUnavailable?.(reason);
 }
 
 function handleWorkerMessage(message: PngWorkerResponse): void {
@@ -74,14 +73,14 @@ function handleWorkerMessage(message: PngWorkerResponse): void {
   }
 }
 
-function handleWorkerFailure(failed: Worker, error: Error): void {
+function handleWorkerFailure(failed: Worker, reason: PngWorkerUnavailableReason): void {
   if (worker !== failed) return;
   // Keep the failure handling conservative: after any worker-level error the
   // daemon permanently falls back to the in-process synchronous path.
-  markWorkerUnavailable(error.message);
+  markWorkerUnavailable(reason);
   worker = null;
   void failed.terminate().catch(() => {});
-  rejectPendingJobs(new PngWorkerUnavailableError(`PNG worker failed: ${error.message}`));
+  rejectPendingJobs(new PngWorkerUnavailableError(`PNG worker failed: ${reason.kind}`));
 }
 
 function rejectPendingJobs(error: Error): void {
@@ -102,31 +101,34 @@ function updateWorkerRef(): void {
 }
 
 function obtainWorker(): Worker | null {
-  if (workerUnavailable) return null;
+  if (unavailableReason) return null;
   if (worker) return worker;
   const modulePath = resolveInternalEntryModulePath(import.meta.url, PNG_WORKER_ENTRYPOINT);
   if (!modulePath) {
-    markWorkerUnavailable('worker entry module not found next to the current module');
+    markWorkerUnavailable({ kind: 'entry-not-found' });
     return null;
   }
   try {
+    // The worker decodes and encodes bytes it is sent; it needs none of the host's environment.
     const created = new Worker(modulePath, {
+      env: {},
       execArgv: modulePath.endsWith('.ts') ? ['--experimental-strip-types'] : [],
     });
     created.on('message', handleWorkerMessage);
     created.on('error', (error) => {
-      handleWorkerFailure(created, error);
+      handleWorkerFailure(created, { kind: 'worker-error', detail: error.message });
     });
     created.on('exit', (code) => {
-      handleWorkerFailure(created, new Error(`PNG worker exited with code ${code}`));
+      handleWorkerFailure(created, { kind: 'worker-exited', detail: `exit code ${code}` });
     });
     created.unref();
     worker = created;
     return created;
   } catch (error) {
-    markWorkerUnavailable(
-      `failed to spawn worker: ${error instanceof Error ? error.message : String(error)}`,
-    );
+    markWorkerUnavailable({
+      kind: 'spawn-failed',
+      detail: error instanceof Error ? error.message : String(error),
+    });
     return null;
   }
 }
@@ -176,14 +178,23 @@ async function runPngJob<Kind extends PngWorkerJobKind>(
   try {
     return await runWorkerJob(job);
   } catch (error) {
-    if (error instanceof PngWorkerUnavailableError) return await runSync();
+    if (error instanceof PngWorkerUnavailableError) {
+      return await runSync();
+    }
     throw error;
   }
 }
 
-/** Daemon startup hook: spawns the worker before the first screenshot job. */
-export function prewarmPngWorker(): void {
-  obtainWorker();
+/**
+ * Daemon startup hook: spawns the worker before the first screenshot job and registers the daemon's
+ * sink, which hears every later transition to unavailable once, inside or outside a request.
+ */
+export function prewarmPngWorker(
+  onUnavailable: (reason: PngWorkerUnavailableReason) => void,
+): void {
+  reportUnavailable = onUnavailable;
+  if (unavailableReason) onUnavailable(unavailableReason);
+  else obtainWorker();
 }
 
 /** Stops the worker thread (used by tests and shutdown); later calls respawn it. */

packages/capture-kit/src/recording/__tests__/overlay-script-paths.test.ts

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { expect, test, vi } from 'vitest';
+import { mkdtempForTestSync } from '../../tmp-dir.fixtures.ts';
+
+vi.mock('@agent-device/host-kit/command', async () => {
+  const fs = await import('node:fs');
+  return {
+    runCmd: vi.fn(async (_cmd: string, args: string[]) => {
+      fs.writeFileSync(args[args.indexOf('--output') + 1]!, 'processed');
+      return { stdout: '', stderr: '', exitCode: 0 };
+    }),
+  };
+});
+vi.mock('../video.ts', () => ({ waitForPlayableVideo: vi.fn(async () => {}) }));
+vi.mock('../swift-cache.ts', () => ({
+  buildSwiftToolEnv: () => ({}),
+  compileSwiftSourceFile: vi.fn(async () => '/bin/true'),
+  resolveRecordingScriptPath: vi.fn(
+    (name: string, _projectRoot: string, cwd: string) => `${cwd}/${name}`,
+  ),
+}));
+
+import { overlayRecordingTouches, startRecordingOverlayBudget } from '../overlay.ts';
+import { compileSwiftSourceFile } from '../swift-cache.ts';
+
+test('a helper script path is resolved per host working directory, not once per process', async () => {
+  const root = mkdtempForTestSync('agent-device-overlay-script-paths-');
+  const videoPath = path.join(root, 'recording.mp4');
+  const telemetryPath = path.join(root, 'recording.gesture-telemetry.json');
+  fs.writeFileSync(telemetryPath, '{"events":[]}');
+  const overlay = async (cwd: string) => {
+    fs.writeFileSync(videoPath, 'original');
+    await overlayRecordingTouches({
+      host: { env: {}, cwd },
+      videoPath,
+      telemetryPath,
+      deadline: startRecordingOverlayBudget(),
+    });
+  };
+
+  await overlay('/cwd/one');
+  await overlay('/cwd/two');
+  await overlay('/cwd/one');
+
+  expect(vi.mocked(compileSwiftSourceFile).mock.calls.map(([params]) => params.sourcePath)).toEqual(
+    [
+      '/cwd/one/recording-overlay.swift',
+      '/cwd/two/recording-overlay.swift',
+      '/cwd/one/recording-overlay.swift',
+    ],
+  );
+});