Skip to content

Commit 3908559

Browse files
authored
fix: report real claim results from daemon stop (#1818)
* fix: report real claim results from daemon stop `daemon stop` typed `claimsReleased`/`claimsOrphaned` as the literal `[]` and every path hardcoded them, so a graceful stop that released a device claim still reported none (#1799 observation 3, #1320 acceptance). Graceful teardown now records each session's claim outcome — released after a clean teardown, orphaned when teardown left the claim in place — into the daemon shutdown report, and the CLI merges them alongside provider releases. Forced and not-running stops stay empty because they cannot know, and a report written before claim reporting still reads its provider releases. * fix: classify daemon stop claim results from the clear outcome `clearDeviceClaim` deliberately resolves without deleting when the on-disk claim is no longer the one it acquired, so the shutdown ledger's "the call resolved" test reported a successor's claim as released — a device the daemon never freed, counted as freed. `clearDeviceClaim` now returns a typed outcome (`deleted` | `absent` | `ownership-changed`) instead of nothing, and the ledger classifies from it: released only when absence is confirmed, and a new `superseded` bucket for a claim another owner had already taken over. Superseded is neither released (this daemon freed nothing) nor orphaned (no claim of ours remains to reconcile), so folding it into either would break that list's meaning; it also raises a warning so a device now owned elsewhere cannot pass silently.
1 parent 8d0de32 commit 3908559

10 files changed

Lines changed: 415 additions & 49 deletions

‎src/cli/commands/__tests__/daemon.test.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ const GRACEFUL_RESULT: DaemonStopResult = {
3535
cleanupConfidence: 'known',
3636
claimsReleased: [],
3737
claimsOrphaned: [],
38+
claimsSuperseded: [],
3839
providerReleases: { status: 'completed', released: [], pending: [] },
3940
warnings: [],
4041
};
@@ -68,11 +69,18 @@ test('merges a graceful shutdown report and cleans runner leases with the start-
6869
const stateDir = mkdtempForTestSync('agent-device-daemon-command-');
6970
mocks.readDaemonStopIdentity.mockReturnValue({ pid: 123, processStartTime: 'start-time' });
7071
mocks.stopDaemon.mockResolvedValue(GRACEFUL_RESULT);
72+
const claim = {
73+
deviceKey: 'local:android:none:emulator-5554',
74+
session: 'default',
75+
platform: 'android',
76+
deviceId: 'emulator-5554',
77+
};
7178
mocks.readDaemonShutdownReport.mockReturnValue({
7279
providerReleases: {
7380
released: [{ leaseId: 'lease-1', provider: 'limrun' }],
7481
pending: [],
7582
},
83+
claims: { released: [claim], orphaned: [], superseded: [] },
7684
});
7785

7886
try {
@@ -95,6 +103,10 @@ test('merges a graceful shutdown report and cleans runner leases with the start-
95103
released: [{ leaseId: 'lease-1', provider: 'limrun' }],
96104
pending: [],
97105
},
106+
// #1799: a graceful stop reports the claims it actually released.
107+
claimsReleased: [claim],
108+
claimsOrphaned: [],
109+
claimsSuperseded: [],
98110
}),
99111
expect.any(Function),
100112
);

‎src/cli/commands/daemon.ts‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,14 @@ function mergeShutdownReport(
4141
): DaemonStopResult {
4242
if (stopped.mode !== 'graceful' || report) {
4343
return report
44-
? { ...stopped, providerReleases: { status: 'completed', ...report.providerReleases } }
44+
? {
45+
...stopped,
46+
providerReleases: { status: 'completed', ...report.providerReleases },
47+
claimsReleased: report.claims.released,
48+
claimsOrphaned: report.claims.orphaned,
49+
claimsSuperseded: report.claims.superseded,
50+
warnings: [...stopped.warnings, ...supersededClaimWarnings(report.claims.superseded)],
51+
}
4552
: stopped;
4653
}
4754
return {
@@ -55,6 +62,16 @@ function mergeShutdownReport(
5562
};
5663
}
5764

65+
/** A superseded claim is not a failure to report as one, but the operator's
66+
* device is now owned elsewhere, so it must not pass silently. */
67+
function supersededClaimWarnings(superseded: DaemonStopResult['claimsSuperseded']): string[] {
68+
if (superseded.length === 0) return [];
69+
const devices = superseded.map((claim) => claim.deviceId).join(', ');
70+
return [
71+
`Another owner had already claimed ${devices} before this daemon released it, so those devices are now owned elsewhere.`,
72+
];
73+
}
74+
5875
function renderDaemonStop(
5976
result: Pick<DaemonStopResult, 'stopped' | 'mode' | 'warnings'> & {
6077
clean: boolean;

‎src/daemon/__tests__/daemon-shutdown-report.test.ts‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,14 @@ import {
99
import { LeaseRegistry } from '../lease-registry.ts';
1010
import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
1111

12-
test('round-trips provider release records without persisting lease credentials', () => {
12+
const claim = {
13+
deviceKey: 'local:android:none:emulator-5554',
14+
session: 'default',
15+
platform: 'android',
16+
deviceId: 'emulator-5554',
17+
};
18+
19+
test('round-trips provider release and device claim records without lease credentials', () => {
1320
const stateDir = mkdtempForTestSync('agent-device-shutdown-report-');
1421
const lease = new LeaseRegistry().allocateLease({
1522
tenantId: 'tenant-a',
@@ -18,13 +25,36 @@ test('round-trips provider release records without persisting lease credentials'
1825
});
1926

2027
try {
21-
writeDaemonShutdownReport(stateDir, { released: [lease], pending: [lease] });
28+
writeDaemonShutdownReport(stateDir, {
29+
providerReleases: { released: [lease], pending: [lease] },
30+
claims: { released: [claim], orphaned: [], superseded: [claim] },
31+
});
2232

2333
expect(readDaemonShutdownReport(stateDir)).toEqual({
2434
providerReleases: {
2535
released: [{ leaseId: lease.leaseId, provider: 'limrun' }],
2636
pending: [{ leaseId: lease.leaseId, provider: 'limrun' }],
2737
},
38+
claims: { released: [claim], orphaned: [], superseded: [claim] },
39+
});
40+
} finally {
41+
fs.rmSync(stateDir, { recursive: true, force: true });
42+
}
43+
});
44+
45+
test('a report written before claim reporting still reads its provider releases', () => {
46+
const stateDir = mkdtempForTestSync('agent-device-shutdown-report-');
47+
const reportPath = path.join(stateDir, 'daemon-shutdown.json');
48+
49+
try {
50+
fs.writeFileSync(
51+
reportPath,
52+
JSON.stringify({ providerReleases: { released: [], pending: [] } }),
53+
);
54+
55+
expect(readDaemonShutdownReport(stateDir)).toEqual({
56+
providerReleases: { released: [], pending: [] },
57+
claims: { released: [], orphaned: [], superseded: [] },
2858
});
2959
} finally {
3060
fs.rmSync(stateDir, { recursive: true, force: true });

‎src/daemon/__tests__/device-claims.test.ts‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -254,10 +254,28 @@ test('clears only the exact owner token and identity, never a successor claim',
254254
claimPath(root),
255255
JSON.stringify({ ...stored, ownerToken: 'successor-token', session: 'second' }),
256256
);
257-
await clearDeviceClaim(acquired.ownership);
257+
// Resolving is not releasing: the outcome is what a caller reporting
258+
// ownership must read, since the successor's claim is deliberately kept.
259+
assert.equal(await clearDeviceClaim(acquired.ownership), 'ownership-changed');
258260
assert.equal(inspectDeviceClaims({ serial: device.id })[0]?.claim?.session, 'second');
259261
});
260262

263+
test('reports the exact outcome of clearing an owned, missing, and unowned claim', async () => {
264+
const root = useClaimsRoot();
265+
const acquired = await acquireDeviceClaim({
266+
device,
267+
session: 'owner',
268+
workspace: '/worktrees/owner',
269+
stateDir: root,
270+
});
271+
assert.equal(acquired.status, 'acquired');
272+
if (acquired.status !== 'acquired') return;
273+
274+
assert.equal(await clearDeviceClaim(acquired.ownership), 'deleted');
275+
assert.equal(await clearDeviceClaim(acquired.ownership), 'absent');
276+
assert.equal(await clearDeviceClaim(undefined), 'absent');
277+
});
278+
261279
test('keeps corrupt records visible and classifies dead owners without reclaiming either', () => {
262280
const root = useClaimsRoot();
263281
fs.writeFileSync(path.join(root, 'corrupt.json'), '{bad json');

‎src/daemon/daemon-shutdown-report.ts‎

Lines changed: 68 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,21 +9,53 @@ export type ProviderReleaseRecord = {
99
provider?: string;
1010
};
1111

12+
/**
13+
* #1320: what happened to one session's device claim during graceful teardown.
14+
* `released` means the claim was confirmed gone after the session reached a safe
15+
* terminal state; `orphaned` means teardown left it in place, so the exiting
16+
* daemon's dead owner identity is what later proves it reclaimable; `superseded`
17+
* means another owner had already replaced it, so this daemon released nothing
18+
* and left nothing to reconcile.
19+
*/
20+
export type DeviceClaimRecord = {
21+
deviceKey: string;
22+
session: string;
23+
platform: string;
24+
deviceId: string;
25+
};
26+
1227
export type DaemonShutdownReport = {
1328
providerReleases: {
1429
released: ProviderReleaseRecord[];
1530
pending: ProviderReleaseRecord[];
1631
};
32+
claims: {
33+
released: DeviceClaimRecord[];
34+
orphaned: DeviceClaimRecord[];
35+
superseded: DeviceClaimRecord[];
36+
};
1737
};
1838

1939
export function writeDaemonShutdownReport(
2040
stateDir: string,
21-
providerReleases: { released: readonly DeviceLease[]; pending: readonly DeviceLease[] },
41+
outcome: {
42+
providerReleases: { released: readonly DeviceLease[]; pending: readonly DeviceLease[] };
43+
claims: {
44+
released: readonly DeviceClaimRecord[];
45+
orphaned: readonly DeviceClaimRecord[];
46+
superseded: readonly DeviceClaimRecord[];
47+
};
48+
},
2249
): void {
2350
const report: DaemonShutdownReport = {
2451
providerReleases: {
25-
released: providerReleases.released.map(toProviderReleaseRecord),
26-
pending: providerReleases.pending.map(toProviderReleaseRecord),
52+
released: outcome.providerReleases.released.map(toProviderReleaseRecord),
53+
pending: outcome.providerReleases.pending.map(toProviderReleaseRecord),
54+
},
55+
claims: {
56+
released: [...outcome.claims.released],
57+
orphaned: [...outcome.claims.orphaned],
58+
superseded: [...outcome.claims.superseded],
2759
},
2860
};
2961
const filePath = shutdownReportPath(stateDir);
@@ -42,7 +74,10 @@ export function writeDaemonShutdownReport(
4274
export function readDaemonShutdownReport(stateDir: string): DaemonShutdownReport | null {
4375
try {
4476
const parsed = JSON.parse(fs.readFileSync(shutdownReportPath(stateDir), 'utf8')) as unknown;
45-
return isDaemonShutdownReport(parsed) ? parsed : null;
77+
if (!isProviderReleaseReport(parsed)) return null;
78+
// A report left behind by a daemon that predates claim reporting still
79+
// describes its provider releases honestly; it just knows nothing of claims.
80+
return { ...parsed, claims: readClaimSection(parsed) };
4681
} catch {
4782
return null;
4883
}
@@ -65,7 +100,9 @@ function toProviderReleaseRecord(lease: DeviceLease): ProviderReleaseRecord {
65100
};
66101
}
67102

68-
function isDaemonShutdownReport(value: unknown): value is DaemonShutdownReport {
103+
function isProviderReleaseReport(
104+
value: unknown,
105+
): value is Omit<DaemonShutdownReport, 'claims'> & { claims?: unknown } {
69106
if (!value || typeof value !== 'object') return false;
70107
const releases = (value as { providerReleases?: unknown }).providerReleases;
71108
if (!releases || typeof releases !== 'object') return false;
@@ -78,6 +115,32 @@ function isDaemonShutdownReport(value: unknown): value is DaemonShutdownReport {
78115
);
79116
}
80117

118+
function readClaimSection(value: { claims?: unknown }): DaemonShutdownReport['claims'] {
119+
const claims = value.claims;
120+
if (!claims || typeof claims !== 'object') return { released: [], orphaned: [], superseded: [] };
121+
const records = claims as { released?: unknown; orphaned?: unknown; superseded?: unknown };
122+
return {
123+
released: readClaimRecords(records.released),
124+
orphaned: readClaimRecords(records.orphaned),
125+
superseded: readClaimRecords(records.superseded),
126+
};
127+
}
128+
129+
function readClaimRecords(value: unknown): DeviceClaimRecord[] {
130+
return Array.isArray(value) ? value.filter(isDeviceClaimRecord) : [];
131+
}
132+
133+
function isDeviceClaimRecord(value: unknown): value is DeviceClaimRecord {
134+
if (!value || typeof value !== 'object') return false;
135+
const record = value as Partial<Record<keyof DeviceClaimRecord, unknown>>;
136+
return (
137+
typeof record.deviceKey === 'string' &&
138+
typeof record.session === 'string' &&
139+
typeof record.platform === 'string' &&
140+
typeof record.deviceId === 'string'
141+
);
142+
}
143+
81144
function isProviderReleaseRecord(value: unknown): value is ProviderReleaseRecord {
82145
if (!value || typeof value !== 'object') return false;
83146
const record = value as { leaseId?: unknown; provider?: unknown };

‎src/daemon/daemon-stop.ts‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import { isAgentDeviceDaemonProcess, trySignalProcess } from './daemon-process.t
44
import { isProcessAlive, waitForProcessExit } from '../utils/host-process.ts';
55
import { sleep } from '../utils/timeouts.ts';
66
import type { DaemonPaths } from './config.ts';
7-
import type { ProviderReleaseRecord } from './daemon-shutdown-report.ts';
7+
import type { DeviceClaimRecord, ProviderReleaseRecord } from './daemon-shutdown-report.ts';
88

99
const DAEMON_STOP_GRACE_TIMEOUT_MS = 10_000;
1010
const DAEMON_STOP_KILL_TIMEOUT_MS = 2_000;
@@ -19,8 +19,15 @@ export type DaemonStopResult = {
1919
stopped: boolean;
2020
mode: 'graceful' | 'forced' | 'not-running';
2121
cleanupConfidence: 'known' | 'unknown';
22-
claimsReleased: [];
23-
claimsOrphaned: [];
22+
/**
23+
* #1320 claim results. Only a graceful stop can carry values: they come from
24+
* the shutdown report the exiting daemon wrote, so a forced kill or a daemon
25+
* that was not running reports none rather than claiming certainty.
26+
*/
27+
claimsReleased: DeviceClaimRecord[];
28+
claimsOrphaned: DeviceClaimRecord[];
29+
/** Claims another owner had already taken over; this daemon released nothing. */
30+
claimsSuperseded: DeviceClaimRecord[];
2431
providerReleases: {
2532
status: 'completed' | 'unknown';
2633
released: ProviderReleaseRecord[];
@@ -66,6 +73,7 @@ export async function stopDaemon(params: {
6673
cleanupConfidence: 'known',
6774
claimsReleased: [],
6875
claimsOrphaned: [],
76+
claimsSuperseded: [],
6977
providerReleases: { status: 'completed', released: [], pending: [] },
7078
warnings: [],
7179
};
@@ -89,6 +97,7 @@ export async function stopDaemon(params: {
8997
cleanupConfidence: 'unknown',
9098
claimsReleased: [],
9199
claimsOrphaned: [],
100+
claimsSuperseded: [],
92101
providerReleases: { status: 'unknown', released: [], pending: null },
93102
warnings: [
94103
'The daemon was force-killed before provider lease state could be finalized. Provider allocations may remain active.',
@@ -148,6 +157,7 @@ function notRunningResult(): DaemonStopResult {
148157
cleanupConfidence: 'known',
149158
claimsReleased: [],
150159
claimsOrphaned: [],
160+
claimsSuperseded: [],
151161
providerReleases: { status: 'completed', released: [], pending: [] },
152162
warnings: [],
153163
};

‎src/daemon/device-claims.ts‎

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -231,28 +231,44 @@ function isCurrentClaimOwner(
231231
);
232232
}
233233

234+
/**
235+
* What releasing a claim actually did. Resolving is not the same as releasing:
236+
* clearing deliberately leaves a claim it does not own in place, so a caller
237+
* that reports ownership must read this rather than the absence of a throw.
238+
*
239+
* - `deleted` — the claim this ownership acquired was removed.
240+
* - `absent` — no claim remains for the device; nothing to remove.
241+
* - `ownership-changed`— a claim remains, but it is not the one we acquired
242+
* (a successor owner, or a record we cannot attribute).
243+
*/
244+
export type DeviceClaimClearOutcome = 'deleted' | 'absent' | 'ownership-changed';
245+
234246
export async function clearDeviceClaim(
235247
ownership: DeviceClaimSessionOwnership | undefined,
236-
): Promise<void> {
237-
if (!ownership) return;
238-
await withDeviceClaimLock(ownership.deviceKey, async () => {
239-
const inspected = inspectDeviceClaimFile(resolveDeviceClaimPath(ownership.deviceKey));
240-
if (!inspected?.claim) return;
248+
): Promise<DeviceClaimClearOutcome> {
249+
if (!ownership) return 'absent';
250+
return await withDeviceClaimLock(ownership.deviceKey, async () => {
251+
const claimPath = resolveDeviceClaimPath(ownership.deviceKey);
252+
const inspected = inspectDeviceClaimFile(claimPath);
253+
if (!inspected) return 'absent';
241254
const claim = inspected.claim;
242255
if (
256+
!claim ||
243257
claim.ownerToken !== ownership.ownerToken ||
244258
!ownerIdentityMatches(
245259
{ pid: claim.ownerPid, startTime: claim.ownerStartTime },
246260
{ pid: ownership.ownerPid, startTime: ownership.ownerStartTime },
247261
)
248262
) {
249-
return;
263+
return 'ownership-changed';
250264
}
251265
try {
252-
fs.unlinkSync(resolveDeviceClaimPath(ownership.deviceKey));
266+
fs.unlinkSync(claimPath);
253267
} catch (error) {
254268
if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
269+
return 'absent';
255270
}
271+
return 'deleted';
256272
});
257273
}
258274

0 commit comments

Comments
 (0)