Merge remote-tracking branch 'origin/main' into claude/limrun-scoped-token-attach-c41aff

* commit 'd396f3b509d9ed7cddaf170351ea6cf34e02ac16':
  fix(provider-webdriver): harden BrowserStack app references and endpoints (#3169)
  fix(android): back off a timed-out snapshot helper session and bound content re-captures (#3160)
  fix: centralize confirmed daemon retirement (#3126)
  fix: bind daemon registration writes to the acquired owner (#3125)
  fix: return confirmed daemon termination outcomes (#3124)
  refactor(move): share daemon registration and shutdown report modules (#3123)
  fix: preserve process lock exclusion across publication and reclaim (#3122)
  fix(cli): refuse a non-URL install-from-source source up front (#3166)
  fix(daemon): start a lease's TTL when its allocation completes (#3165)
  fix(android): fail doctor when adb is the Windows binary on a POSIX host (#3157)
  0.21.20
  0.21.19

# Conflicts:
#	src/daemon/server/daemon-runtime-metadata-ownership.test.ts

Author: thymikee

CONTRIBUTING.md

@@ -37,6 +37,11 @@ pnpm test-app:typecheck
 `pnpm build` compiles the TypeScript CLI and library. If a running development daemon must pick up
 that build, use `pnpm rebuild:cli`; it builds and then stops the worktree-scoped daemon.
 
+`pnpm clean:daemon` retains state when it cannot confirm the recorded daemon exited. Restore
+process inspection or stop the verified owner before retrying. Its `--prune-dev` option considers
+dev state directories whose newest observed modification is at least 14 days old. It retires
+confirmed abandoned registrations and keeps session artifacts and state directories for inspection.
+
 Build only the Apple runner target you changed:
 
 ```bash

docs/adr/0007-remote-device-leases.md

@@ -67,6 +67,16 @@ one minute, while a cloud WebDriver connection profile asks for ten. A single co
 longer than its own lease is therefore ordinary on the default and only reachable through a profile
 on the longer one.
 
+## Provider allocation
+
+Allocation is admitted work too. The registry records a lease before a hosted provider creates the
+session behind it, and creating that session can take longer than the lease's inactivity TTL, so a
+lease timed from its record was already expired, or nearly so, when its client first received it, and
+the paid session it pointed at was orphaned. The allocation therefore holds a work pass while the
+provider allocates: the lease cannot expire underneath it, and a successful allocation still wanted by
+its requester starts the inactivity TTL from the moment allocation completed. A requester that hung up
+preserves nothing, and its allocation is released as before.
+
 ## Client-side work that precedes admission
 
 Protecting admitted work covers nothing that happens before a request is admitted. Installing an

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

@@ -0,0 +1,45 @@
+# Process lock exclusion
+
+## Status
+
+Accepted for the hardened host-kit protocol. Mixed access with the legacy host-kit protocol
+is unsupported.
+
+## Rules at a glance
+
+- Publication, reclaim and release hold the same non-expiring mutation guard.
+- The guard covers only filesystem compare-and-mutate steps. Owner liveness is judged before
+  the guard is taken; under it, a reclaim only confirms that the record it judged is unchanged.
+- Release waits a bounded time for a held guard. A guard still held after that bound leaves the
+  release unverified, as an unprovable owner record or a directory it cannot remove also does.
+- A claim identifies an acquisition; a PID alone cannot authorize release.
+- Unknown owners and abandoned guards remain retained. Age never proves abandonment.
+- Before upgrading, stop every legacy process using the shared state or cache paths. Keep
+  legacy versions from returning while hardened users operate those paths. Use a single
+  deployed version or separate environments; deleting a lock is not an upgrade procedure.
+- Manual guard recovery requires external confirmation that every user of its paths stopped.
+
+The implementation and its executable invariants live in
+[`process-lock.ts`](../../packages/host-kit/src/internal/process-lock.ts) and its sibling tests.
+
+## Why the guard does not expire
+
+A process can pause after creating a directory or verifying a dead claim. Expiring its guard
+lets another process enter, then the first process resumes and overwrites or deletes the
+replacement. Retaining an uncertain guard trades automatic crash recovery for exclusion.
+
+The guard is an exclusive file at the existing guard path. Legacy age-based `rmdir` cannot
+remove it, so a fresh legacy reclaimer cannot steal a hardened publisher's guard. This does
+not revoke a legacy reclaimer admitted before cutover: another legacy process may already
+have stolen its directory guard. A real paused-child experiment reproduced both protocols
+returning acquired after that older reclaimer resumed. Quiescence must cover all legacy
+users, and continued mixed access remains unsupported.
+
+A different lock path would split exclusion. A version check, an owner re-read or a new
+guard cannot constrain legacy code after its final check. The support boundary therefore
+requires deployment control; host-kit does not claim to detect or evict every legacy user.
+
+Daemon registration has a separate cutover boundary: keep the same `daemon.lock` path and
+refuse legacy files rather than automatically reclaiming them. Its startup tests must cover
+an already-running older daemon and concurrent old/new startup. This does not expand the
+host-kit mixed-protocol support contract.

docs/adr/README.md

@@ -31,6 +31,7 @@
 | [0027 Descriptor Root Size vs Eager-Closure Budget (Proposed)](0027-descriptor-root-vs-eager-closure-budget.md) | splitting `packages/command-registry/src/registry.ts`, the ADR-0019 eager-closure module-count budget, and why a byte-neutral hub split is currently unshippable |
 | [0028 Capability-Family Cell Vocabulary — One Runtime Source (Proposed)](0028-capability-family-cell-vocabulary.md) | adding a capability operation family, `UnavailablePlatformRuntimeFacts` / `UNAVAILABLE_CELLS`, `INTERACTOR_OPERATIONS`, and why an eight-package fan-out recurs |
 | [0029 Daemon Policy](0029-daemon-policy.md) | `AGENT_DEVICE_DAEMON_POLICY`, confining a daemon's commands, devices, or device shutdown, and where operator rules are enforced for batch/replay steps |
+| [0030 Process Lock Exclusion](0030-process-lock-exclusion.md) | process-lock publication/reclaim/release, retained mutation guards, and the single-protocol upgrade boundary |
 
 ADRs record *why*; the registries and gates they describe are the living source of truth — when
 prose and a registry disagree, the registry wins and the ADR needs a follow-up.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.21.18",
+  "version": "0.21.20",
   "description": "Mobile app automation and verification for AI coding agents. CLI, MCP server, and typed Node.js API for iOS, Android, HarmonyOS, TV, web, macOS, and Linux.",
   "mcpName": "io.github.callstack/agent-device",
   "license": "MIT",

packages/capture-kit/src/recording/swift-cache.test.ts

@@ -98,10 +98,16 @@ test('extra source paths participate in the cache key and reach the compiler', a
   expect(compiledPaths).toContainEqual(['swiftc', sourcePath, changedSupportPath]);
 });
 
-test('stale cache locks are removed before compiling', async () => {
+test('cache locks with a proven dead owner are recovered before compiling', async () => {
   const { sourcePath, executablePath, lockDir } = await createBlockedCacheEntry();
-  const staleTime = new Date(Date.now() - 1_000);
-  fs.utimesSync(lockDir, staleTime, staleTime);
+  fs.writeFileSync(
+    path.join(lockDir, 'owner.json'),
+    JSON.stringify({
+      pid: 999_999_999,
+      startTime: null,
+      acquiredAtMs: Date.now(),
+    }),
+  );
 
   await expect(
     compileSwiftSourceFile({
@@ -115,10 +121,10 @@ test('stale cache locks are removed before compiling', async () => {
   expect(mockRunCmd).toHaveBeenCalledTimes(1);
 });
 
-test('cache lock timeout reports the lock path', async () => {
+test('an ownerless cache lock is retained with verified-recovery guidance regardless of age', async () => {
   const { sourcePath, lockDir } = await createBlockedCacheEntry();
-  const futureTime = new Date(Date.now() + 60_000);
-  fs.utimesSync(lockDir, futureTime, futureTime);
+  const old = new Date(Date.now() - 60_000);
+  fs.utimesSync(lockDir, old, old);
 
   await expect(
     compileSwiftSourceFile({
@@ -132,11 +138,12 @@ test('cache lock timeout reports the lock path', async () => {
     details: {
       lockDir,
       timeoutMs: 1,
-      hint: expect.stringContaining(`remove "${lockDir}"`),
+      hint: expect.stringContaining('confirming all users of this state directory have stopped'),
     },
   });
 
   expect(mockRunCmd).not.toHaveBeenCalled();
+  expect(fs.existsSync(lockDir)).toBe(true);
 });
 
 test('compileSwiftSourceText resolves a cache name with a long interior dash run in sub-second time', async () => {
@@ -228,15 +235,18 @@ async function expectConcurrentCacheReuse(compile: () => Promise<string>): Promi
 
   const firstCompile = compile();
   await compileStarted;
-  const originalMkdirSync = fs.mkdirSync;
+  const originalReadFileSync = fs.readFileSync;
   const lockAttempted = new Promise<void>((resolve) => {
-    const mkdirSpy = vi.spyOn(fs, 'mkdirSync').mockImplementation((dirPath, options) => {
-      if (typeof dirPath === 'string' && dirPath.endsWith('.lock')) {
+    const readSpy = vi.spyOn(fs, 'readFileSync').mockImplementation(((
+      filePath: fs.PathOrFileDescriptor,
+      options?: Parameters<typeof fs.readFileSync>[1],
+    ) => {
+      if (typeof filePath === 'string' && filePath.endsWith(`.lock${path.sep}owner.json`)) {
         resolve();
-        mkdirSpy.mockRestore();
+        readSpy.mockRestore();
       }
-      return originalMkdirSync(dirPath, options);
-    });
+      return originalReadFileSync(filePath, options);
+    }) as typeof fs.readFileSync);
   });
   const secondCompile = compile();
 

packages/capture-kit/src/recording/swift-cache.ts

@@ -204,19 +204,14 @@ async function acquireSwiftCacheLock(
       },
       timeoutMs,
       pollMs: LOCK_RETRY_DELAY_MS,
-      ownerGraceMs: timeoutMs,
       description: `Swift cache lock: ${lockDir} (${timeoutMs}ms)`,
     });
   } catch (error) {
-    if (
-      error instanceof AppError &&
-      error.message.startsWith('Timed out waiting for Swift cache lock:')
-    ) {
+    if (error instanceof AppError && error.details?.reason === 'process_lock_timeout') {
       throw new AppError('COMMAND_FAILED', error.message, {
         ...error.details,
         lockDir,
         timeoutMs,
-        hint: `Another agent-device process may still be compiling this Swift helper. Retry shortly; if no agent-device process is active, remove "${lockDir}" and retry.`,
       });
     }
     throw error;

packages/contracts/src/app-deployment-runtime.ts

@@ -13,6 +13,11 @@ export type AppDeploymentSource =
 export type MaterializedAppSource = Readonly<{
   archivePath?: string;
   installablePath: string;
+  /**
+   * The single file a hosted provider uploads for this build, named by the materializer that knows
+   * its format. Absent when the installable is already that file or no such file exists.
+   */
+  uploadPath?: string;
   bundleId?: string;
   packageName?: string;
   appName?: string;

packages/host-kit/src/file.ts

@@ -14,7 +14,13 @@ export {
 export { expandUserHomePath, resolveUserPath } from './internal/path-resolution.ts';
 export {
   acquireProcessLock,
+  acquireProcessLockAcquisition,
+  tryAcquireProcessLock,
+  inspectProcessLock,
   withProcessLock,
+  type ProcessLockAcquisition,
+  type ProcessLockAttempt,
+  type ProcessLockInspection,
   type ProcessLockOwner,
   type ProcessLockRelease,
 } from './internal/process-lock.ts';

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

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+
+// Guard acquisition from c237027737bf4737e324adae2146ba63891152a3, before protocol hardening.
+export function holdLegacyReclaimMutex(mutexPath: string, abandonedAfterMs: number): boolean {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      fs.mkdirSync(mutexPath);
+      return true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      if (!clearAbandonedReclaimMutex(mutexPath, abandonedAfterMs)) return false;
+    }
+  }
+  return false;
+}
+
+function clearAbandonedReclaimMutex(mutexPath: string, abandonedAfterMs: number): boolean {
+  let stats: fs.Stats;
+  try {
+    stats = fs.statSync(mutexPath);
+  } catch {
+    return true;
+  }
+  if (Date.now() - stats.mtimeMs < abandonedAfterMs) return false;
+  try {
+    fs.rmdirSync(mutexPath);
+  } catch {}
+  return true;
+}