feat: add daemon stop lifecycle (#1323)

* feat: add daemon stop lifecycle

* fix: harden daemon stop cleanup

* fix: fail closed daemon stop cleanup

* fix: bound daemon shutdown lease releases

* fix: await active shutdown lease release

* fix: release provider leases independently on shutdown

Author: thymikee

scripts/integration-progress-model.ts

@@ -319,6 +319,11 @@ function summarizeProviderScenarioFlagExclusions() {
         'proxyPort',
       ],
     },
+    {
+      name: 'daemon lifecycle control',
+      owner: 'daemon CLI lifecycle tests',
+      keys: ['clean'],
+    },
     {
       name: 'platform boot fallback without provider seam',
       owner: 'handler and Android platform unit tests',

src/cli-schema/command-overrides.ts

@@ -29,6 +29,16 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = {
     positionalArgs: ['status|login|logout'],
     supportedFlags: ['remoteConfig', 'stateDir'],
   },
+  daemon: {
+    usageOverride: 'daemon stop [--state-dir <path>] [--clean]',
+    listUsageOverride: 'daemon stop',
+    helpDescription:
+      'Stop a local daemon after verifying its PID/start-time identity. Use --clean to remove retained Apple runner processes and leases owned by that daemon.',
+    summary: 'Safely stop a local daemon and optionally clean retained runner resources',
+    positionalArgs: ['stop'],
+    allowedFlags: ['clean'],
+    supportedFlags: ['stateDir'],
+  },
   connect: {
     usageOverride:
       'connect [cloud|proxy|limrun|browserstack|aws-device-farm] [--remote-config <path>] [--daemon-base-url <url>] [--tenant <id>] [--run-id <id>] [--lease-id <id>] [--lease-backend <backend>] [--force] [--no-login]',

src/cli.ts

@@ -75,6 +75,7 @@ const REMOTE_MATERIALIZATION_DEFERRED_COMMANDS = new Set([
   'connect',
   'connection',
   'close',
+  'daemon',
   'disconnect',
   'metro',
   'proxy',
@@ -554,6 +555,7 @@ function resolveActiveConnectionDefaults(options: {
   if (
     options.command === 'connect' ||
     options.command === 'connection' ||
+    options.command === 'daemon' ||
     options.command === 'proxy'
   ) {
     return null;
@@ -577,7 +579,9 @@ function shouldMaterializeRemoteConnection(command: string): boolean {
 }
 
 function shouldResolveRemoteAuth(command: string): boolean {
-  return command !== 'auth' && command !== 'connection' && command !== 'proxy';
+  return (
+    command !== 'auth' && command !== 'connection' && command !== 'daemon' && command !== 'proxy'
+  );
 }
 
 function shouldWarnOpenMayMissRemoteRuntime(options: {

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

@@ -0,0 +1,133 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, expect, test, vi } from 'vitest';
+import type { DaemonStopResult } from '../../../daemon/daemon-stop.ts';
+
+const mocks = vi.hoisted(() => ({
+  cleanupRunnerLeasesForOwner: vi.fn(async () => undefined),
+  readDaemonShutdownReport: vi.fn(),
+  readDaemonStopIdentity: vi.fn(),
+  stopDaemon: vi.fn(),
+  writeCommandOutput: vi.fn(),
+}));
+
+vi.mock('../../../daemon/daemon-stop.ts', () => ({
+  readDaemonStopIdentity: mocks.readDaemonStopIdentity,
+  stopDaemon: mocks.stopDaemon,
+}));
+vi.mock('../../../daemon/daemon-shutdown-report.ts', () => ({
+  readDaemonShutdownReport: mocks.readDaemonShutdownReport,
+}));
+vi.mock('../../../platforms/apple/core/runner/runner-lease.ts', () => ({
+  cleanupRunnerLeasesForOwner: mocks.cleanupRunnerLeasesForOwner,
+}));
+vi.mock('../../../platforms/apple/core/runner/runner-disposal.ts', () => ({
+  runnerLeaseCleanupAdapter: {},
+}));
+vi.mock('../shared.ts', () => ({ writeCommandOutput: mocks.writeCommandOutput }));
+
+import { daemonCommand } from '../daemon.ts';
+
+const GRACEFUL_RESULT: DaemonStopResult = {
+  stopped: true,
+  mode: 'graceful',
+  cleanupConfidence: 'known',
+  claimsReleased: [],
+  claimsOrphaned: [],
+  providerReleases: { status: 'completed', released: [], pending: [] },
+  warnings: [],
+};
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+test('accepts only daemon stop', async () => {
+  await assert.rejects(
+    async () =>
+      await daemonCommand({
+        positionals: [],
+        flags: { help: false, json: false, version: false },
+        client: {} as never,
+      }),
+    (error: { code?: string }) => error.code === 'INVALID_ARGS',
+  );
+  await assert.rejects(
+    async () =>
+      await daemonCommand({
+        positionals: ['stop', 'extra'],
+        flags: { help: false, json: false, version: false },
+        client: {} as never,
+      }),
+    (error: { code?: string }) => error.code === 'INVALID_ARGS',
+  );
+});
+
+test('merges a graceful shutdown report and cleans runner leases with the start-time identity', async () => {
+  const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-daemon-command-'));
+  mocks.readDaemonStopIdentity.mockReturnValue({ pid: 123, processStartTime: 'start-time' });
+  mocks.stopDaemon.mockResolvedValue(GRACEFUL_RESULT);
+  mocks.readDaemonShutdownReport.mockReturnValue({
+    providerReleases: {
+      released: [{ leaseId: 'lease-1', provider: 'limrun' }],
+      pending: [],
+    },
+  });
+
+  try {
+    await daemonCommand({
+      positionals: ['stop'],
+      flags: { clean: true, help: false, json: false, stateDir, version: false },
+      client: {} as never,
+    });
+
+    expect(mocks.cleanupRunnerLeasesForOwner).toHaveBeenCalledWith(
+      { pid: 123, startTime: 'start-time' },
+      {},
+    );
+    expect(mocks.writeCommandOutput).toHaveBeenCalledWith(
+      expect.objectContaining({ clean: true, json: false }),
+      expect.objectContaining({
+        clean: true,
+        providerReleases: {
+          status: 'completed',
+          released: [{ leaseId: 'lease-1', provider: 'limrun' }],
+          pending: [],
+        },
+      }),
+      expect.any(Function),
+    );
+  } finally {
+    fs.rmSync(stateDir, { recursive: true, force: true });
+  }
+});
+
+test('reports graceful provider cleanup as unknown when the shutdown report is unavailable', async () => {
+  const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-daemon-command-'));
+  mocks.readDaemonStopIdentity.mockReturnValue(null);
+  mocks.stopDaemon.mockResolvedValue(GRACEFUL_RESULT);
+  mocks.readDaemonShutdownReport.mockReturnValue(null);
+
+  try {
+    await daemonCommand({
+      positionals: ['stop'],
+      flags: { help: false, json: false, stateDir, version: false },
+      client: {} as never,
+    });
+
+    expect(mocks.writeCommandOutput).toHaveBeenCalledWith(
+      expect.objectContaining({ json: false }),
+      expect.objectContaining({
+        clean: false,
+        cleanupConfidence: 'unknown',
+        providerReleases: { status: 'unknown', released: [], pending: null },
+        warnings: [expect.stringContaining('provider cleanup state is unknown')],
+      }),
+      expect.any(Function),
+    );
+  } finally {
+    fs.rmSync(stateDir, { recursive: true, force: true });
+  }
+});

src/cli/commands/daemon.ts

@@ -0,0 +1,67 @@
+import { resolveDaemonPaths } from '../../daemon/config.ts';
+import {
+  readDaemonStopIdentity,
+  stopDaemon,
+  type DaemonStopResult,
+} from '../../daemon/daemon-stop.ts';
+import { readDaemonShutdownReport } from '../../daemon/daemon-shutdown-report.ts';
+import { AppError } from '../../kernel/errors.ts';
+import { writeCommandOutput } from './shared.ts';
+import type { ClientCommandHandler } from './router-types.ts';
+
+export const daemonCommand: ClientCommandHandler = async ({ positionals, flags }) => {
+  const subcommand = positionals[0];
+  if (subcommand !== 'stop' || positionals.length !== 1) {
+    throw new AppError('INVALID_ARGS', 'daemon accepts only: stop');
+  }
+  const paths = resolveDaemonPaths(flags.stateDir);
+  const identity = readDaemonStopIdentity(paths.infoPath);
+  const stopped = await stopDaemon({ paths });
+  const report = stopped.mode === 'graceful' ? readDaemonShutdownReport(paths.baseDir) : null;
+  const result = mergeShutdownReport(stopped, report);
+  const shouldClean = flags.clean === true && identity !== null && result.stopped;
+  if (shouldClean) {
+    const [{ cleanupRunnerLeasesForOwner }, { runnerLeaseCleanupAdapter }] = await Promise.all([
+      import('../../platforms/apple/core/runner/runner-lease.ts'),
+      import('../../platforms/apple/core/runner/runner-disposal.ts'),
+    ]);
+    await cleanupRunnerLeasesForOwner(
+      { pid: identity.pid, startTime: identity.processStartTime },
+      runnerLeaseCleanupAdapter,
+    );
+  }
+  const data = { ...result, clean: shouldClean };
+  writeCommandOutput(flags, data, () => renderDaemonStop(data));
+  return true;
+};
+
+function mergeShutdownReport(
+  stopped: DaemonStopResult,
+  report: ReturnType<typeof readDaemonShutdownReport>,
+): DaemonStopResult {
+  if (stopped.mode !== 'graceful' || report) {
+    return report
+      ? { ...stopped, providerReleases: { status: 'completed', ...report.providerReleases } }
+      : stopped;
+  }
+  return {
+    ...stopped,
+    cleanupConfidence: 'unknown',
+    providerReleases: { status: 'unknown', released: [], pending: null },
+    warnings: [
+      ...stopped.warnings,
+      'The graceful shutdown report is unavailable, so provider cleanup state is unknown. Provider allocations may remain active.',
+    ],
+  };
+}
+
+function renderDaemonStop(
+  result: Pick<DaemonStopResult, 'stopped' | 'mode' | 'warnings'> & {
+    clean: boolean;
+  },
+): string {
+  const headline = result.stopped ? `Daemon stopped (${result.mode}).` : 'No running daemon found.';
+  return [headline, result.clean ? 'Retained runner cleanup completed.' : null, ...result.warnings]
+    .filter((line): line is string => Boolean(line))
+    .join('\n');
+}

src/cli/commands/router.ts

@@ -3,6 +3,7 @@ import type { AgentDeviceClient } from '../../agent-device-client.ts';
 import { isClientBackedCliCommandName, type ClientBackedCliCommandName } from './client-backed.ts';
 import { connectCommand, connectionCommand, disconnectCommand } from './connection.ts';
 import { authCommand } from './auth.ts';
+import { daemonCommand } from './daemon.ts';
 import { proxyCommand } from './proxy.ts';
 import { replayCommand } from './replay.ts';
 import { screenshotCommand, diffCommand } from './screenshot.ts';
@@ -19,6 +20,7 @@ const dedicatedCliCommandHandlers = {
   disconnect: disconnectCommand,
   connection: connectionCommand,
   auth: authCommand,
+  daemon: daemonCommand,
   proxy: proxyCommand,
   replay: replayCommand,
   screenshot: screenshotCommand,

src/commands/cli-grammar/flag-definitions-connection.ts

@@ -201,6 +201,13 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     usageDescription:
       'Force replacement of existing state (connect: replace an active connection; --save-script: overwrite an existing target instead of refusing)',
   },
+  {
+    key: 'clean',
+    names: ['--clean'],
+    type: 'boolean',
+    usageLabel: '--clean',
+    usageDescription: 'Daemon stop: remove retained runner processes and leases after stopping',
+  },
   {
     key: 'noLogin',
     names: ['--no-login'],

src/contracts/cli-flags.ts

@@ -42,6 +42,7 @@ export type CliFlags = CloudProviderProfileFields &
     provider?: string;
     providerSessionId?: string;
     force?: boolean;
+    clean?: boolean;
     noLogin?: boolean;
     kind?: string;
     perfTemplate?: string;

src/core/command-descriptor/registry.ts

@@ -1075,6 +1075,15 @@ export const RAW_COMMAND_DESCRIPTORS = [
     timeoutPolicy: DEFAULT_TIMEOUT_POLICY,
     batchable: false,
   },
+  {
+    name: 'daemon',
+    ...(ownerFilesEnabled ? { ownerFiles: ['src/cli/commands/daemon.ts'] as const } : {}),
+    catalog: { group: 'local-cli' },
+    recordsSessionAction: false,
+    timeoutPolicy: DEFAULT_TIMEOUT_POLICY,
+    batchable: false,
+    mcpExposed: false,
+  },
   {
     name: 'metro',
     ...(ownerFilesEnabled ? { ownerFiles: ['src/commands/metro/index.ts'] as const } : {}),

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

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { expect, test } from 'vitest';
+import {
+  clearDaemonShutdownReport,
+  readDaemonShutdownReport,
+  writeDaemonShutdownReport,
+} from '../daemon-shutdown-report.ts';
+import { LeaseRegistry } from '../lease-registry.ts';
+
+test('round-trips provider release records without persisting lease credentials', () => {
+  const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-shutdown-report-'));
+  const lease = new LeaseRegistry().allocateLease({
+    tenantId: 'tenant-a',
+    runId: 'run-1',
+    leaseProvider: 'limrun',
+  });
+
+  try {
+    writeDaemonShutdownReport(stateDir, { released: [lease], pending: [lease] });
+
+    expect(readDaemonShutdownReport(stateDir)).toEqual({
+      providerReleases: {
+        released: [{ leaseId: lease.leaseId, provider: 'limrun' }],
+        pending: [{ leaseId: lease.leaseId, provider: 'limrun' }],
+      },
+    });
+  } finally {
+    fs.rmSync(stateDir, { recursive: true, force: true });
+  }
+});
+
+test('ignores malformed shutdown reports and clear removes a prior report', () => {
+  const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-shutdown-report-'));
+  const reportPath = path.join(stateDir, 'daemon-shutdown.json');
+
+  try {
+    expect(readDaemonShutdownReport(stateDir)).toBeNull();
+    fs.writeFileSync(reportPath, JSON.stringify({ providerReleases: { released: [] } }));
+    expect(readDaemonShutdownReport(stateDir)).toBeNull();
+
+    fs.writeFileSync(
+      reportPath,
+      JSON.stringify({ providerReleases: { released: [{}], pending: [] } }),
+    );
+    expect(readDaemonShutdownReport(stateDir)).toBeNull();
+
+    clearDaemonShutdownReport(stateDir);
+    expect(fs.existsSync(reportPath)).toBe(false);
+  } finally {
+    fs.rmSync(stateDir, { recursive: true, force: true });
+  }
+});