Skip to content

Commit eb3db8f

Browse files
thymikeeclaude
andcommitted
fix(daemon): retire embedded records after proven host exit
Centralize stop owner refusals and preserve released host diagnostics. Document the stop behavior and removed reasons in a patch changeset. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 86ae7b7 commit eb3db8f

15 files changed

Lines changed: 117 additions & 79 deletions

File tree

‎.changeset/embedded-owner-stop.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
'agent-device': patch
3+
---
4+
5+
Make `daemon stop` fail with `daemon-owner-embedded` for a live embedded runtime instead of exiting successfully. Close the runtime in its host process with the handle returned by `startAgentDevice()`. Stop sends no shutdown request or signal to embedded or unrecognized owners. It can retire their abandoned registrations after proving the recorded host lifetime exited.
6+
7+
Remove the `daemon-shutdown-unconfirmed`, `daemon-embedded-stop-unreachable`, and `daemon-not-embedded` reasons shipped in v0.21.29 along with the external embedded shutdown path. In-process `close()` still returns its shutdown report.

‎docs/adr/0034-provider-plugin-registry.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ had to fake the store to load a plugin from its own dependencies (#3747).
5858

5959
## Daemon ownership
6060

61-
Clients retain managed and attach lifecycles. Managed clients may start a daemon; attach clients cannot start or replace one. An embedder calls `startAgentDevice({ stateDir, plugins?, host? })` from `agent-device` to own a runtime in its process. The main entry loads the runtime when called. The returned client and serializable `clientConfig` identify that exact instance. Attaching checks normal version and code compatibility before checking the instance pin. `close()` in the host process is the only way to shut an embedded runtime down, and returns its `ShutdownReport`. `daemon stop` refuses embedded ownership with `daemon-owner-embedded` and unrecognized ownership with `daemon-owner-unrecognized`, without a request or signal. The embedded-ownership refusal names the host PID and directs the caller to close the runtime there. The CLI cannot replace an embedded runtime. Registration and its lock remain held while requests or platform owners are unfinished.
61+
Clients retain managed and attach lifecycles. Managed clients may start a daemon; attach clients cannot start or replace one. An embedder calls `startAgentDevice({ stateDir, plugins?, host? })` from `agent-device` to own a runtime in its process. The main entry loads the runtime when called. The returned client and serializable `clientConfig` identify that exact instance. Attaching checks normal version and code compatibility before checking the instance pin. `close()` in the host process is the only way to shut an embedded runtime down, and returns its `ShutdownReport`. `daemon stop` refuses live embedded ownership with `daemon-owner-embedded` and live unrecognized ownership with `daemon-owner-unrecognized`, without a request or signal. The embedded-ownership refusal names the host PID and directs the caller to close the runtime there. Stop may retire an embedded or unrecognized registration when its recorded host lifetime has provably exited. The CLI cannot replace a live embedded runtime. Registration and its lock remain held while requests or platform owners are unfinished.
6262

6363
The embedder supplies plugin objects directly. They follow the built-ins through the same registry validation; this runtime does not read the plugin store. Plugin failures remain inventory data. Logging adapters, a separate package entry, and disposal protocols are not required to own a daemon: the library exposes the client, its attach configuration, and `close()`.
6464

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -511,7 +511,11 @@ async function proveExitWithoutSignaling(
511511
observed: OwnerIdentity,
512512
reason: 'identity-unverified' | 'embedded-owner' | 'owner-unproven' = 'identity-unverified',
513513
): Promise<DaemonTerminationResult> {
514-
if (!observed.startTime?.trim()) return { status: 'retained', reason: 'missing-start-time' };
514+
if (!observed.startTime?.trim())
515+
return {
516+
status: 'retained',
517+
reason: reason === 'identity-unverified' ? 'missing-start-time' : reason,
518+
};
515519
const identity = { pid: observed.pid, startTime: observed.startTime };
516520
return (await waitForDaemonExit(identity, { timeoutMs: 0 })).exited
517521
? { status: 'exited', identity, mode: 'already-exited' }

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

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -209,7 +209,6 @@ export type DaemonStopIdentity = Readonly<{
209209
/** `absent`: no record. `unreadable`: a record whose contents cannot be used, unreadable or malformed. */
210210
ownership: DaemonOwnership | 'absent' | 'unreadable';
211211
identity: OwnerIdentity | null;
212-
record: DaemonRecord | null;
213212
}>;
214213

215214
/**
@@ -223,9 +222,8 @@ export function readDaemonStopIdentity(infoPath: string): DaemonStopIdentity {
223222
return {
224223
ownership: reading.status === 'absent' ? 'absent' : 'unreadable',
225224
identity: null,
226-
record: null,
227225
};
228-
return { ownership: reading.ownership, identity: reading.identity, record: reading.record };
226+
return { ownership: reading.ownership, identity: reading.identity };
229227
}
230228

231229
/**

‎packages/daemon-contracts/src/daemon-resolution.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -293,3 +293,8 @@ export function readDaemonLifecycleCensus(details: unknown): DaemonLifecycleCens
293293
leases: leases as number,
294294
};
295295
}
296+
297+
/** Directs embedded runtime callers to the host that owns close. */
298+
export function embeddedCloseHint(pid: number | undefined): string {
299+
return `${pid === undefined ? 'The runtime is owned by its host process.' : `The runtime is owned by host process ${pid}.`} Close it there with the handle returned by startAgentDevice(). If the host has exited, use daemon stop or ensureDaemon() for this state directory to recover its abandoned registration.`;
300+
}

‎packages/daemon-contracts/src/daemon-stop.ts‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import type { DaemonRetirementResult } from './daemon-registration-owner.ts';
33

44
import {
55
DAEMON_LIFECYCLE_REASONS,
6+
embeddedCloseHint,
67
DAEMON_RECORD_OWNER_UNRECOGNIZED_REASON,
78
type DaemonPaths,
89
type ObservedDaemonIdentity,
@@ -47,8 +48,8 @@ export type DaemonStopResult = {
4748
/**
4849
* Retires the daemon whose lifetime the caller read, and shapes that retirement as a stop result.
4950
*
50-
* The public stop router refuses embedded and unknown registrations before this path.
51-
* Direct callers still supply ownership to retirement, which refuses to signal a non-detached owner.
51+
* Retirement refuses to signal embedded and unknown owners, and retires their records only
52+
* when the observed host lifetime has provably exited.
5253
*/
5354
export async function stopDaemon(params: {
5455
paths: DaemonPaths;
@@ -106,11 +107,12 @@ export async function stopDaemon(params: {
106107
*/
107108
function ownerRefusal(
108109
reason: 'embedded-owner' | 'owner-unproven',
110+
pid: number,
109111
): Readonly<{ reason: string; hint: string }> {
110112
return reason === 'embedded-owner'
111113
? {
112114
reason: DAEMON_LIFECYCLE_REASONS.ownerEmbedded,
113-
hint: 'Nothing was signaled. Close the host that started this runtime, or repair its record after the process has exited.',
115+
hint: embeddedCloseHint(pid),
114116
}
115117
: {
116118
reason: DAEMON_RECORD_OWNER_UNRECOGNIZED_REASON,
@@ -129,7 +131,7 @@ function daemonRetirementError(
129131
const refusal =
130132
retirement.status === 'retained' &&
131133
(retirement.reason === 'embedded-owner' || retirement.reason === 'owner-unproven')
132-
? ownerRefusal(retirement.reason)
134+
? ownerRefusal(retirement.reason, info.pid)
133135
: undefined;
134136
return new AppError(
135137
'COMMAND_FAILED',

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

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -385,14 +385,15 @@ test('daemon status names a record whose owner it cannot recognize', async () =>
385385
expect(render()).toContain('pid 321, owner-not-recognized');
386386
});
387387

388-
test('daemon stop routes a host-owned record through the one router and never the signal path', async () => {
388+
test('daemon stop passes host ownership to shared retirement without detached cleanup', async () => {
389389
const stateDir = mkdtempForTestSync('agent-device-daemon-command-embedded-');
390390
fs.writeFileSync(
391391
`${stateDir}/daemon.json`,
392392
JSON.stringify({ pid: 555, processStartTime: 'start-time', ownership: 'embedded' }),
393393
{ mode: 0o600 },
394394
);
395395

396+
mocks.stopDaemon.mockRejectedValueOnce({ details: { reason: 'daemon-owner-embedded' } });
396397
try {
397398
await expect(
398399
daemonCommand({
@@ -403,8 +404,10 @@ test('daemon stop routes a host-owned record through the one router and never th
403404
}),
404405
).rejects.toMatchObject({ details: { reason: 'daemon-owner-embedded' } });
405406

406-
// The embedded route owns this record end to end: no detached retirement, no cleanup, no output.
407-
expect(mocks.stopDaemon).not.toHaveBeenCalled();
407+
expect(mocks.stopDaemon).toHaveBeenCalledWith({
408+
paths: expect.objectContaining({ baseDir: stateDir }),
409+
observed: { pid: 555, startTime: 'start-time', ownership: 'embedded' },
410+
});
408411
expect(mocks.cleanupDaemonOwner).not.toHaveBeenCalled();
409412
expect(mocks.writeCommandOutput).not.toHaveBeenCalled();
410413
expect(fs.readFileSync(`${stateDir}/daemon.json`, 'utf8')).toContain('"embedded"');

‎src/commands/schema/cli-help.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -480,7 +480,7 @@ Runner and daemon lifecycle (applies to simulators too):
480480
Each AGENT_DEVICE_STATE_DIR runs its own daemon. It self-exits after an idle window (default 5 minutes, matching the runner idle-stop default) once it has no open sessions, no in-flight requests, and no active recording; set AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS to override, or 0 to disable idle reap.
481481
A client starting a local daemon waits while the daemon process stays alive and keeps publishing startup progress, so an overloaded host makes startup slower, not failed. It stops at a ceiling (default 120 s; set AGENT_DEVICE_DAEMON_STARTUP_TIMEOUT_MS to a positive integer number of milliseconds to override) and names the outcome in error details.reason: startup-exited (the process ended before registering), startup-stalled (alive, no startup progress for a fixed 60 s window the ceiling variable does not change), or startup-ceiling (a startup was still live when the ceiling passed — this client's daemon or another client's; the client stops its own launch and never signals another client's live daemon. Only a progressing own launch outlasts the 60 s stall window, so a ceiling set below 60 s also ends a silent own launch this way). details.phases carries the startup phase timings it observed and details.startupTimeoutMs the effective ceiling. Branch on details.reason, never on the message. The variable is read only when a client must start a daemon: a value that is not a positive integer fails with INVALID_ARGS before the daemon spawns, and a client that only attaches to or reuses a running daemon never reads it.
482482
A command that needs the shared local daemon starts it for its state dir when none runs (device status and device release --stale never contact one). When the running daemon comes from another version or build, the command replaces it only if the daemon reports no work: no in-flight request, session, repair session, or live lease (a streaming resumable upload and a host human-control hold that names no lease are not counted); otherwise it fails with details.reason daemon-busy and leaves the daemon alone. A daemon that agreed to leave is waited for up to 60 s and never signaled while it drains; one still running then fails with details.reason daemon-drain-timeout unless it answers nothing and is provably a daemon process, which is force-retired. A daemon from a release that predates this check is never replaced and fails with daemon-incompatible. End a busy or older daemon deliberately with agent-device daemon stop --state-dir <path>. Node clients pick daemonLifecycle 'attach' (never starts or replaces a daemon; fails with daemon-not-running or daemon-incompatible) or 'managed' (the default until 0.22), and ensureDaemon() starts or replaces one explicitly.
483-
daemon stop --state-dir <path> stops a detached daemon with process signals after verifying its identity. For an embedded runtime, stop refuses with details.reason daemon-owner-embedded and a hint naming the host PID. Close that runtime in its host process with the handle returned by startAgentDevice(). Stop refuses unrecognized ownership with daemon-owner-unrecognized and sends no request or signal. Without --clean, an unreadable daemon.json fails with daemon-record-unreadable. daemon status shows host-owned or owner-not-recognized. Managed clients reuse a matching embedded runtime. Takeover, drain, and timeout recovery refuse a live embedded or unrecognized owner without a signal; a provably exited owner is retired so the state directory stays usable. Detached stop and cleanup use the lifetime and ownership from one registration read. --clean requires proven detached ownership; embedded, unrecognized and unreadable records fail with daemon-clean-not-detached because that cleanup walks the owner's whole process tree.
483+
daemon stop --state-dir <path> stops a detached daemon with process signals after verifying its identity. For a live embedded runtime, stop refuses with details.reason daemon-owner-embedded and a hint naming the host PID. Close that runtime in its host process with the handle returned by startAgentDevice(). Stop refuses live unrecognized ownership with daemon-owner-unrecognized and sends no request or signal. Stop retires an embedded or unrecognized registration when its recorded host lifetime has provably exited. Without --clean, an unreadable daemon.json fails with daemon-record-unreadable. daemon status shows host-owned or owner-not-recognized. Managed clients reuse a matching embedded runtime. Takeover, drain, and timeout recovery refuse a live embedded or unrecognized owner without a signal; a provably exited owner is retired so the state directory stays usable. Detached stop and cleanup use the lifetime and ownership from one registration read. --clean requires proven detached ownership; embedded, unrecognized and unreadable records fail with daemon-clean-not-detached because that cleanup walks the owner's whole process tree.
484484
On a machine shared by several agents, set AGENT_DEVICE_SESSION_IDLE_TIMEOUT_MS to also expire an individual session that has taken a host-global device claim and then received no commands for that long; the claim is released and the next command on that session answers SESSION_NOT_FOUND with details.reason SESSION_IDLE_EXPIRED naming the window and the device. Off by default, because on a shared host "idle" and "thinking" are indistinguishable: only set it where an abandoned claim blocking every other agent is the worse failure. Sessions holding a remote lease or any active capture (recording, logs, audio, performance, or trace) are never expired this way.
485485
A stale iOS runner lease — its owner process dead, or its AGENT_DEVICE_STATE_DIR deleted — is reclaimed automatically instead of failing with "is already owned by another agent-device daemon". A live owner's runner is also reclaimed when the requesting daemon holds the host-global device claim for that device: claims are exclusive, so holding one proves the runner's owner released the device and merely kept the runner warm. The error remains only for owners outside claim arbitration (a pre-claims build, or daemons pointed at different claim stores).
486486

0 commit comments

Comments
 (0)