Android delivery: target the app package explicitly so `am start` can never show a chooser

[V3RON]

Problem

appduct link --open android and the MCP appduct_connect tool deliver the bootstrap link with an implicit intent (packages/appduct/src/cli/open-target.ts, deliverAndroid):

adb shell am start -a android.intent.action.VIEW -d '<scheme>:///?appduct=...'

No package or component is named. Android resolves the intent by scheme alone, so whenever more than one installed app declares that scheme, the OS shows the "Open with" disambiguation dialog instead of opening the app. At that point the session is never claimed and appduct_wait_for_session blocks for its whole timeout, with nothing telling the agent why. This is the same class of failure as the iOS "Open in App?" alert, and defeats the point of the agent path, which exists so no one has to tap on the device.

This is not exotic. Typical ways to end up with two matching apps on one emulator:

• Product flavors with applicationIdSuffix (com.example.app and com.example.app.dev) that share one manifestPlaceholders["appductScheme"] / expo.scheme.
• A released build and a debug build of the same app installed side by side.
• Two projects that both picked a generic scheme name.

Proposal

Pass the application id to am start so resolution is explicit:

adb shell am start -a android.intent.action.VIEW -d '<link>' -p <applicationId>

-p limits resolution to that package, so the chooser cannot appear, and a missing package fails loudly ("Activity not started, unable to resolve Intent") rather than hanging the wait. The CLI already reads project files statically to find the scheme (native-scheme.ts reads app/build.gradle for manifestPlaceholders, and app.json for Expo), so applicationId from the same Gradle file, or android.package from app.json, can be resolved the same way, with a --package flag / package argument as the override, mirroring how --scheme works today. If no application id can be resolved, keep today's implicit intent so nothing regresses.

Out of scope for this issue, and only worth considering later: a debug-only exported BroadcastReceiver so delivery needs no activity at all. The -p change is enough to close the chooser gap.

Notes

• usesLoopbackAddress and the adb reverse step are unaffected.
• The ios-device path already takes a bundleId and validates its shape (letters, digits, ., -); the same validation applies to an Android application id.

[V3RON]

Agreed approach

Confirmed the problem and settled the design. Summary of what we're implementing, and why it differs from the proposal in the issue body.

The gap is real, and the failure is silent

deliverAndroid emits am start -a android.intent.action.VIEW -d '<link>' with no package. When two installed apps declare the scheme, the chooser appears, am start still exits 0, so delivery reports delivered: true and appduct_wait_for_session blocks its full timeout with nothing explaining why. Same failure signature as the ios-device loopback case that §8 already guards against.

Contract

Delivery to a target that resolves an app by identity requires the app's id. One per-invocation flag, one platform-keyed config block:

{
  "scheme": "myapp",
  "appId": { "ios": "com.example.MyApp", "android": "com.example.myapp" }
}

• --app-id <id> (CLI) / appId (MCP appduct_connect) — single, because the target is known at the call site.
• Project .appduct/config.json → appId.<platform>, via the existing walk-up. Project file only; the state dir's global config.json gets nothing — one global value per machine is the problem Project-level setup: cordierite init, scheme auto-discovery, and a way to pass the scheme to cordierite mcp #29 fixed for scheme, and an app id is more app-specific than a scheme, not less.
• android → android, ios-device → ios. Not required for ios-sim (simctl openurl has no equivalent flag).
• Missing → usage error raised before minting, so nothing is stranded, naming appduct init --android-app-id … --ios-app-id …, --app-id, and the config path.

Android delivery becomes am start -a android.intent.action.VIEW -d '<link>' -p <appId>.

Decisions worth recording

Required, not optional-with-fallback. Falling back to today's implicit intent when no id resolves would leave the zero-argument appduct_connect path — the one the issue is actually about — exactly as broken as it is now. A loud, actionable error beats a silent 120s timeout; that is the same trade loopbackAddressMessage already makes.

No static discovery of the id. Reading applicationId out of build.gradle looked attractive but carries the failure mode the issue opens with: a project using applicationIdSuffix resolves the base id, and -p then targets an app that either isn't installed (loud) or is the wrong flavor declaring the same scheme (silent, and worse than the chooser). Guarding that needs flavor heuristics and "sources disagree" rules — more machinery than a committed config line. A project .appduct/config.json is per-project by construction and gets the team, CI, and the agent path in one edit.

Config is per-platform, the flag is not. Android forbids - and is conventionally lowercase, so com.example.MyApp / com.example.myapp divergence is real; a single config value would feed the wrong id to one platform. A flag doesn't have that problem because the target is known when it is typed.

One shape check for both platforms. The existing BUNDLE_ID_PATTERN already does the job and gains a second caller. It is a safety check, not a grammar check: the value reaches both a devicectl trailing positional (where a leading - reads as an option) and a string that adb shell re-parses on the device's own shell (where a space or ; is injection — the same reason §8 single-quotes the URL). A syntactically wrong id fails loudly at am start.

am start output is checked. am does not reliably exit non-zero, so output matching /^Error:/m is turned into a thrown usage error. Without this, an unresolvable -p reproduces the very silent hang being fixed.

Shipping as a breaking change

1. --open android, and Android delivery via appduct_connect, now require an app id.
2. --bundle-id, MCP/client bundleId and config.json's iosBundleId are removed rather than aliased. Note that loadConfig's warn defaults to a no-op, so a leftover iosBundleId produces no output at all — the delivery-time error is the only signal, which is why it names the migration verbatim.
3. Migration is one command: appduct init --scheme myapp --android-app-id com.example.myapp --ios-app-id com.example.MyApp (init gains both flags).

Explicitly out of scope: static discovery, any state-dir config key, --ios-app-id/--android-app-id on appduct mcp (the per-call appId is the escape hatch when the server's cwd isn't the app root), and the debug-only BroadcastReceiver this issue already defers.

Implementation is underway; PR to follow.

---

Generated by Claude Code