feat: add stale device claim release and dead-end recovery guidance

Close the #1320 recovery loop for claims no daemon can settle on its own:

- agent-device device release --stale settles a provably dead owner's durable
  resources through the same exact-owner reconciliation open and daemon
  startup use, then clears the claim last — daemonlessly, composing a
  local-only platform gateway in the CLI process. Live, uncertain, PID-reused,
  and corrupt claims always fail closed and are reported with the reason.
- DEVICE_IN_USE conflicts whose recorded owner provably cannot release
  (dead or superseded) now carry the exact release command as their recovery
  instead of a status inspection that dead-ended.
- device status --stale now offers the matching release command when provably
  dead owners are listed.
- daemon stop now warns in text output when a claim was orphaned (previously
  visible only via --json) and names the status/release commands.

Part of #1320.

Author: thymikee

src/__tests__/cli-device-release.test.ts

@@ -0,0 +1,130 @@
+import assert from 'node:assert/strict';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { test, vi } from 'vitest';
+import { readCurrentOwnerIdentity } from '@agent-device/host-kit/process';
+import { runCliCapture } from './cli-capture.ts';
+import { mkdtempForTestSync } from './test-utils/tmp-dir.ts';
+
+vi.mock('@agent-device/host-kit/process', async (importOriginal) =>
+  (await import('./test-utils/host-process-mock.ts')).pinOwnProcessStartTime(importOriginal),
+);
+
+function hashedClaimPath(claimsDir: string, deviceKey: string): string {
+  const hash = crypto.createHash('sha256').update(deviceKey).digest('hex');
+  return path.join(claimsDir, `${hash}.json`);
+}
+
+function writeClaim(
+  claimsDir: string,
+  params: {
+    deviceKey: string;
+    id: string;
+    name: string;
+    session: string;
+    ownerPid: number;
+    ownerStartTime: string | null;
+    stateDir: string;
+  },
+): void {
+  fs.writeFileSync(
+    hashedClaimPath(claimsDir, params.deviceKey),
+    JSON.stringify({
+      schemaVersion: 1,
+      deviceKey: params.deviceKey,
+      device: { platform: 'android', id: params.id, name: params.name, kind: 'emulator' },
+      session: params.session,
+      workspace: '/worktrees/release-test',
+      stateDir: params.stateDir,
+      ownerPid: params.ownerPid,
+      ownerStartTime: params.ownerStartTime,
+      ownerToken: `${params.session}-token`,
+      createdAtMs: 1,
+      updatedAtMs: 1,
+    }),
+  );
+}
+
+test('device release requires --stale and explains how live owners are released', async () => {
+  const result = await runCliCapture(['device', 'release', '--json']);
+  assert.equal(result.calls.length, 0);
+  const payload = JSON.parse(result.stdout || result.stderr);
+  assert.equal(payload.success, false);
+  assert.equal(payload.error.code, 'INVALID_ARGS');
+  assert.match(payload.error.message, /pass --stale to confirm/);
+});
+
+test('device release --stale settles a provably dead owner daemonlessly and refuses a live one', async () => {
+  const claimsDir = mkdtempForTestSync('agent-device-cli-release-');
+  const stateDir = mkdtempForTestSync('agent-device-cli-release-state-');
+  const owner = readCurrentOwnerIdentity();
+  try {
+    writeClaim(claimsDir, {
+      deviceKey: 'local:android:none:emulator-5554',
+      id: 'emulator-5554',
+      name: 'Dead Pixel',
+      session: 'dead-session',
+      ownerPid: 999_999_999,
+      ownerStartTime: 'old-start-time',
+      stateDir,
+    });
+    writeClaim(claimsDir, {
+      deviceKey: 'local:android:none:emulator-5556',
+      id: 'emulator-5556',
+      name: 'Live Pixel',
+      session: 'live-session',
+      ownerPid: owner.pid,
+      ownerStartTime: owner.startTime,
+      stateDir: process.cwd(),
+    });
+
+    const result = await runCliCapture(['device', 'release', '--stale', '--json'], {
+      env: { AGENT_DEVICE_CLAIMS_DIR: claimsDir },
+    });
+    assert.equal(result.calls.length, 0);
+    const payload = JSON.parse(result.stdout);
+    assert.equal(payload.success, true);
+    assert.equal(payload.data.released.length, 1);
+    assert.equal(payload.data.released[0].session, 'dead-session');
+    assert.equal(payload.data.refused.length, 1);
+    assert.equal(payload.data.refused[0].session, 'live-session');
+    assert.equal(payload.data.refused[0].reason, 'live-owner');
+    assert.equal(
+      fs.existsSync(hashedClaimPath(claimsDir, 'local:android:none:emulator-5554')),
+      false,
+    );
+    assert.equal(
+      fs.existsSync(hashedClaimPath(claimsDir, 'local:android:none:emulator-5556')),
+      true,
+    );
+  } finally {
+    fs.rmSync(claimsDir, { recursive: true, force: true });
+    fs.rmSync(stateDir, { recursive: true, force: true });
+  }
+});
+
+test('device status --stale offers the exact release command for provably dead owners', async () => {
+  const claimsDir = mkdtempForTestSync('agent-device-cli-release-');
+  try {
+    writeClaim(claimsDir, {
+      deviceKey: 'local:android:none:emulator-5554',
+      id: 'emulator-5554',
+      name: 'Dead Pixel',
+      session: 'dead-session',
+      ownerPid: 999_999_999,
+      ownerStartTime: 'old-start-time',
+      stateDir: process.cwd(),
+    });
+
+    const result = await runCliCapture(['device', 'status', '--stale'], {
+      env: { AGENT_DEVICE_CLAIMS_DIR: claimsDir },
+    });
+    assert.match(
+      result.stdout,
+      /Release provably dead owners with: agent-device device release --stale/,
+    );
+  } finally {
+    fs.rmSync(claimsDir, { recursive: true, force: true });
+  }
+});

src/cli-schema/command-overrides.ts

@@ -46,14 +46,14 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = {
   },
   device: {
     text: {
-      summary: 'Inspect enforced local device ownership without daemon side effects',
+      summary: 'Inspect and recover enforced local device ownership without a daemon',
       description:
-        'Inspect enforced host-local device ownership claims without starting or contacting a daemon. --stale only inspects proven-stale claims; automatic reclamation occurs during open or daemon startup after exact-owner resource reconciliation.',
+        'Inspect enforced host-local device ownership claims without starting or contacting a daemon; status --stale only inspects proven-stale claims. release --stale settles a provably dead owner through exact-owner resource reconciliation and clears its claim last — live and uncertain owners always fail closed. Automatic reclamation still occurs during open and daemon startup.',
     },
     usageOverride:
-      'device status [--platform <platform>] [--udid <udid>] [--serial <serial>] [--stale]',
+      'device status|release [--platform <platform>] [--udid <udid>] [--serial <serial>] [--stale]',
     listUsageOverride: 'device status',
-    positionalArgs: ['status'],
+    positionalArgs: ['status|release'],
     allowedFlags: ['stale'],
     supportedFlags: ['platform', 'device', 'udid', 'serial'],
   },

src/cli/commands/daemon.ts

@@ -46,7 +46,11 @@ function mergeShutdownReport(
           claimsReleased: report.claims.released,
           claimsOrphaned: report.claims.orphaned,
           claimsSuperseded: report.claims.superseded,
-          warnings: [...stopped.warnings, ...supersededClaimWarnings(report.claims.superseded)],
+          warnings: [
+            ...stopped.warnings,
+            ...supersededClaimWarnings(report.claims.superseded),
+            ...orphanedClaimWarnings(report.claims.orphaned),
+          ],
         }
       : stopped;
   }
@@ -71,6 +75,17 @@ function supersededClaimWarnings(superseded: DaemonStopResult['claimsSuperseded'
   ];
 }
 
+/** An orphaned claim keeps holding its device after the daemon is gone, and
+ * only `device release --stale` or the next open settles it — say so instead
+ * of leaving the block discoverable through --json alone. */
+function orphanedClaimWarnings(orphaned: DaemonStopResult['claimsOrphaned']): string[] {
+  if (orphaned.length === 0) return [];
+  const devices = orphaned.map((claim) => claim.deviceId).join(', ');
+  return [
+    `Ownership of ${devices} was not released cleanly; the claim now blocks other owners until it is settled. Inspect with: agent-device device status --stale, then release with: agent-device device release --stale.`,
+  ];
+}
+
 function renderDaemonStop(
   result: Pick<DaemonStopResult, 'stopped' | 'mode' | 'warnings'> & {
     clean: boolean;

src/cli/commands/device-release.ts

@@ -0,0 +1,51 @@
+import { SessionStore } from '../../daemon/session-store.ts';
+import { resolveDaemonPaths } from '../../daemon/config.ts';
+import { createDeviceClaimReconciler } from '../../daemon/device-claim-reconciliation.ts';
+import { createDaemonRecoveryPlatformScope } from '../../daemon/platform-request-scope.ts';
+import {
+  releaseProvenStaleDeviceClaims,
+  type DeviceClaimStaleReleaseOutcome,
+} from '../../daemon/device-claims.ts';
+import type { DeviceClaimSelectors } from '../../daemon/device-claim-inspection.ts';
+import { createPlatformRuntimeGateway } from '../../platform-runtime.ts';
+import { createOwnedProcessRecordStore } from '@agent-device/host-kit/process';
+
+/**
+ * Daemonless `device release --stale`: composes the same local platform
+ * gateway and reconciliation transaction the daemon uses at `open` and
+ * startup, so resources are settled through their exact-owner recovery paths
+ * before the claim is cleared — without requiring the (typically dead) owner
+ * daemon, or any daemon, to be running.
+ */
+export async function runStaleDeviceClaimRelease(
+  selectors: DeviceClaimSelectors,
+): Promise<DeviceClaimStaleReleaseOutcome[]> {
+  const daemonPaths = resolveDaemonPaths(process.env.AGENT_DEVICE_STATE_DIR);
+  const sessionStore = new SessionStore(daemonPaths.sessionsDir);
+  const ownedProcesses = createOwnedProcessRecordStore({
+    stateDir: daemonPaths.baseDir,
+    sessionsDir: daemonPaths.sessionsDir,
+    resolveSessionDir: (sessionId) => sessionStore.resolveSessionDir(sessionId),
+  });
+  // Local-only gateway: claims exist only for local devices, so provider
+  // runtimes stay out of the composition entirely.
+  const gateway = createPlatformRuntimeGateway({
+    sessionsDir: daemonPaths.sessionsDir,
+    ownedProcesses,
+    resolveSessionArtifacts: (sessionId) => ({
+      outputPath: sessionStore.resolveAppLogPath(sessionId),
+      pidPath: sessionStore.resolveAppLogPidPath(sessionId),
+    }),
+  });
+  try {
+    return await releaseProvenStaleDeviceClaims({
+      selectors,
+      reconcile: createDeviceClaimReconciler({
+        gateway,
+        scope: createDaemonRecoveryPlatformScope(),
+      }),
+    });
+  } finally {
+    await gateway.shutdown();
+  }
+}