Skip to content

Commit 2212eac

Browse files
authored
fix: centralize daemon startup ownership and retirement (#3127)
* fix: centralize daemon startup and retirement ownership * refactor: share daemon registration identity proof * chore(gates): acknowledge composed health probe timing * refactor: keep health probe outcome classification consistent * chore(gates): pin composed health probe declaration * test: preserve scoped repair evidence and restart probe cancellation
1 parent 052cba8 commit 2212eac

41 files changed

Lines changed: 3600 additions & 1563 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 41 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,44 @@ guard cannot constrain legacy code after its final check. The support boundary t
4040
requires deployment control; host-kit does not claim to detect or evict every legacy user.
4141

4242
Daemon registration has a separate cutover boundary: keep the same `daemon.lock` path and
43-
refuse legacy files rather than automatically reclaiming them. Its startup tests must cover
44-
an already-running older daemon and concurrent old/new startup. This does not expand the
45-
host-kit mixed-protocol support contract.
43+
refuse legacy files rather than automatically reclaiming them. A legacy daemon creates an
44+
exclusive file; a hardened daemon creates a directory at that same path. The old acquisition
45+
cannot unlink a directory, and the new acquisition retains an existing file.
46+
47+
The [registration tests](../../src/__tests__/daemon-registration-owner.test.ts) exercise real
48+
children using the c237027737 legacy acquisition and the current owner. They cover an older
49+
daemon already running, a hardened owner waiting to publish metadata, and concurrent startup.
50+
The client refuses an older registration before signaling or changing it. This proves the daemon
51+
cutover; it does not expand the host-kit mixed-protocol support contract. Older clients still
52+
require the deployment controls above.
53+
54+
## Recovering retained legacy daemon state
55+
56+
Stop every daemon and client using the affected state directory, including older versions,
57+
and verify that those processes have exited. Keep them stopped throughout recovery.
58+
Only then remove the legacy `daemon.lock` file and any retained `daemon.reclaim.lock` guard
59+
from that directory. Preserve the other state, logs and repair evidence.
60+
61+
Start one supported version using that directory and prevent older clients or daemons from
62+
returning. If every user cannot be identified and stopped, retain the files and use a separate
63+
state directory. This procedure applies to daemon registration; shared build and cache locks
64+
require the same confirmation for every process using their own paths.
65+
66+
## Registration operations
67+
68+
[Shared retirement](../../src/daemon-registration-owner.ts) owns verified termination, protected
69+
metadata inspection and removal, and release. Takeover, failed startup, replay cleanup, timeout
70+
reset and manual stop await its result. Abandoned recovery uses the same protected retirement
71+
sequence without signaling a live process. Daemon publication and shutdown use functions bound
72+
to their acquired claim.
73+
74+
```mermaid
75+
flowchart LR
76+
C[Client lifecycle and timeout] --> R[Shared retirement]
77+
M[Manual stop] --> R
78+
P[Abandoned recovery and pruning] --> R
79+
R --> L[Acquired registration claim]
80+
D[Daemon startup and shutdown] --> O[Functions bound to own claim]
81+
O --> L
82+
L --> F[Protected metadata and reports]
83+
```

‎packages/host-kit/src/internal/owner-identity-liveness.test.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,3 +59,13 @@ test('a missing entry in a completed process snapshot stays fail-closed without
5959
assert.equal(mockIsProcessZombie.mock.calls.length, 0);
6060
assert.equal(mockReadProcessStartTime.mock.calls.length, 0);
6161
});
62+
63+
test('a pid outside the native range is unknown without a liveness probe', () => {
64+
assert.equal(
65+
classifyOwnerLiveness({ owner: { pid: 2_147_483_648, startTime: 'start-a' } }),
66+
'unknown',
67+
);
68+
assert.equal(mockIsProcessAlive.mock.calls.length, 0);
69+
assert.equal(mockIsProcessZombie.mock.calls.length, 0);
70+
assert.equal(mockReadProcessStartTime.mock.calls.length, 0);
71+
});

‎packages/host-kit/src/internal/owner-identity.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,11 @@ export type OwnerIdentity = {
1111
startTime: string | null;
1212
};
1313

14+
/** A process id accepted by Node's native signal API. */
15+
export function isProcessPid(value: unknown): value is number {
16+
return typeof value === 'number' && Number.isInteger(value) && value > 0 && value <= 0x7fff_ffff;
17+
}
18+
1419
export type OwnerLiveness =
1520
| 'live'
1621
| 'owner-process-dead'
@@ -75,6 +80,7 @@ export function classifyOwnerLivenessFromObservation(
7580
observation?: HostProcessIdentityObservation | null,
7681
): OwnerLiveness {
7782
const { owner, stateDir } = params;
83+
if (!isProcessPid(owner.pid)) return 'unknown';
7884
if (!isProcessAlive(owner.pid)) return 'owner-process-dead';
7985
if (observation !== undefined ? observation?.state.startsWith('Z') : isProcessZombie(owner.pid)) {
8086
return 'owner-process-dead';
@@ -88,7 +94,10 @@ export function classifyOwnerLivenessFromObservation(
8894
return 'owner-process-reused';
8995
}
9096
}
91-
if (!stateDir) return 'live';
97+
return stateDir ? classifyOwnerStateDirectory(stateDir) : 'live';
98+
}
99+
100+
function classifyOwnerStateDirectory(stateDir: string): OwnerLiveness {
92101
try {
93102
fs.statSync(stateDir);
94103
return 'live';

‎packages/host-kit/src/internal/process-lock.fixtures.ts‎

Lines changed: 49 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,28 @@
11
import fs from 'node:fs';
2+
import path from 'node:path';
23
import { vi } from 'vitest';
34
import { readProcessStartTime } from './host-process.ts';
4-
import type { ProcessLockOwner } from './process-lock.ts';
5+
import type { ProcessLockOwner, ProcessLockOwnerRecord } from './process-lock.ts';
6+
7+
export function writeLockOwnerFixture(
8+
lockDirPath: string,
9+
owner: ProcessLockOwner | ProcessLockOwnerRecord,
10+
): void {
11+
fs.mkdirSync(lockDirPath);
12+
fs.writeFileSync(path.join(lockDirPath, 'owner.json'), JSON.stringify(owner));
13+
}
14+
15+
export function writeDeadLockFixture(lockDirPath: string, acquiredAtMs = Date.now()): void {
16+
writeLockOwnerFixture(lockDirPath, { pid: 999_999_999, startTime: null, acquiredAtMs });
17+
}
18+
19+
export function failUnlinkForPath(filePath: string, error: Error) {
20+
const unlink = fs.unlinkSync;
21+
return vi.spyOn(fs, 'unlinkSync').mockImplementation((target) => {
22+
if (String(target) === filePath) throw error;
23+
return unlink(target);
24+
});
25+
}
526

627
export function currentProcessOwner(): ProcessLockOwner {
728
return {
@@ -41,3 +62,30 @@ export function onFirstGuardOpen(mutexPath: string, action: () => void) {
4162
}) as typeof fs.openSync);
4263
return { fired: () => fired, restore: () => spy.mockRestore() };
4364
}
65+
66+
export const UNINFORMATIVE_OWNER_RECORDS = [
67+
'{ pid: ',
68+
'null',
69+
'"999999999"',
70+
'{"pid":"999999999","startTime":null,"acquiredAtMs":1}',
71+
'{"pid":0,"startTime":null,"acquiredAtMs":1}',
72+
'{"pid":999999999,"startTime":7,"acquiredAtMs":1}',
73+
'{"pid":999999999,"startTime":null}',
74+
] as const;
75+
76+
function failRenameForPath(filePath: string, error: Error) {
77+
const rename = fs.renameSync;
78+
return vi.spyOn(fs, 'renameSync').mockImplementation((source, destination) => {
79+
if (String(destination) === filePath) throw error;
80+
return rename(source, destination);
81+
});
82+
}
83+
84+
export function failLockOwnerPublication(lockDirPath: string, releaseFails: boolean) {
85+
const primary = Object.assign(new Error('publication failed'), { code: 'EIO' });
86+
const releaseError = Object.assign(new Error('guard unlink refused'), { code: 'EPERM' });
87+
const renameSpy = failRenameForPath(path.join(lockDirPath, 'owner.json'), primary);
88+
const guardPath = lockDirPath.replace(/\.lock$/, '.reclaim.lock');
89+
const unlinkSpy = releaseFails ? failUnlinkForPath(guardPath, releaseError) : undefined;
90+
return { primary, renameSpy, unlinkSpy, guardPath };
91+
}

0 commit comments

Comments
 (0)