Merge remote-tracking branch 'origin/main' into claude/issue-2022-adversarial-review-x9d9x3

# Conflicts:
#	CHANGELOG.md

Author: thymikee

CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## Unreleased
 
+- Security (MCP/AI-SDK tool surface): the operator-owned endpoint and path inputs — `daemonBaseUrl`,
+  the Metro `proxyBaseUrl`, `stateDir`, `cwd`, `iosSimulatorDeviceSet`, `iosXctestrunFile`,
+  `iosXctestDerivedDataPath`, `iosXctestEnvDir` — follow the credential inputs off the
+  model-writable tool surface: no longer advertised, refused as explicit input with guidance, and
+  resolved from env/config only (a model-writable `daemonBaseUrl`/`proxyBaseUrl` would redirect the
+  env-resolved token to an arbitrary server). Dropping these plus the credential fields shrinks
+  `tools/list` by roughly half. CLI flags and the SDK client options are unchanged.
+- MCP tool descriptions now declare their enforced client timeout envelope (90s default, 180s
+  install, 300s+ lease allocation, unbounded only for the streaming `test` runner), sourced from
+  the descriptor registry's timeout policy so the declared number cannot drift from the enforced
+  one.
+- Security (MCP/AI-SDK tool surface): the shared command-tool executor now enforces the advertised
+  tool schema as an admission boundary — every raw `tools/call` argument must appear in the tool's
+  advertised (`additionalProperties: false`) schema, or it is refused before config/env resolution.
+  Hiding a key from `tools/list` alone was insufficient: the router forwards raw arguments verbatim
+  and the MCP config resolver read `config`/`remoteConfig` as CLI flags, so a model-supplied config
+  file could load `daemonBaseUrl`/`daemonAuthToken` and redirect the operator's token to an
+  arbitrary endpoint. Deny-by-default closes that, the operator keys, and any unknown key at once;
+  operator env/config defaults still resolve (they never arrive as tool input). Retired keys are
+  still admitted so their migration guidance answers.
+- Security (MCP/AI-SDK tool surface): `daemonAuthToken` and the Metro `bearerToken` are no longer
+  advertised as tool input properties, and an explicit value is refused with guidance instead of
+  being forwarded. Credentials are operator-owned: set `AGENT_DEVICE_DAEMON_AUTH_TOKEN` (or
+  `daemonAuthToken` in `~/.agent-device/config.json`) and `AGENT_DEVICE_METRO_BEARER_TOKEN` on the
+  process serving the tools. The model both reads untrusted app UI text and picks tool arguments,
+  so a model-writable credential parameter was a prompt-injection exfiltration path. CLI flags
+  (`--daemon-auth-token`, `--bearer-token`) and env/config resolution are unchanged.
+- Release hygiene: after `npm publish`, `release:mark-dev` moves `main` to the next patch with a
+  `-dev` prerelease marker so the version on `main` never equals a published version (registry
+  scanners diff the tool surface per version string, and a moving surface under a released number
+  reads as a republish). `release:prepare` refuses to publish while the `-dev` marker is in place.
 - Windows `--platform web` works again. `agent-device web setup` no longer fails with
   `npm not found in PATH`, and every web command — including `web doctor` — no longer fails with
   `spawn EINVAL`. npm and the managed `agent-browser` backend are now both launched as

CONTRIBUTING.md

@@ -72,6 +72,17 @@ when a running daemon needs to pick up a new TypeScript build.
 `pnpm package:npm` is a release guard, not a routine development command. Use the specific commands
 above while iterating.
 
+### The version on main never equals a published version
+
+`release:publish` runs `release:mark-dev` right after `npm publish`, moving `package.json` (and the
+synchronized `server.json`) to the next patch with a `-dev` prerelease marker (for example
+`0.20.11-dev`). Commit that bump as part of the release. The invariant it protects: MCP registry
+scanners diff the repository's tool surface per version string, so a released number left on `main`
+while `main` keeps changing is indistinguishable from a republished ("rug-pull") version.
+`release:prepare` enforces the inverse direction and refuses to publish while the `-dev` marker is
+still in place — set the real release version first (for example `npm version patch`, which strips
+the prerelease marker), commit, then publish.
+
 ### Released-surface baselines roll forward on publish
 
 Compatibility gates baseline against the last **released tag**, not against `main`, so publishing is

package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.20.10",
+  "version": "0.20.11-dev",
   "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",
@@ -109,8 +109,9 @@
     "build:macos-helper:clean": "node --experimental-strip-types scripts/swift-toolchain-tmpdir.ts swift package --package-path apple/macos-helper clean && pnpm build:macos-helper",
     "build:package": "pnpm build && pnpm build:xcuitest:ios && pnpm build:xcuitest:macos && pnpm build:xcuitest:tvos && pnpm build:xcuitest:visionos && pnpm build:macos-helper:clean && pnpm package:apple-runner:npm && pnpm build:android",
     "package:npm": "pnpm build:package && pnpm check:package",
-    "release:prepare": "rm -rf .tmp/release && pnpm check:mcp-metadata && pnpm build:package && pnpm check:package -- --pack-destination .tmp/release",
-    "release:publish": "pnpm release:prepare && npm publish --ignore-scripts .tmp/release/*.tgz",
+    "release:prepare": "node scripts/release-mark-dev.mjs --check-release-version && rm -rf .tmp/release && pnpm check:mcp-metadata && pnpm build:package && pnpm check:package -- --pack-destination .tmp/release",
+    "release:publish": "pnpm release:prepare && npm publish --ignore-scripts .tmp/release/*.tgz && pnpm release:mark-dev",
+    "release:mark-dev": "node scripts/release-mark-dev.mjs",
     "ad": "node bin/agent-device.mjs",
     "bench:help-conformance": "node scripts/help-conformance-bench.mjs",
     "maestro:conformance": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/maestro-conformance/format-generated-json.test.mjs packages/maestro/test/conformance/verify.test.ts packages/maestro/test/conformance/differential/engine-process.test.ts packages/maestro/test/conformance/differential/report-output.test.ts packages/maestro/test/conformance/differential/run.test.ts packages/maestro/test/conformance/differential/invariants.test.ts",

packages/contracts/src/client-app.ts

@@ -15,6 +15,26 @@ import type {
 } from './client-connection.ts';
 import type { AgentDeviceSessionDevice, StartupPerfSample } from './client-device-view.ts';
 
+export type DeviceSelectionReason =
+  | 'explicit-selector'
+  | 'existing-session'
+  | 'single-booted-local'
+  | 'single-bootable-local'
+  | 'single-app-installed-local'
+  | 'preferred-local'
+  | 'single-provider-device';
+
+export type DeviceSelectionSource = 'session' | 'local' | 'provider';
+
+/** Deterministic device-selection evidence shared by daemon responses and the published client. */
+export type DeviceSelectionMetadata = {
+  reason: DeviceSelectionReason;
+  source: DeviceSelectionSource;
+  candidateCount: number;
+  /** Whether this request booted a previously stopped local virtual target during open. */
+  bootOccurred: boolean;
+};
+
 export type AppInstallOptions = AgentDeviceRequestOverrides &
   AgentDeviceSelectionOptions & {
     app?: string;
@@ -73,6 +93,7 @@ export type AppOpenResult = {
   appId?: string;
   startup?: StartupPerfSample;
   runtime?: SessionRuntimeHints;
+  selection?: DeviceSelectionMetadata;
   device?: AgentDeviceSessionDevice;
   /**
    * Initial interactive snapshot captured immediately after an open that

packages/contracts/src/facades/client.ts

@@ -11,6 +11,9 @@ export type {
   AppOpenResult,
   AppPushOptions,
   AppTriggerEventOptions,
+  DeviceSelectionMetadata,
+  DeviceSelectionReason,
+  DeviceSelectionSource,
   MaterializationReleaseOptions,
   MaterializationReleaseResult,
 } from '../client-app.ts';

packages/kernel/src/device.ts

@@ -68,6 +68,15 @@ export type DeviceSelector = {
   serial?: string;
 };
 
+/** Device identity is narrower than platform/target filtering for precedence decisions. */
+export function hasExplicitDeviceIdentitySelector(
+  selector: Pick<DeviceSelector, 'deviceName' | 'udid' | 'serial'>,
+): boolean {
+  return [selector.deviceName, selector.udid, selector.serial].some(
+    (value) => typeof value === 'string' && value.trim().length > 0,
+  );
+}
+
 type DeviceSelectionContext = {
   simulatorSetPath?: string;
 };

scripts/__tests__/test-file-size-ratchet.test.ts

@@ -50,7 +50,7 @@ const PINNED_TEST_FILE_LINES: Readonly<Record<string, number>> = Object.freeze({
   'src/__tests__/cli-config.test.ts': 1282,
   'src/daemon/handlers/__tests__/find.test.ts': 1202,
   'src/platforms/apple/core/__tests__/perf.test.ts': 1222,
-  'src/mcp/__tests__/command-tools.test.ts': 1218,
+  'src/mcp/__tests__/command-tools.test.ts': 1216,
   'src/daemon/handlers/__tests__/session-replay-divergence.test.ts': 1137,
   'src/platforms/apple/core/__tests__/apps.test.ts': 1210,
   'src/daemon/handlers/__tests__/session-replay-repair-transaction.test.ts': 1208,

scripts/release-mark-dev.mjs

@@ -0,0 +1,67 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+// The version on main must never equal a published version: registry scanners
+// diff the repository's tool surface per version string, so a released number
+// left in place while main keeps moving reads as a rug-pull republish
+// (AS-012). `release:publish` runs this right after `npm publish` to move
+// main to the next patch with a `-dev` prerelease marker; `--check-release-version`
+// is the inverse guard in `release:prepare`, refusing to publish a `-dev`
+// version because the maintainer has not set the release version yet.
+const root = process.cwd();
+const checkReleaseVersion = process.argv.includes('--check-release-version');
+const packagePath = path.join(root, 'package.json');
+
+const raw = fs.readFileSync(packagePath, 'utf8');
+const pkg = JSON.parse(raw);
+const version = pkg.version;
+
+if (typeof version !== 'string' || version.length === 0) {
+  fail('package.json must define version.');
+}
+
+if (checkReleaseVersion) {
+  if (version.includes('-')) {
+    fail(
+      `package.json version ${version} is a prerelease marker. Set the release version first ` +
+        '(e.g. `npm version patch`), commit, then publish.',
+    );
+  }
+  process.exit(0);
+}
+
+if (version.includes('-')) {
+  process.stdout.write(`Version ${version} already carries a prerelease marker; nothing to do.\n`);
+  process.exit(0);
+}
+
+const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+if (!match) {
+  fail(`Unsupported version format: ${version}`);
+}
+const nextVersion = `${match[1]}.${match[2]}.${Number(match[3]) + 1}-dev`;
+
+const versionField = `"version": "${version}"`;
+if (raw.split(versionField).length !== 2) {
+  fail(`Expected exactly one ${versionField} in package.json.`);
+}
+fs.writeFileSync(packagePath, raw.replace(versionField, `"version": "${nextVersion}"`));
+
+const sync = spawnSync(process.execPath, [path.join(root, 'scripts', 'sync-mcp-metadata.mjs')], {
+  stdio: 'inherit',
+});
+if (sync.status !== 0) {
+  fail('sync-mcp-metadata failed after the version bump.');
+}
+
+process.stdout.write(
+  `Marked main as unreleased: ${version} -> ${nextVersion} (package.json + server.json).\n` +
+    `Commit and push this so the version on main never equals the published ${version}.\n`,
+);
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}

server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/callstack/agent-device",
     "source": "github"
   },
-  "version": "0.20.10",
+  "version": "0.20.11-dev",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "agent-device",
-      "version": "0.20.10",
+      "version": "0.20.11-dev",
       "transport": {
         "type": "stdio"
       }

src/__tests__/cli-help.test.ts

@@ -82,6 +82,9 @@ test('help workflow prints the compact workflow card with a version header and s
   assert.match(result.stdout, /no CSS selectors/);
   assert.match(result.stdout, /help scripting/);
   assert.match(result.stdout, /help gestures/);
+  assert.match(result.stdout, /Selection: explicit --device\/--udid\/--serial/);
+  assert.match(result.stdout, /--platform\/--target only filter/);
+  assert.match(result.stdout, /bounded retry selectors/);
 });
 
 test('help workflow encourages chaining confident steps and requires the end state to be on screen', async () => {
@@ -141,7 +144,7 @@ test('help workflow advertises open --foreground and snapshot -i --actions', asy
   assert.equal(result.calls.length, 0);
   assert.match(
     result.stdout,
-    /Known app: open <app> --foreground -> snapshot\. Bare form needs one running app on one iOS sim; capture failure keeps session open/,
+    /open --foreground -> snapshot\. Selection: explicit --device\/--udid\/--serial/,
   );
   assert.match(
     result.stdout,