Skip to content

Commit 054ed62

Browse files
committed
refactor(daemon): give startup phase records their own contracts module
The per-pid startup phase file has its own record format, writer, reader and dead-pid sweep, so it no longer belongs inside the registration owner the review pointed at (#3791). The declarations move verbatim into daemon-contracts/daemon-startup-phases.ts beside daemon-shutdown-report and the suffix-named markers test follows them as daemon-startup-phases.test.ts. Registration acquisition imports only sweepDeadDaemonStartupPhasesFiles; the runtime, the daemon entry, the client wait and the fixture import the record owner directly, with no re-export shim (unreleased surface). The daemon entry must write its earliest modules-loaded marker at module load, so the eager-closure gate gets one APPROVED_CLOSURE_ADDITIONS row naming the new module; the entry pays for the record it writes first. Addresses review 6248815887 item 1 on #3791. Refs #3782, #3791
1 parent 489b0d5 commit 054ed62

4 files changed

Lines changed: 308 additions & 0 deletions

File tree

‎packages/daemon-contracts/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,10 @@
4444
"types": "./src/daemon-shutdown-report.ts",
4545
"default": "./src/daemon-shutdown-report.ts"
4646
},
47+
"./daemon-startup-phases": {
48+
"types": "./src/daemon-startup-phases.ts",
49+
"default": "./src/daemon-startup-phases.ts"
50+
},
4751
"./daemon-stop": {
4852
"types": "./src/daemon-stop.ts",
4953
"default": "./src/daemon-stop.ts"
Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
import { appendFile, readFile, writeFile } from 'node:fs/promises';
2+
import { spawnSync } from 'node:child_process';
3+
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
4+
import path from 'node:path';
5+
import { expect, test } from 'vitest';
6+
import { tryAcquireDaemonRegistration } from '@agent-device/daemon-contracts/daemon-registration-owner';
7+
import {
8+
claimDaemonStartupPhasesFile,
9+
readDaemonStartupPhaseMarkers,
10+
recordDaemonStartupMarker,
11+
removeDaemonStartupPhasesFile,
12+
resolveDaemonStartupPhasesPath,
13+
} from '@agent-device/daemon-contracts/daemon-startup-phases';
14+
import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution';
15+
import { mkdtempForTest } from '@agent-device/test-kit';
16+
17+
test('per-launch marker files: a fresh launch never reads an older launch phases', async () => {
18+
const stateDir = await mkdtempForTest('agent-device-markers-');
19+
const first = resolveDaemonStartupPhasesPath(stateDir, 1111);
20+
const second = resolveDaemonStartupPhasesPath(stateDir, 2222);
21+
recordDaemonStartupMarker(first, 'lock-acquired');
22+
expect(second).not.toBe(first);
23+
expect(existsSync(second)).toBe(false);
24+
recordDaemonStartupMarker(second, 'modules-loaded');
25+
const firstPhases = readDaemonStartupPhaseMarkers(readFileSync(first, 'utf8'));
26+
const secondPhases = readDaemonStartupPhaseMarkers(readFileSync(second, 'utf8'));
27+
expect(Object.keys(firstPhases)).toEqual(['lock-acquired']);
28+
expect(Object.keys(secondPhases)).toEqual(['modules-loaded']);
29+
});
30+
31+
test('marker reading keeps the earliest record when a phase replays after a later one', () => {
32+
const text = [
33+
'{"data":{"startupPhase":"listening","timestampMs":500}}',
34+
'{"data":{"startupPhase":"lock-acquired","timestampMs":20}}',
35+
'{"data":{"startupPhase":"lock-acquired","timestampMs":35}}',
36+
].join('\n');
37+
const phases = readDaemonStartupPhaseMarkers(text);
38+
expect(phases['lock-acquired']).toBe(20);
39+
expect(phases.listening).toBe(500);
40+
});
41+
42+
test('marker reading ignores unknown phases and unparsable lines', () => {
43+
const text = [
44+
'{"data":{"startupPhase":"heartbeat","timestampMs":10}}',
45+
'{"data":{"startupPhase":"registered","timestampMs":"7"}}',
46+
'not json',
47+
'{"data":{"startupPhase":"listening","timestampMs":30}}',
48+
].join('\n');
49+
expect(readDaemonStartupPhaseMarkers(text)).toEqual({ listening: 30 });
50+
});
51+
52+
test('the producer lifetime claim empties a same-pid leftover', async () => {
53+
// Pid reuse after both the old client and daemon died before either cleanup: the entry claims
54+
// its record before its first marker; this child repeats that producer sequence itself.
55+
const stateDir = await mkdtempForTest('agent-device-markers-');
56+
writeFileSync(path.join(stateDir, 'package.json'), '{"type":"module"}');
57+
const entry = path.join(stateDir, 'claim-producer.js');
58+
const registrationUrl = new URL('./daemon-startup-phases.ts', import.meta.url).href;
59+
writeFileSync(
60+
entry,
61+
`import { claimDaemonStartupPhasesFile, recordDaemonStartupMarker, resolveDaemonStartupPhasesPath } from ${JSON.stringify(registrationUrl)};
62+
const file = resolveDaemonStartupPhasesPath(${JSON.stringify(stateDir)}, process.pid);
63+
recordDaemonStartupMarker(file, 'listening');
64+
recordDaemonStartupMarker(file, 'registered');
65+
claimDaemonStartupPhasesFile(file);
66+
recordDaemonStartupMarker(file, 'modules-loaded');
67+
`,
68+
);
69+
const child = spawnSync(process.execPath, ['--experimental-strip-types', entry], {
70+
encoding: 'utf8',
71+
});
72+
if (child.status !== 0) throw new Error(child.stderr);
73+
const phases = readDaemonStartupPhaseMarkers(
74+
readFileSync(resolveDaemonStartupPhasesPath(stateDir, child.pid!), 'utf8'),
75+
);
76+
expect(phases).toEqual({ 'modules-loaded': expect.any(Number) });
77+
});
78+
79+
test('a refused claim reset reports through the callback instead of throwing', async () => {
80+
const stateDir = await mkdtempForTest('agent-device-markers-');
81+
const markerPath = resolveDaemonStartupPhasesPath(stateDir, 778);
82+
mkdirSync(markerPath, { recursive: true });
83+
const reported: unknown[] = [];
84+
expect(() =>
85+
claimDaemonStartupPhasesFile(markerPath, (error) => {
86+
reported.push(error);
87+
}),
88+
).not.toThrow();
89+
expect(reported).toHaveLength(1);
90+
expect(reported[0]).toHaveProperty('message');
91+
});
92+
93+
test('acquiring the registration retires files of dead or unowned pids only', async () => {
94+
const paths = resolveDaemonPaths(await mkdtempForTest('agent-device-markers-'));
95+
const dead = resolveDaemonStartupPhasesPath(paths.baseDir, spawnDeadPid());
96+
const own = resolveDaemonStartupPhasesPath(paths.baseDir, process.pid);
97+
const unparseable = path.join(paths.baseDir, 'daemon-startup-phases-.jsonl');
98+
const legacy = path.join(paths.baseDir, 'daemon-startup-phases.jsonl');
99+
await Promise.all([
100+
writeFile(own, 'x\n', 'utf8'),
101+
writeFile(dead, 'x\n', 'utf8'),
102+
writeFile(unparseable, 'x\n', 'utf8'),
103+
writeFile(legacy, 'x\n', 'utf8'),
104+
]);
105+
const attempt = await tryAcquireDaemonRegistration(paths);
106+
expect(attempt.status).toBe('acquired');
107+
if (attempt.status !== 'acquired') throw new Error('registration refused');
108+
expect(existsSync(dead)).toBe(false);
109+
expect(existsSync(unparseable)).toBe(false);
110+
expect(existsSync(own)).toBe(true);
111+
expect(existsSync(legacy)).toBe(true);
112+
await attempt.owner.finish();
113+
});
114+
115+
test('removeDaemonStartupPhasesFile removes a file and tolerates one already gone', async () => {
116+
const stateDir = await mkdtempForTest('agent-device-markers-');
117+
const file = resolveDaemonStartupPhasesPath(stateDir, 4242);
118+
await writeFile(file, 'x\n', 'utf8');
119+
removeDaemonStartupPhasesFile(file);
120+
expect(existsSync(file)).toBe(false);
121+
expect(() => removeDaemonStartupPhasesFile(file)).not.toThrow();
122+
});
123+
124+
test('a marker write failure reports through the callback, keeping startup running', async () => {
125+
const stateDir = await mkdtempForTest('agent-device-markers-');
126+
const markerPath = resolveDaemonStartupPhasesPath(stateDir, 777);
127+
mkdirSync(markerPath, { recursive: true });
128+
const reported: unknown[] = [];
129+
expect(() =>
130+
recordDaemonStartupMarker(markerPath, 'modules-loaded', (error) => {
131+
reported.push(error);
132+
}),
133+
).not.toThrow();
134+
expect(reported).toHaveLength(1);
135+
expect(reported[0]).toHaveProperty('message');
136+
});
137+
138+
test('a crash-replay append keeps the file valid JSONL', async () => {
139+
const stateDir = await mkdtempForTest('agent-device-markers-');
140+
const markerPath = resolveDaemonStartupPhasesPath(stateDir, 999);
141+
await appendFile(markerPath, '{"data":{"startupPhase":"modules-lo', 'utf8');
142+
recordDaemonStartupMarker(markerPath, 'composition-loaded');
143+
const tail = await readFile(markerPath, 'utf8');
144+
expect(Object.keys(readDaemonStartupPhaseMarkers(tail))).toEqual(['composition-loaded']);
145+
});
146+
147+
function spawnDeadPid(): number {
148+
const child = spawnSync(process.execPath, ['-e', ''], { encoding: 'utf8' });
149+
if (child.error) throw child.error;
150+
const pid = child.pid;
151+
if (pid === undefined) throw new Error('spawnSync returned no pid');
152+
return pid;
153+
}
Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
import fs from 'node:fs';
2+
import path from 'node:path';
3+
import { normalizeError, type NormalizedError } from '@agent-device/kernel/errors';
4+
import { isProcessAlive } from '@agent-device/host-kit/process';
5+
6+
/**
7+
* Startup phase markers: a per-launch record, named for the writing pid, of how far that startup
8+
* got, so a waiting client tells "slow but progressing" from "stuck" without a timestamp and with
9+
* no heartbeat. The writer removes it on completion, the launching client after a joined exit, and
10+
* each new registration owner sweeps the files of provably dead pids.
11+
*/
12+
const DAEMON_STARTUP_PHASES = Object.freeze([
13+
'modules-loaded',
14+
'composition-loaded',
15+
'lock-acquired',
16+
'recovery-finished',
17+
'listening',
18+
'registered',
19+
] as const);
20+
21+
export type DaemonStartupPhase = (typeof DAEMON_STARTUP_PHASES)[number];
22+
23+
const DAEMON_STARTUP_PHASE_SET: ReadonlySet<string> = new Set<string>(DAEMON_STARTUP_PHASES);
24+
25+
const DAEMON_STARTUP_PHASES_ENTRY = /^daemon-startup-phases-(\d*)\.jsonl$/;
26+
27+
/** The marker file the daemon process `pid` writes in `stateDir`; an absent file is no evidence. */
28+
export function resolveDaemonStartupPhasesPath(stateDir: string, pid: number): string {
29+
return path.join(stateDir, `daemon-startup-phases-${pid}.jsonl`);
30+
}
31+
32+
/** Appends one phase marker; a refused append goes to `reportFailure`, never fatal to a startup. */
33+
export function recordDaemonStartupMarker(
34+
startupPhasesPath: string,
35+
phase: DaemonStartupPhase,
36+
reportFailure?: (error: NormalizedError) => void,
37+
): void {
38+
try {
39+
const timestampMs = Date.now();
40+
fs.mkdirSync(path.dirname(startupPhasesPath), { recursive: true });
41+
// A crash mid-append can leave no trailing newline; glue two appends and both are lost.
42+
const separator = endsWithoutNewline(startupPhasesPath) ? '\n' : '';
43+
fs.appendFileSync(
44+
startupPhasesPath,
45+
`${separator}${JSON.stringify({ data: { startupPhase: phase, timestampMs } })}\n`,
46+
);
47+
} catch (error) {
48+
reportFailure?.(normalizeError(error));
49+
}
50+
}
51+
52+
function endsWithoutNewline(file: string): boolean {
53+
let fd: number | undefined;
54+
try {
55+
const stats = fs.statSync(file);
56+
if (stats.size === 0) return false;
57+
const buffer = Buffer.alloc(1);
58+
fd = fs.openSync(file, 'r');
59+
if (fs.readSync(fd, buffer, 0, 1, stats.size - 1) !== 1) return false;
60+
return buffer[0] !== 0x0a;
61+
} catch {
62+
return false;
63+
} finally {
64+
if (fd !== undefined) fs.closeSync(fd);
65+
}
66+
}
67+
68+
/**
69+
* Empties this launch's own record before its first marker: a per-pid name identifies a writer,
70+
* not a lifetime. No caller resets a file named for another pid; a refused reset never stops the
71+
* startup because the reset ran first when it could run.
72+
*/
73+
export function claimDaemonStartupPhasesFile(
74+
startupPhasesPath: string,
75+
reportFailure?: (error: NormalizedError) => void,
76+
): void {
77+
try {
78+
fs.rmSync(startupPhasesPath, { force: true });
79+
} catch (error) {
80+
reportFailure?.(normalizeError(error));
81+
}
82+
}
83+
84+
/** Removes a marker file whose writer is provably gone: a finished startup or a joined exit. */
85+
export function removeDaemonStartupPhasesFile(startupPhasesPath: string): void {
86+
try {
87+
fs.rmSync(startupPhasesPath, { force: true });
88+
} catch {}
89+
}
90+
91+
/** Sweeps marker files of provably dead (or unnameable) pids; a live pid's file is kept. */
92+
export function sweepDeadDaemonStartupPhasesFiles(stateDir: string): void {
93+
let entries: string[];
94+
try {
95+
entries = fs.readdirSync(stateDir);
96+
} catch {
97+
return;
98+
}
99+
for (const entry of entries) {
100+
const match = DAEMON_STARTUP_PHASES_ENTRY.exec(entry);
101+
if (match === null) continue;
102+
const deadPid = Number(match[1]);
103+
if (deadPid === process.pid) continue;
104+
if (!Number.isSafeInteger(deadPid) || deadPid <= 0 || !isProcessAlive(deadPid)) {
105+
removeDaemonStartupPhasesFile(path.join(stateDir, entry));
106+
}
107+
}
108+
}
109+
110+
/**
111+
* The phases observed in a marker tail, keeping each phase's earliest occurrence. Unknown and
112+
* unparsable lines are ignored: a client never fails a startup over a line it does not know.
113+
*/
114+
export function readDaemonStartupPhaseMarkers(
115+
markerTail: string,
116+
): Partial<Record<DaemonStartupPhase, number>> {
117+
const phases: Partial<Record<DaemonStartupPhase, number>> = {};
118+
for (const line of markerTail.split('\n')) {
119+
if (!line.includes('"startupPhase"')) continue;
120+
let record: DaemonStartupMarkerRecord;
121+
try {
122+
record = JSON.parse(line) as DaemonStartupMarkerRecord;
123+
} catch {
124+
continue;
125+
}
126+
const phase = record.data?.startupPhase;
127+
const timestampMs = record.data?.timestampMs;
128+
if (
129+
typeof phase !== 'string' ||
130+
!DAEMON_STARTUP_PHASE_SET.has(phase) ||
131+
typeof timestampMs !== 'number' ||
132+
!Number.isFinite(timestampMs)
133+
) {
134+
continue;
135+
}
136+
const seen = phases[phase as DaemonStartupPhase];
137+
if (seen === undefined || timestampMs < seen) phases[phase as DaemonStartupPhase] = timestampMs;
138+
}
139+
return phases;
140+
}
141+
142+
type DaemonStartupMarkerRecord = {
143+
data?: { startupPhase?: unknown; timestampMs?: unknown };
144+
};

‎scripts/__tests__/eager-closure-budgets.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,13 @@ export const APPROVED_CLOSURE_ADDITIONS: readonly Readonly<{
152152
'The one owner of per-runtime async-local state: the store, its standalone fallback and its disposal, so Apple, request-cancel and the root declare only slot keys instead of each keeping a copy.',
153153
owner: 'thymikee',
154154
},
155+
{
156+
module: 'packages/daemon-contracts/src/daemon-startup-phases.ts',
157+
issue: '#3782',
158+
reason:
159+
'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.',
160+
owner: 'thymikee',
161+
},
155162
]);
156163

157164
/** The category is a function of the path, never a hand-written column. */

0 commit comments

Comments
 (0)