refactor(daemon): converge the marker helpers and shared fixture waits

Author: thymikee

.github/workflows/ios.yml

@@ -171,17 +171,11 @@ jobs:
           pnpm clean:daemon
           # The public-SDK record is the cold-startup evidence; the CLI timer only wraps attach.
           node --input-type=module -e '
-            import { performance } from "node:perf_hooks";
+            const { performance } = await import("node:perf_hooks");
             const { ensureDaemon } = await import("./dist/src/index.js");
-            const stateDir = process.env.AGENT_DEVICE_STATE_DIR;
-            const startedAt = performance.now();
-            const connection = await ensureDaemon({ stateDir });
-            console.log(JSON.stringify({
-              phase: "daemon_cold_startup",
-              durationMs: Math.round(performance.now() - startedAt),
-              started: connection.started,
-              pid: connection.daemon.pid,
-            }));
+            const t0 = performance.now();
+            const c = await ensureDaemon({ stateDir: process.env.AGENT_DEVICE_STATE_DIR });
+            console.log(JSON.stringify({ phase: "daemon_cold_startup", started: c.started, pid: c.daemon.pid, durationMs: Math.round(performance.now() - t0) }));
           '
           node bin/agent-device.mjs prepare ios-runner --platform ios --udid "${{ steps.ios-simulator.outputs.simulator-udid }}" --timeout "$AGENT_DEVICE_IOS_PREPARE_TIMEOUT_MS" --json
 

packages/daemon-contracts/src/daemon-registration-owner.ts

@@ -47,7 +47,6 @@ import {
 import { sweepDeadDaemonStartupPhasesFiles } from './daemon-startup-phases.ts';
 
 export const DAEMON_STARTUP_EXIT_CODES = Object.freeze({ busy: 75, unproven: 78 });
-
 export type DaemonRegistrationFields = Readonly<{
   socketPort?: number;
   httpPort?: number;

packages/daemon-contracts/src/daemon-startup-phases.test.ts

@@ -5,7 +5,6 @@ import path from 'node:path';
 import { expect, test } from 'vitest';
 import { tryAcquireDaemonRegistration } from '@agent-device/daemon-contracts/daemon-registration-owner';
 import {
-  claimDaemonStartupPhasesFile,
   readDaemonStartupPhaseMarkers,
   recordDaemonStartupMarker,
   removeDaemonStartupPhasesFile,
@@ -50,19 +49,19 @@ test('marker reading ignores unknown phases and unparsable lines', () => {
 });
 
 test('the producer lifetime claim empties a same-pid leftover', async () => {
-  // Pid reuse after both the old client and daemon died before either cleanup: the entry claims
+  // Pid reuse after both the old client and daemon died before either cleanup: the entry removes
   // its record before its first marker; this child repeats that producer sequence itself.
   const stateDir = await mkdtempForTest('agent-device-markers-');
   writeFileSync(path.join(stateDir, 'package.json'), '{"type":"module"}');
   const entry = path.join(stateDir, 'claim-producer.js');
   const registrationUrl = new URL('./daemon-startup-phases.ts', import.meta.url).href;
   writeFileSync(
     entry,
-    `import { claimDaemonStartupPhasesFile, recordDaemonStartupMarker, resolveDaemonStartupPhasesPath } from ${JSON.stringify(registrationUrl)};
+    `import { removeDaemonStartupPhasesFile, recordDaemonStartupMarker, resolveDaemonStartupPhasesPath } from ${JSON.stringify(registrationUrl)};
 const file = resolveDaemonStartupPhasesPath(${JSON.stringify(stateDir)}, process.pid);
 recordDaemonStartupMarker(file, 'listening');
 recordDaemonStartupMarker(file, 'registered');
-claimDaemonStartupPhasesFile(file);
+removeDaemonStartupPhasesFile(file);
 recordDaemonStartupMarker(file, 'modules-loaded');
 `,
   );
@@ -76,13 +75,19 @@ recordDaemonStartupMarker(file, 'modules-loaded');
   expect(phases).toEqual({ 'modules-loaded': expect.any(Number) });
 });
 
-test('a refused claim reset reports through the callback instead of throwing', async () => {
+test.each([
+  ['remove', (p: string, cb: (e: unknown) => void) => removeDaemonStartupPhasesFile(p, cb)],
+  [
+    'record',
+    (p: string, cb: (e: unknown) => void) => recordDaemonStartupMarker(p, 'modules-loaded', cb),
+  ],
+] as const)('a refused %s reports through the callback instead of throwing', async (_name, run) => {
   const stateDir = await mkdtempForTest('agent-device-markers-');
-  const markerPath = resolveDaemonStartupPhasesPath(stateDir, 778);
+  const markerPath = resolveDaemonStartupPhasesPath(stateDir, 777);
   mkdirSync(markerPath, { recursive: true });
   const reported: unknown[] = [];
   expect(() =>
-    claimDaemonStartupPhasesFile(markerPath, (error) => {
+    run(markerPath, (error) => {
       reported.push(error);
     }),
   ).not.toThrow();
@@ -121,20 +126,6 @@ test('removeDaemonStartupPhasesFile removes a file and tolerates one already gon
   expect(() => removeDaemonStartupPhasesFile(file)).not.toThrow();
 });
 
-test('a marker write failure reports through the callback, keeping startup running', async () => {
-  const stateDir = await mkdtempForTest('agent-device-markers-');
-  const markerPath = resolveDaemonStartupPhasesPath(stateDir, 777);
-  mkdirSync(markerPath, { recursive: true });
-  const reported: unknown[] = [];
-  expect(() =>
-    recordDaemonStartupMarker(markerPath, 'modules-loaded', (error) => {
-      reported.push(error);
-    }),
-  ).not.toThrow();
-  expect(reported).toHaveLength(1);
-  expect(reported[0]).toHaveProperty('message');
-});
-
 test('a crash-replay append keeps the file valid JSONL', async () => {
   const stateDir = await mkdtempForTest('agent-device-markers-');
   const markerPath = resolveDaemonStartupPhasesPath(stateDir, 999);

packages/daemon-contracts/src/daemon-startup-phases.ts

@@ -5,9 +5,9 @@ import { isProcessAlive } from '@agent-device/host-kit/process';
 
 /**
  * Startup phase markers: a per-launch record, named for the writing pid, of how far that startup
- * got, so a waiting client tells "slow but progressing" from "stuck" without a timestamp and with
- * no heartbeat. The writer removes it on completion, the launching client after a joined exit, and
- * each new registration owner sweeps the files of provably dead pids.
+ * got, so a waiting client tells "slow but progressing" from "stuck" without a heartbeat. The
+ * writer removes it on completion, the client after a joined exit, and each new registration
+ * owner sweeps the files of provably dead pids.
  */
 const DAEMON_STARTUP_PHASES = Object.freeze([
   'modules-loaded',
@@ -66,11 +66,11 @@ function endsWithoutNewline(file: string): boolean {
 }
 
 /**
- * Empties this launch's own record before its first marker: a per-pid name identifies a writer,
- * not a lifetime. No caller resets a file named for another pid; a refused reset never stops the
- * startup because the reset ran first when it could run.
+ * Removes this launch's record: before its first marker (a per-pid name identifies a writer, not
+ * a lifetime, so the entry claims its file first), and after a finished startup or joined exit.
+ * A refused removal only reports through `reportFailure`; it never stops a startup.
  */
-export function claimDaemonStartupPhasesFile(
+export function removeDaemonStartupPhasesFile(
   startupPhasesPath: string,
   reportFailure?: (error: NormalizedError) => void,
 ): void {
@@ -81,13 +81,6 @@ export function claimDaemonStartupPhasesFile(
   }
 }
 
-/** Removes a marker file whose writer is provably gone: a finished startup or a joined exit. */
-export function removeDaemonStartupPhasesFile(startupPhasesPath: string): void {
-  try {
-    fs.rmSync(startupPhasesPath, { force: true });
-  } catch {}
-}
-
 /** Sweeps marker files of provably dead (or unnameable) pids; a live pid's file is kept. */
 export function sweepDeadDaemonStartupPhasesFiles(stateDir: string): void {
   let entries: string[];

scripts/__tests__/eager-closure-budgets.ts

@@ -156,7 +156,7 @@ export const APPROVED_CLOSURE_ADDITIONS: readonly Readonly<{
     module: 'packages/daemon-contracts/src/daemon-startup-phases.ts',
     issue: '#3782',
     reason:
-      'The startup phase record owner the #3791 review asked for (its own file/format/writer/reader/sweep beside daemon-shutdown-report). The daemon entry records its earliest `modules-loaded` marker at module load, so the owner must be eager there; the entry pays for the record it writes first.',
+      'The startup phase record owner the #3791 review asked for. The daemon entry records its earliest `modules-loaded` marker at module load, so the owner must be eager there; the entry pays for the record it writes first.',
     owner: 'thymikee',
   },
 ]);

src/__tests__/test-utils/registered-daemon-fixture.test.ts

@@ -11,6 +11,7 @@ import {
   launchRegisteredDaemonFixtureArgs,
   registeredDaemonFixtureArgs,
   spawnRegisteredDaemonFixture,
+  waitForFixtureFile,
   waitForRegisteredDaemonFixture,
   finishRegisteredDaemonFixture,
 } from './registered-daemon-fixture.ts';
@@ -36,21 +37,12 @@ test('args built before any launch keep their own entry script under a concurren
   assert.notEqual(firstArgs[1], secondArgs[1]);
   const first = launchRegisteredDaemonFixtureArgs(paths, firstArgs, { stdio: 'ignore' });
   try {
-    const held = path.join(paths.baseDir, `registration-held-${first.pid}`);
-    for (let attempt = 0; !fs.existsSync(held); attempt += 1) {
-      assert.ok(attempt < 400, 'child 1 never acquired the registration');
-      await new Promise((resolve) => setTimeout(resolve, 10));
-    }
+    await waitForFixtureFile(path.join(paths.baseDir, `registration-held-${first.pid}`));
     const second = launchRegisteredDaemonFixtureArgs(paths, secondArgs, { stdio: 'ignore' });
     assert.equal((await second.exited).exitCode, DAEMON_STARTUP_EXIT_CODES.busy);
-    const ownRecord = resolveDaemonStartupPhasesPath(paths.baseDir, first.pid);
-    const text = fs.readFileSync(ownRecord, 'utf8');
+    const text = fs.readFileSync(resolveDaemonStartupPhasesPath(paths.baseDir, first.pid), 'utf8');
     assert.match(text, /modules-loaded/);
-    assert.doesNotMatch(
-      text,
-      /lock-acquired/,
-      "child 1 must run the script built for it, not the second build's switches",
-    );
+    assert.doesNotMatch(text, /lock-acquired/, 'child 1 must run the script built for it');
   } finally {
     await finishRegisteredDaemonFixture(paths.baseDir);
   }

src/__tests__/test-utils/registered-daemon-fixture.ts

@@ -52,7 +52,7 @@ export function registeredDaemonFixtureArgs(
     `import fs from 'node:fs';
 import path from 'node:path';
 import { DAEMON_STARTUP_EXIT_CODES, tryAcquireDaemonRegistration } from ${JSON.stringify(registrationUrl)};
-import { claimDaemonStartupPhasesFile, recordDaemonStartupMarker, resolveDaemonStartupPhasesPath } from ${JSON.stringify(phasesUrl)};
+import { removeDaemonStartupPhasesFile, recordDaemonStartupMarker, resolveDaemonStartupPhasesPath } from ${JSON.stringify(phasesUrl)};
 const paths = ${JSON.stringify(paths)};
 const barrier = ${JSON.stringify(acquisitionBarrier)};
 const emitBefore = ${fixtureOptions?.emitStartupMarkerBeforeAcquisition ? 'true' : 'false'};
@@ -61,11 +61,7 @@ if (barrier) {
   fs.writeFileSync(barrier + '.ready-' + process.pid, 'ready');
   while (!fs.existsSync(barrier)) await new Promise(resolve => setTimeout(resolve, 10));
 }
-if (emitBefore) {
-  const ownRecord = resolveDaemonStartupPhasesPath(paths.baseDir, process.pid);
-  claimDaemonStartupPhasesFile(ownRecord);
-  recordDaemonStartupMarker(ownRecord, 'modules-loaded');
-}
+if (emitBefore) { const own = resolveDaemonStartupPhasesPath(paths.baseDir, process.pid); removeDaemonStartupPhasesFile(own); recordDaemonStartupMarker(own, 'modules-loaded'); }
 const acquired = await tryAcquireDaemonRegistration(paths);
 if (acquired.status !== 'acquired') process.exit(DAEMON_STARTUP_EXIT_CODES[acquired.status]);
 if (emitAfter)
@@ -117,6 +113,14 @@ export function spawnRegisteredDaemonFixture(
   );
 }
 
+/** Waits up to 4 s for a fixture child to publish `file`; one shared wait for every probe. */
+export async function waitForFixtureFile(file: string): Promise<void> {
+  for (let attempt = 0; !fs.existsSync(file); attempt += 1) {
+    assert.ok(attempt < 400, `fixture did not publish ${file}`);
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
 export async function waitForRegisteredDaemonFixture(
   paths: DaemonPaths,
   child: ReturnType<typeof runCmdDetachedMonitored>,