appduct 0.13.0 → 0.15.0

package/README.md

@@ -1,6 +1,6 @@
 [![Appduct][appduct-banner]][repo]
 
-### Drive app tools without shipping debug UI
+### Call functions in your running iOS, Android, React Native, Flutter or web app from a terminal, a test or an agent
 
 [![MIT license][license-badge]][license] [![npm downloads][npm-downloads-badge]][npm-downloads] [![PRs Welcome][prs-welcome-badge]][prs-welcome]
 
@@ -8,19 +8,19 @@ The `appduct` package is the operator/agent side of Appduct: a CLI and an MCP se
 
 ## Why use this package
 
-- **One daemon, many devices.** It auto-spawns on first use, serves every device on one `wss://` port, and survives Metro reloads, backgrounding, and network flaps by suspending and resuming sessions instead of dying with them.
+- **One daemon, many devices.** It starts on first use and serves every connected iOS, Android and React Native app on one port. A session survives backgrounding, network drops and React Native reloads: it pauses while the app is away and resumes when it reconnects.
 - **Same surface for humans and agents.** The CLI (`sessions`, `tools`, `events`, ...) and `appduct mcp` use the same RPC methods, so an agent sees the tools a human operator does.
-- **Hardened control plane.** The CLI and MCP server never touch sockets, keys, or state files directly — everything goes through a Unix-domain-socket RPC surface gated by filesystem permissions (see [`docs/SECURITY.md`][security]).
+- **Local to your user account.** The CLI and MCP server reach the daemon through a local socket only your user account can open, and the daemon's key and logs are readable only by you (see [Security][security]).
 - **Fits production-minded apps.** The app only exposes what you register; trust boundaries are pins and TLS, and production deployments can gate tools with policy and audit every call.
 
 ## Getting started
 
 ```bash
 npm install -g appduct
-appduct sessions link --scheme myapp --qr
+appduct sessions link --qr
 ```
 
-`sessions link` needs your app's deep-link scheme: pass `--scheme` (the app's `expo.scheme`, or its bare-RN equivalent), or set `"scheme"` once in `~/.appduct/config.json` and omit the flag. Without either, the command exits with a usage error.
+`sessions link` needs your app's deep-link scheme. Run from your app's directory, it usually finds the scheme on its own, in `app.json` or the iOS and Android project files (see [The deep-link scheme](#the-deep-link-scheme)). `--scheme` overrides whatever it finds.
 
 Scan the QR (or open the deep link) in an Appduct-enabled app, then:
 
@@ -40,14 +40,15 @@ Every command is `appduct <noun> <verb> [selector] [args]`, the same shape as `a
 | `appduct init [--scheme <s>] [--ios-app-id <id>] [--android-app-id <id>] [--force]` | set up an app directory: write `.appduct/config.json`, print the MCP snippet |
 | `appduct keygen [--out <path>] [--force]` | generate a daemon private key, print its app pin |
 | `appduct sessions ls` | list sessions: alias, state, device, tool count |
-| `appduct sessions link [--ttl <s>] [--qr] [--open android\|ios-sim\|ios-device] [--device <id>] [--app-id <id>] [--scheme <s>]` | mint a pending session and print its deep link |
+| `appduct sessions link [--ttl <s>] [--qr] [--open android\|ios-sim\|ios-device] [--device <id>] [--app-id <id>] [--relaunch] [--scheme <s>]` | mint a pending session and print its deep link |
 | `appduct sessions revoke [selector]` | revoke a session |
 | `appduct tools ls [selector] [--full] [--group <name>] [--filter <text>] [--limit <n>] [--offset <n>]` | list a session's tools (one call signature + description per line) |
 | `appduct tools ls [selector] --groups` | list a session's tool groups with their tool counts |
 | `appduct tools describe [selector] <name>` | show one tool's full schema |
 | `appduct tools call [selector] <name> --input '<json>' [--timeout <ms>]` | call a tool |
-| `appduct events tail [selector] [--follow]` | stream the events the app posts with `postEvent`; `--json` emits NDJSON |
-| `appduct events since [selector] <cursor>` | one-shot pull the events retained since `<cursor>`; `--json` emits NDJSON |
+| `appduct events ls [selector] [--name <glob>] [--limit <n>] [--offset <n>]` | list the events the app declares, one signature line each; an exact `--name` prints the full payload schema; `--limit`/`--offset` page a long list, ending with a `Showing n of total events (offset o).` line when events were left out; `--json` carries the full descriptors, with `total` counting matches before paging |
+| `appduct events tail [selector] [--follow] [--name <glob>] [--payload-max-bytes <n>]` | stream the events the app posts with `postEvent`; `--name` keeps only matching names, `--payload-max-bytes` cuts each payload down to a preview; `--json` emits NDJSON |
+| `appduct events since [selector] <cursor> [--name <glob>] [--payload-max-bytes <n>]` | one-shot pull the events retained since `<cursor>`, with the same filters as `tail`; `--json` emits NDJSON |
 | `appduct daemon run\|start\|stop\|status` | daemon lifecycle |
 | `appduct mcp [--scheme <s>]` | start a stdio MCP server proxying connected apps' tools to MCP clients |
 | `appduct doctor <artifact> [--assert-present\|--assert-absent]` | release-gate step: report or assert whether a built `.app`/`.ipa`/`.apk`/`.aab` contains Appduct |
@@ -76,7 +77,7 @@ Use `--filter <text>` to narrow the listing to tools whose name or description c
 
 ### Tool groups
 
-When the app puts its tools in groups ([`docs/TOOLS.md`](../../docs/TOOLS.md#group-tools-in-a-large-app)), `appduct tools ls` lists them under group headings, with subgroups indented under their parent and ungrouped tools last:
+When the app puts its tools in groups ([Write tools](https://callstackincubator.github.io/appduct/guides/writing-tools/#group-tools-in-a-large-app)), `appduct tools ls` lists them under group headings, with subgroups indented under their parent and ungrouped tools last:
 
 ```
 Tools
@@ -125,13 +126,15 @@ $ appduct tools ls --group checkout
    3. **iOS**: any `Info.plist` up to two levels below the app root (excluding `Pods`, `build`, `node_modules`, `DerivedData`) for the first `CFBundleURLSchemes` entry, then xcodegen's `project.yml` for the same key under `info.properties.CFBundleURLTypes`
 6. otherwise an error naming every location above
 
+In a Flutter project root (a directory with a `pubspec.yaml`), the Android probes read `android/app/` instead of `app/`, and the iOS and macOS ones find `ios/Runner/Info.plist` and `macos/Runner/Info.plist`. `appduct init` there prints the Flutter setup steps instead of the React Native reminder.
+
 In an Expo app root, none of this needs configuring; a plain Xcode or Gradle app root doesn't either, once its `Info.plist`/`AndroidManifest.xml`/`build.gradle` already declares deep links. These probes never execute `app.config.js`/`app.config.ts`, `xcodebuild`, `plutil`, or a Gradle evaluation — each is a plain, defensively-parsed read of a static project file. If your project uses dynamic config, or the probes can't make sense of your setup, use `--scheme`, `APPDUCT_SCHEME`, or `appduct init --scheme <s>` instead.
 
 **Disagreement is never guessed away.** If more than one native probe resolves to a different scheme (say, an `android/` and an `ios/` tree in the same repo declaring different values), resolution fails with a usage error naming every conflicting source instead of picking one.
 
-`appduct init`, run in an app root, writes `.appduct/config.json` (mode `0600`, in a `0700` directory) with the discovered scheme and prints the MCP server entry to paste, plus the `import "@appduct/react-native/auto"` reminder. It never generates keys or touches daemon state.
+`appduct init`, run in an app root, writes `.appduct/config.json` (mode `0600`, in a `0700` directory) with the discovered scheme and prints the MCP server entry to paste, plus the wiring your app still needs: the `import "@appduct/react-native/auto"` reminder for a React Native or Expo app, or the step a plain iOS or Android app needs (`Appduct.shared.handle(url)`, or the `appductScheme` placeholder). A `react-native` or `expo` dependency in your `package.json` is what says this is a React Native app; running `init` from the app's `ios/` or `android/` directory finds that manifest where the native toolchain puts you. It never generates keys or touches daemon state.
 
-`init` only looks at `--scheme` and the static-file discovery in step 5 above (`app.json`, then the native probes), plus whatever the file already records — it deliberately ignores `APPDUCT_SCHEME` and does not walk up to a parent `.appduct/config.json`, since baking either into a committed file would be wrong (a shell variable that happened to be exported, or a parent project's scheme silently copied into a sub-package). `--json`'s `source` field reports which input won: `"--scheme"`, `"app.json"`, one of the four native-probe names (`"android-gradle"`, `"android-manifest"`, `"ios-info-plist"`, `"ios-project-yml"`), or `"already-recorded"`.
+`init` only looks at `--scheme` and the static-file discovery in step 5 above (`app.json`, then the native probes), plus whatever the file already records — it deliberately ignores `APPDUCT_SCHEME` and does not walk up to a parent `.appduct/config.json`, since baking either into a committed file would be wrong (a shell variable that happened to be exported, or a parent project's scheme silently copied into a sub-package). `--json`'s `source` field reports which input won: `"--scheme"`, `"app.json"`, one of the four native-probe names (`"android-gradle"`, `"android-manifest"`, `"ios-info-plist"`, `"ios-project-yml"`), or `"already-recorded"`. `platforms` lists every native platform discovery saw (`["android", "ios"]` for a root that spans both), on every run including `"already-recorded"` and `--scheme`, and is left out when it saw none; `init` prints the wiring step for each platform in it.
 
 It's idempotent and safe to re-run:
 
@@ -222,9 +225,9 @@ Your MCP client asks permission for `appduct_call_tool` as a single tool, so cho
 
 Set this before you connect: the daemon reads `config.json` only when it starts, so changing it later takes `appduct daemon stop`. That disconnects every device, which then has to link again, and leaves a running `appduct mcp` without a daemon, so restart the MCP server in your client as well.
 
-Four more built-in tools cover what the app's own tools can't. `appduct_connect` mints a link and, by default, delivers it to whichever `android`/`ios-sim` device it detects — pass `target`/`device` to choose, or `target: "none"` to force the human flow — falling back to a QR code, plus instructions to show it, only when there's nothing to deliver to. Delivering to `android` (chosen or detected) needs `appId`, resolved the same way as `--app-id` (see [Delivering the link to a device](#delivering-the-link-to-a-device)); passing it with `target: "ios-sim"` or `"none"` is an error. `appduct_wait_for_session` then waits for that session to be claimed. `target: "ios-device"` reaches a paired physical iPhone or iPad, with `appId` and the [prerequisites above](#--open-ios-device-experimental) — it's experimental and never auto-detected, so an agent has to ask for it by name.
+Five more built-in tools cover what the app's own tools can't. `appduct_connect` mints a link and, by default, delivers it to whichever `android`/`ios-sim` device it detects — pass `target`/`device` to choose, or `target: "none"` to force the human flow — falling back to a QR code, plus instructions to show it, only when there's nothing to deliver to. Delivering to `android` (chosen or detected) needs `appId`, resolved the same way as `--app-id` (see [Delivering the link to a device](#delivering-the-link-to-a-device)); passing it with `target: "ios-sim"` or `"none"` is an error. `appduct_wait_for_session` then waits for that session to be claimed. `target: "ios-device"` reaches a paired physical iPhone or iPad, with `appId` and the [prerequisites above](#--open-ios-device-experimental) — it's experimental and never auto-detected, so an agent has to ask for it by name.
 
-The other two give an agent a pull surface over `postEvent()`-pushed app events: `appduct_events` drains everything retained since a cursor, and `appduct_wait_for_event` blocks for the next event whose name matches `name`, a whole-name glob (`*` waits for any name) — checking what's already retained before waiting live — rejecting with `tool_timeout` if none arrives in time.
+The other three give an agent a pull surface over `postEvent()`-pushed app events. `appduct_list_events` lists the events the app declared (`appduct events ls`) as signatures with descriptions, plus the payload schema when `name` is an exact name, so an agent learns the names before it waits on one. `appduct_events` drains everything retained since a cursor, and `appduct_wait_for_event` blocks for the next event whose name matches `name`, a whole-name glob (`*` waits for any name) — checking what's already retained before waiting live — rejecting with `tool_timeout` if none arrives in time.
 
 ## Test runners: `appduct/client`
 
@@ -276,11 +279,11 @@ const next = await app.waitForEvent("checkout_done", { since: cursor });
 const capped = await app.waitForEvent("checkout_done", { payloadMaxBytes: 1024 }); // check `truncated` before reading `payload`
 ```
 
-For everything else, the package exports `runCli` and the command handlers from [`src/index.ts`](https://github.com/callstackincubator/appduct/blob/main/packages/appduct/src/index.ts), so you can embed the same behavior in Node or Bun scripts without shelling out.
+For anything the client doesn't cover, the package's main entry exports `runCli(argv, { stdout, stderr })`, which runs any `appduct` command in your Node or Bun process and resolves to its exit code.
 
 ## Keys and pins
 
-You can skip this entirely while your app has no `cliPins` configured — the zero-config default, in any build type. The daemon auto-generates its own `key.pem` the first time it starts if one isn't already there (mode `0600`) and prints its `sha256/...` fingerprint on that first run; `appduct sessions link` carries that fingerprint on the deep link for the app to pick up. See [`docs/SECURITY.md`][security]'s "Trust modes" for what that does and doesn't protect.
+You can skip this entirely while your app has no `cliPins` configured — the zero-config default, in any build type. The daemon auto-generates its own `key.pem` the first time it starts if one isn't already there (mode `0600`) and prints its `sha256/...` fingerprint on that first run; `appduct sessions link` carries that fingerprint on the deep link for the app to pick up. See [Security][security]'s "Trust modes" for what that does and doesn't protect.
 
 For a build that should trust only a key you embedded ahead of time, generate one explicitly:
 
@@ -290,33 +293,61 @@ appduct keygen
 
 This writes an unencrypted PEM private key (PKCS#8) to `<state-dir>/key.pem` by default (override with `--out`; add `--force` to overwrite) and prints the exact `sha256/...` SPKI fingerprint your app should place into `cliPins`. It runs non-interactively, so it's safe to call from CI or a setup script.
 
-`appduct sessions link`'s deep link is `<scheme>:///?appduct=<payload>&pin=<sha256/...>`. The `appduct` param is the binary v2 bootstrap payload (address, session id, token, expiry); `pin` is a separate, out-of-band query param carrying the daemon's current SPKI fingerprint for apps that want to pick it up. An app build with embedded `cliPins` ignores `pin` outright — embedded pins always win, in every build type. A build with no embedded pins trusts it for that one session.
+The deep link `appduct sessions link` prints carries the daemon's current fingerprint in its `pin` parameter. A build with embedded `cliPins` ignores it: embedded pins always win, in every build type. A build with no embedded pins trusts it for that one session.
 
 ## Daemon lifecycle
 
-The daemon auto-starts the first time any CLI or MCP command needs it — you don't normally run `appduct daemon start` yourself. It writes state to `<state-dir>/` (`daemon.sock`, `daemon.pid`, `daemon.log`, `daemon.log.1`, `events.log`, `events.log.1`, `key.pem`, `config.json`, `audit/`), holds a single-instance lock via the pidfile, and runs independently of any one device's connection, so a reload or crash on the device side never costs you the daemon process.
+The daemon auto-starts the first time any CLI or MCP command needs it — you don't normally run `appduct daemon start` yourself. It keeps its key, config, logs and audit log in the state directory (`~/.appduct` by default), runs one instance per state directory, and keeps running whatever happens to a device, so an app reload or crash never takes the daemon down.
 
 Use `appduct daemon status` to see what's running (version, pid, `wssPort`, pinned keys, live sessions, effective policy, and the audit log's retention window, file count, size, and failure counters) and `appduct daemon stop` to shut it down explicitly.
 
 Because the daemon outlives the CLI that started it, upgrading Appduct would otherwise leave the old daemon serving your commands. Every CLI/MCP process compares its version with the daemon's on its first command and replaces a stale daemon when nothing would be lost; when there is something at stake — connected sessions, or an unexpired link nobody has scanned yet — the command stops instead, naming both versions, until you run `appduct daemon stop` or pass `--daemon-restart`. A daemon newer than your CLI is left alone with a warning, so a project-local install never downgrades a global one's daemon.
 
-No log grows without bound: `audit/<YYYY-MM-DD>.jsonl` files older than `auditRetentionDays` (default 30) are pruned at daemon start and once a day after, a `daemon.log` over `daemonLogMaxBytes` (default 10 MiB) is rotated to `daemon.log.1` when a daemon is next spawned, and `events.log` is rotated to `events.log.1` as soon as it passes `eventsLogMaxBytes` (default 10 MiB). `events.log` records the daemon's own events (links, sessions, tool registries and tool calls), one JSON line each, for debugging Appduct itself; your app's events are never written to it. All three are `config.json` keys — see [`ARCHITECTURE.md` §3][architecture].
+No log grows without bound: `audit/<YYYY-MM-DD>.jsonl` files older than `auditRetentionDays` (default 30) are pruned at daemon start and once a day after, a `daemon.log` over `daemonLogMaxBytes` (default 10 MiB) is rotated to `daemon.log.1` when a daemon is next spawned, and `events.log` is rotated to `events.log.1` as soon as it passes `eventsLogMaxBytes` (default 10 MiB). `events.log` records the daemon's own events (links, sessions, tool registries and tool calls), one JSON line each, for debugging Appduct itself; your app's events are never written to it. All three are `config.json` keys; see below.
+
+### Daemon settings: `config.json`
+
+`<state-dir>/config.json` (`~/.appduct/config.json` by default) is optional, and so is every key in it. The daemon reads it when it starts, so after editing it run `appduct daemon stop`; the next command starts a fresh daemon with the new values. Stopping the daemon disconnects every device.
+
+| Key | Default | What it sets |
+| --- | --- | --- |
+| `wssPort` | `8443` | Port devices connect to. `0` picks a free port. |
+| `graceSeconds` | `600` | How long a disconnected session can still resume. |
+| `linkTtlSeconds` | `300` | How long a new link stays valid. Override per link with `--ttl`. |
+| `eventBufferSize` | `256` | App events kept per session for `events since` and `waitForEvent`. |
+| `advertisedIp` | detected | Address put in links for physical devices. |
+| `scheme` | none | Fallback deep-link scheme (step 4 of [The deep-link scheme](#the-deep-link-scheme)). |
+| `restartDaemonOnVersionMismatch` | `false` | Always replace an outdated daemon, even with devices connected. |
+| `policy` | `{ "default": "allow", "destructive": "allow" }` | Which tools callers may run without approval; see [Security][security]. |
+| `auditRetentionDays` | `30` | Days of audit log to keep. |
+| `daemonLogMaxBytes`, `eventsLogMaxBytes` | 10 MiB | Size at which `daemon.log` and `events.log` are rotated. |
+
+`keyPath` and `keepaliveIntervalSeconds` exist too; you rarely need them. An unknown key prints a warning and is ignored.
 
 ## Release gate: `appduct doctor`
 
-Appduct's inclusion in a build is controlled entirely by autolinking exclusion (see [`docs/BUILD-VARIANTS.md`][build-variants]) — there's no runtime `debuggable` check to catch a pipeline that forgot to exclude the package. `doctor` checks the built artifact itself, not the config you think produced it:
+Appduct's inclusion in a build is controlled entirely by autolinking exclusion (see [Build variants][build-variants]) — there's no runtime `debuggable` check to catch a pipeline that forgot to exclude the package. `doctor` checks the built artifact itself, not the config you think produced it:
 
 ```bash
 appduct doctor ./build/MyApp.ipa --assert-absent
 appduct doctor ./build/app-release.apk --assert-absent
 ```
 
-Exit codes, what it inspects per platform, and the marker-only detection rules on both platforms are documented in `appduct doctor --help`; CI wiring lives in `.github/workflows/test.yaml`.
+It exits with:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | The artifact was inspected, and any `--assert-present`/`--assert-absent` held |
+| `3` | The artifact was inspected and the assertion failed |
+| `66` | The artifact couldn't be inspected: it's missing, unreadable or corrupt, or a tool `doctor` needs (such as `unzip`) isn't installed |
+
+A pipeline should fail on anything other than `0`. `66` never means "absent", so a broken runner image can't pass the gate by accident.
 
 ## Related packages
 
-- **[@appduct/react-native](https://github.com/callstackincubator/appduct/blob/main/packages/react-native/README.md)** — native app client + Expo plugin.
-- **[@appduct/shared](https://github.com/callstackincubator/appduct/blob/main/packages/shared/README.md)** — wire protocol v2 types used by this package and the React Native client.
+- **[Appduct for iOS](https://github.com/callstackincubator/appduct/blob/main/packages/native/ios/README.md)** — Swift SDK for native iOS apps.
+- **[Appduct for Android](https://github.com/callstackincubator/appduct/blob/main/packages/native/android/README.md)** — Kotlin SDK for native Android apps.
+- **[@appduct/react-native](https://github.com/callstackincubator/appduct/blob/main/packages/react-native/README.md)** — React Native SDK and Expo config plugin.
 
 ## Documentation
 
@@ -337,8 +368,8 @@ Like the project? ⚛️ [Join the team](https://callstack.com/careers/?utm_camp
 [callstack-readme-with-love]: https://callstack.com/?utm_source=github.com&utm_medium=referral&utm_campaign=appduct&utm_term=readme-with-love
 [architecture]: https://github.com/callstackincubator/appduct/blob/main/docs/ARCHITECTURE.md
 [protocol]: https://github.com/callstackincubator/appduct/blob/main/docs/PROTOCOL.md
-[security]: https://github.com/callstackincubator/appduct/blob/main/docs/SECURITY.md
-[build-variants]: https://github.com/callstackincubator/appduct/blob/main/docs/BUILD-VARIANTS.md
+[security]: https://callstackincubator.github.io/appduct/guides/security/
+[build-variants]: https://callstackincubator.github.io/appduct/guides/build-variants/
 [license-badge]: https://img.shields.io/npm/l/appduct?style=for-the-badge
 [license]: https://github.com/callstackincubator/appduct/blob/main/LICENSE
 [npm-downloads-badge]: https://img.shields.io/npm/dm/appduct?style=for-the-badge

package/dist/artifact-inspect.d.ts

@@ -1,8 +1,8 @@
 /**
- * `appduct doctor` (docs/tasks/08-appduct-doctor.md): the artifact-level replacement for the
- * runtime `debuggable`/`#if DEBUG` gate removed elsewhere in opt-in hardening. Given a built
- * `.app`/`.ipa`/`.apk`/`.aab`, decide whether Appduct's native code actually shipped inside it —
- * not whether the config that's supposed to have produced it looks right.
+ * `appduct doctor`: the artifact-level replacement for the runtime `debuggable`/`#if DEBUG` gate
+ * removed elsewhere in opt-in hardening. Given a built `.app`/`.ipa`/`.apk`/`.aab`, decide whether
+ * Appduct's native code actually shipped inside it — not whether the config that's supposed to have
+ * produced it looks right.
  *
  * The one property everything here is built around: **never report "absent" because a tool was
  * missing or the artifact couldn't be read.** That failure mode is strictly worse than not having
@@ -14,31 +14,30 @@
  * Detection strategy, and why no single signal is authoritative on either platform:
  *
  * - iOS: `present` is decided by real-code-only symbols alone, exactly like Android below —
- *   `AppductCoreMarker` (`packages/native/ios/Sources/AppductCore/Real/AppductCoreMarker.swift`,
- *   docs/tasks/14-native-core-extraction.md), an `@objc` class compiled only into the real
- *   implementation, never into the SwiftPM package's `Stub/` branch, so its presence cannot be
- *   confused with a stub build. `RCTNativeAppduct` (`RCT_EXPORT_MODULE`, see
- *   `packages/react-native/ios/RCTNativeAppduct.mm`) is kept as a second real-code signal for
- *   artifacts built before the marker existed. Both are Objective-C runtime metadata — they live in
- *   `__objc_classname`/`__objc_data`, and `strip`/release optimization leaves them alone because
- *   removing them would break `+[NSObject class]`-based dispatch. (A build that dead-strips the whole
- *   translation unit for lack of `-ObjC`/`-force_load` could still drop them — these signals assume
- *   the module actually links into the binary, which is the thing being checked in the first
- *   place.) The plugin-authored `Info.plist` keys
- *   (`AppductCliPins`/`AppductTrust`/`AppductAllowPrivateLanOnly`, docs/tasks/00-overview.md
- *   "Native config keys the plugin writes") are reported as a corroborating signal only and can no
- *   longer flip `present` to `true` on their own — an app author can write these keys by hand (or a
- *   future stub could ship them) without the real implementation being present, exactly the reason
- *   the Android signals below aren't all treated as equally authoritative either.
+ *   `AppductCoreMarker` (`packages/native/ios/Sources/AppductCore/Real/AppductCoreMarker.swift`),
+ *   an `@objc` class compiled only into the real implementation, never into the SwiftPM package's
+ *   `Stub/` branch, so its presence cannot be confused with a stub build. `RCTNativeAppduct`
+ *   (`RCT_EXPORT_MODULE`, see `packages/react-native/ios/RCTNativeAppduct.mm`) is kept as a second
+ *   real-code signal for artifacts built before the marker existed. Both are Objective-C runtime
+ *   metadata — they live in `__objc_classname`/`__objc_data`, and `strip`/release optimization
+ *   leaves them alone because removing them would break `+[NSObject class]`-based dispatch. (A
+ *   build that dead-strips the whole translation unit for lack of `-ObjC`/`-force_load` could still
+ *   drop them — these signals assume the module actually links into the binary, which is the thing
+ *   being checked in the first place.) The plugin-authored `Info.plist` keys
+ *   (`AppductCliPins`/`AppductTrust`/`AppductAllowPrivateLanOnly`) are reported as a corroborating
+ *   signal only and can no longer flip `present` to `true` on their own — an app author can write
+ *   these keys by hand (or a future stub could ship them) without the real implementation being
+ *   present, exactly the reason the Android signals below aren't all treated as equally
+ *   authoritative either.
  * - Android: the primary signal is `AppductNativeMarker`
  *   (`packages/native/android/core/src/main/java/com/callstack/appduct/AppductNativeMarker.kt`,
  *   vendored into `@appduct/react-native` at `android/core/src/main/java/...`), a marker class with no
  *   other purpose. Its fully-qualified name is kept unminified and unremoved by a `-keep` rule in
  *   `consumer-rules.pro` (same vendoring path), shipped to every consuming app via `consumerProguardFiles`
  *   (see `../build.gradle`) — R8 applies it regardless of whether the app used the Expo config plugin or
- *   bare-RN autolinking, and regardless of whether the app authored any keep rules of its own
- *   (docs/tasks/10-android-detection-keep-rule.md). This is the only Android signal guaranteed to survive
- *   minification in every supported consumer setup.
+ *   bare-RN autolinking, and regardless of whether the app authored any keep rules of its own.
+ *   This is the only Android signal guaranteed to survive minification in every supported consumer
+ *   setup.
  *
  *   Two more signals are kept as fallbacks for artifacts built before this marker existed: the
  *   `com.callstack.appduct` package string in the dex string pool (and its pre-rename spelling,
@@ -56,30 +55,34 @@
  * a real inclusion to "absent" just because one check missed — but the Info.plist keys signal cannot
  * flip it to `true` by itself, matching Android's marker-only rule below (a stub that ships the same
  * plist keys without the real implementation is exactly the failure mode this guards against, even
- * though no such stub exists yet as of Phase 1 of docs/tasks/14-native-core-extraction.md).
+ * though no such stub exists yet).
  *
  * On Android, `present` is decided by the keep-rule marker alone, not an OR across all three
  * signals. The other two are reported in `signals` for corroboration/debugging but cannot flip
  * `present` to `true` on their own: `android/build.gradle`'s `APPDUCT_ENABLED`-gated vendored
- * source-directory swap (`core` vs `core-noop`, docs/tasks/14-native-core-extraction.md; previously a
- * `src/debug`/`src/release-stub` swap, see docs/tasks/00-overview.md's "Revisited
- * post-implementation") compiles a genuine no-op `AppductPackage` into a default release build at
- * the *same* fully-qualified name the real one uses (required so the shared, non-variant-aware
+ * source-directory swap (`core` vs `core-noop`; previously a `src/debug`/`src/release-stub` swap)
+ * compiles a genuine no-op `AppductPackage` into a default release build at the *same*
+ * fully-qualified name the real one uses (required so the shared, non-variant-aware
  * `PackageList.java` still resolves), and the config plugin writes the same manifest meta-data
  * regardless of variant (Expo mods edit the single merged manifest, not a per-variant one). Both
  * fallback signals therefore fire on that harmless stub exactly as they would on the real module, and
  * can no longer prove inclusion by themselves.
  *
- * `appduct doctor` is strictly better than the runtime check it replaces (docs/tasks/00-overview.md
- * "What we give up, deliberately"). The keep-rule marker closes the previously-documented gap where a
- * bare-RN app with no config plugin and no keep rule could evade both older Android signals under R8
- * minification (docs/tasks/10-android-detection-keep-rule.md) — that gap applied to builds produced before
- * this library shipped the marker/keep rule; an app that pins an older `@appduct/react-native` version
- * still lacks it, and doctor cannot detect inclusion on such a build at all.
+ * Flutter: the Dart core writes `appduct-dart-core/` into the AOT snapshot only when
+ * `appductEnabled` is true; that string in `libapp.so` / `App.framework/App` is a third
+ * authoritative signal on both platforms. The native shim is in every Flutter build and proves
+ * nothing, so doctor reports on the Dart core alone.
+ *
+ * `appduct doctor` is strictly better than the runtime check it replaces: it runs in CI, before
+ * distribution, against the thing actually shipped. The keep-rule marker closes the
+ * previously-documented gap where a bare-RN app with no config plugin and no keep rule could evade
+ * both older Android signals under R8 minification — that gap applied to builds produced before
+ * this library shipped the marker/keep rule; an app that pins an older `@appduct/react-native`
+ * version still lacks it, and doctor cannot detect inclusion on such a build at all.
  */
 export type ArtifactPlatform = "ios" | "android";
 export type ArtifactFormat = "app" | "ipa" | "apk" | "aab";
-export type DetectionSignal = "ios-core-marker-symbol" | "ios-objc-class-symbol" | "ios-info-plist-keys" | "android-keep-rule-marker" | "android-dex-package-symbol" | "android-manifest-meta-data-keys";
+export type DetectionSignal = "ios-core-marker-symbol" | "ios-objc-class-symbol" | "ios-info-plist-keys" | "android-keep-rule-marker" | "android-dex-package-symbol" | "android-manifest-meta-data-keys" | "flutter-dart-core-marker";
 export type ArtifactInspection = {
     platform: ArtifactPlatform;
     format: ArtifactFormat;
@@ -97,10 +100,6 @@ export type ExecBufferResult = {
  * corrupt-archive failure without needing either condition to be true on the machine running the
  * tests. */
 export type ExecBufferFn = (command: string, args: string[]) => Promise<ExecBufferResult>;
-/** Real subprocess execution via `execFile`, buffered as raw bytes. `maxBuffer` is generous (an
- * artifact's full decompressed contents are read into memory at once — see {@link readZipEntries})
- * since real `.ipa`/`.apk`/`.aab` files can run into the hundreds of MB. */
-export declare const defaultExecBuffer: ExecBufferFn;
 export type InspectArtifactOptions = {
     exec?: ExecBufferFn;
 };

package/dist/bin.js

@@ -128,8 +128,11 @@ var createCli = () => {
     `link: deep-link URI scheme (also: APPDUCT_SCHEME; default: .appduct/config.json, then app.json's "expo.scheme", then the Android/iOS project files in <cwd>).`
   ).option(
     "--open <target>",
-    "link: deliver the link automatically via adb/simctl/devicectl (android|ios-sim|ios-device; ios-device is experimental)."
-  ).option("--device <id>", "link: adb serial, simulator udid or paired-device udid to target when --open is ambiguous.").option(
+    "link: deliver the link automatically via adb/simctl/devicectl (android|ios-sim|ios-device; ios-device is experimental), or with `web <url>` return the page URL and a connect script for a web page."
+  ).option(
+    "--browser-url <url>",
+    "link: with --open web, attach the tab of a Chrome launched with --remote-debugging-port (such as http://127.0.0.1:9222) and claim a session on it."
+  ).option("--target-id <id>", "link: with --browser-url, the CDP target id of the tab to attach when several tabs match <url>.").option("--device <id>", "link: adb serial, simulator udid or paired-device udid to target when --open is ambiguous.").option(
     "--app-id <id>",
     `link: installed app id for --open android/ios-device (default: .appduct/config.json's "appId.<platform>").`
   ).option(
@@ -140,10 +143,10 @@ var createCli = () => {
     "--timeout <ms>",
     "call: call timeout in milliseconds. Shortens the deadline; it cannot extend one past the app's own timer, which is the tool's declared timeoutMs (else 10000)."
   );
-  cli.command("events [...args]", "Stream the app's events, or replay them since a cursor: tail or since.").usage("events <tail|since> [selector] [args]").option("--follow", "tail: accepted for script readability; the default behavior already follows.").option(
+  cli.command("events [...args]", "List the events an app declares, stream them, or replay them since a cursor: ls, tail, or since.").usage("events <ls|tail|since> [selector] [args]").option("--follow", "tail: accepted for script readability; the default behavior already follows.").option(
     "--name <glob>",
-    'Only events whose name matches this whole-name, case-sensitive glob ("*" matches any run of characters).'
-  ).option(
+    `Only events whose name matches this whole-name, case-sensitive glob ("*" matches any run of characters). ls: an exact name prints that event's full payload schema.`
+  ).option("--limit <n>", "ls: show at most n events.").option("--offset <n>", "ls: skip the first n events of the name-sorted list.").option(
     "--payload-max-bytes <n>",
     "Cap each event's payload at this many UTF-8 bytes of its JSON; over the cap, the event carries payloadPreview, payloadBytes and truncated: true instead of payload."
   );
@@ -171,6 +174,7 @@ var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "daemonLogMaxBytes",
   "eventsLogMaxBytes",
   "policy",
+  "webOrigins",
   "advertisedIp",
   "scheme",
   "restartDaemonOnVersionMismatch"
@@ -231,6 +235,7 @@ var defaultConfig = (paths) => {
     daemonLogMaxBytes: DEFAULT_DAEMON_LOG_MAX_BYTES,
     eventsLogMaxBytes: 10 * 1024 * 1024,
     restartDaemonOnVersionMismatch: false,
+    webOrigins: [],
     policy: {
       default: "allow",
       destructive: "allow"
@@ -301,6 +306,12 @@ var loadConfig = async (paths, options = {}) => {
       "restartDaemonOnVersionMismatch"
     );
   }
+  if (parsed.webOrigins !== void 0) {
+    if (!Array.isArray(parsed.webOrigins)) {
+      throw configError("webOrigins", "must be an array of origin strings.");
+    }
+    config.webOrigins = parsed.webOrigins.map((origin) => requireNonEmptyString(origin, "webOrigins"));
+  }
   if (parsed.policy !== void 0) {
     if (typeof parsed.policy !== "object" || parsed.policy === null || Array.isArray(parsed.policy)) {
       throw configError("policy", "must be an object.");
@@ -409,7 +420,7 @@ var EXIT_CODE_BY_ERROR_TYPE = {
   // EX_NOINPUT (66): "an input file did not exist or was not readable" — `doctor` throws this for a
   // missing external tool or an unreadable/corrupt artifact, deliberately distinct from every other
   // code here so a release pipeline can't mistake "we couldn't tell" for either a clean pass or an
-  // assertion failure (docs/tasks/08-appduct-doctor.md).
+  // assertion failure.
   inspection_error: 66,
   connection_error: 70,
   session_error: 71,
@@ -524,6 +535,7 @@ var getExitCodeForError = (error) => {
 import pc from "picocolors";
 import {
   formatAgentWebSocketUrl,
+  renderEventSignature,
   renderToolSignature,
   summarizeToolDescription
 } from "@appduct/shared";
@@ -619,6 +631,13 @@ var formatDevice = (device) => {
   const label = parts.length > 0 ? parts.join(" ") : "unknown device";
   return device.os ? `${label} (${device.os})` : label;
 };
+var SUSPEND_REASON_LABELS = {
+  app_backgrounded: "app in background",
+  connection_lost: "connection lost"
+};
+var formatSessionState = (session) => {
+  return session.suspendReason ? `${session.state} (${SUSPEND_REASON_LABELS[session.suspendReason]})` : session.state;
+};
 var renderLsData = (colors, data, now) => {
   if (data.length === 0) {
     return [colors.dim("Sessions"), "  No Appduct sessions are registered."];
@@ -627,7 +646,7 @@ var renderLsData = (colors, data, now) => {
   const headers = ["Alias", "State", "Device", "Tools", "Age"];
   const rows = data.map((session) => [
     session.alias,
-    session.state,
+    formatSessionState(session),
     formatDevice(session.device),
     String(session.toolCount),
     formatAge(session.claimedAt ?? session.createdAt, nowIso)
@@ -801,10 +820,87 @@ var renderToolsListData = (colors, data, flags, full) => {
   }
   return full ? renderToolsFullListing(colors, data, flags) : renderToolSummaryTable(colors, data);
 };
+var renderEventsTruncationLine = (data) => {
+  const offset = data.offset ?? 0;
+  if (data.events.length >= data.total) {
+    return [];
+  }
+  return [
+    "",
+    `Showing ${data.events.length} of ${data.total} events (offset ${offset}). Narrow with --name <glob> or page with --offset <n>.`
+  ];
+};
+var renderEventsListData = (colors, data, flags) => {
+  const [only] = data.events;
+  if (data.name !== void 0 && !data.name.includes("*") && only !== void 0) {
+    return renderFields(
+      colors.green(`Event: ${only.name}`),
+      [
+        ["Signature", renderEventSignature(only)],
+        ["Description", only.description],
+        ["Payload schema", only.payload_schema]
+      ],
+      flags
+    );
+  }
+  if (data.events.length === 0 && data.total > 0) {
+    return [
+      colors.green("Events"),
+      `  No events at offset ${data.offset ?? 0}; ${data.total} matching event${data.total === 1 ? "" : "s"} in total.`
+    ];
+  }
+  if (data.events.length === 0) {
+    return [
+      colors.green("Events"),
+      data.name === void 0 ? "  No events declared." : `  No events match ${JSON.stringify(data.name)}.`
+    ];
+  }
+  const lines = data.events.flatMap((event) => [
+    `  ${renderEventSignature(event)}`,
+    `    ${summarizeToolDescription(event.description)}`
+  ]);
+  return [
+    colors.green("Events"),
+    ...lines,
+    ...renderEventsTruncationLine(data),
+    "",
+    "Run `appduct events ls --name <name>` for an event's full payload schema."
+  ];
+};
 var renderInvokeData = (colors, data, flags) => {
   return [colors.green("Result"), formatScalar(data, flags)];
 };
 var renderLinkData = (colors, data, flags, qr) => {
+  if ("attached" in data) {
+    return [
+      colors.green("Page Attached"),
+      ...renderFields(
+        "Page",
+        [
+          ["Session", data.sessionId],
+          ["Tab", data.targetId],
+          ["URL", data.url],
+          ["Expires", new Date(data.expiresAt * 1e3).toISOString()]
+        ],
+        flags
+      )
+    ];
+  }
+  if ("script" in data) {
+    return [
+      colors.green("Link Created"),
+      ...renderFields(
+        "Link",
+        [
+          ["Session", data.sessionId],
+          ["URL", data.url],
+          ["Script", data.script],
+          ["Expires", new Date(data.expiresAt * 1e3).toISOString()]
+        ],
+        flags
+      )
+    ];
+  }
   const lines = [
     colors.green("Link Created"),
     ...renderFields(
@@ -925,6 +1021,7 @@ var renderDaemonStatusData = (colors, data, flags) => {
         ["PID", data.daemon.pid],
         ["Started at", data.daemon.started_at],
         ["WSS port", data.daemon.wss_port],
+        ["Web port", data.daemon.web_port],
         ["Pinned keys", data.daemon.pinned_keys.length],
         ["Sessions", data.daemon.session_count]
       ],
@@ -992,6 +1089,8 @@ var renderSuccessData = (colors, command, data, options) => {
       return renderToolsListData(colors, data, flags, options.full);
     case "tools describe":
       return renderToolDetail(colors, data, flags);
+    case "events ls":
+      return renderEventsListData(colors, data, flags);
     case "tools call":
       return renderInvokeData(colors, data, flags);
     case "sessions revoke":

package/dist/cli/result-types.d.ts

@@ -4,7 +4,7 @@
  * the thin-client shapes for the v2 command table.
  */
 import type { OpenTarget } from "./open-target.js";
-import type { AgentEndpoint, EffectivePolicyDecision, EventNotification, SessionSummary, ToolGroupSummary, ToolsListEntry, ToolsListResult } from "@appduct/shared";
+import type { AgentEndpoint, EffectivePolicyDecision, EventNotification, EventsListResult, SessionSummary, ToolGroupSummary, ToolsListEntry, ToolsListResult } from "@appduct/shared";
 /**
  * CLI-domain error classes, used only to pick a sysexits-style exit code (see `errors.ts`).
  * `CliError.type` itself is *not* restricted to this union: RPC/app-originated failures preserve
@@ -66,6 +66,11 @@ export type InitCommandData = {
      * tier rather than `"--scheme"`/`"already-recorded"` — `init`'s human-readable hint surfaces
      * this so a native-probe result says which file to go edit, not just which platform. */
     origin?: string;
+    /** The native platforms discovery saw in this project (`"android"` for a Gradle file or Android
+     * manifest, `"ios"` for an `Info.plist` or `project.yml`), alphabetical. Unlike `source`, which
+     * names the one input that won, this lists every platform, and it is reported on every run,
+     * including `"already-recorded"` and `"--scheme"`. Omitted when none was seen. */
+    platforms?: ("android" | "ios")[];
     /** The project config did not exist before this run. */
     created: boolean;
     /** This run wrote to the file. `false` on an idempotent re-run. */
@@ -111,6 +116,26 @@ export type LinkCommandData = {
     /** The `--open` target the link was delivered to, alongside `delivered`. */
     target?: OpenTarget;
 };
+/** `appduct sessions link --open web <url>`: the page URL carrying the link, and the script that
+ * connects an already-open page instead. */
+export type WebLinkCommandData = {
+    sessionId: string;
+    url: string;
+    script: string;
+    /** Unix seconds. */
+    expiresAt: number;
+};
+/** `appduct sessions link --open web <url> --browser-url <u>`: the tab the daemon attached and the
+ * session it will claim. */
+export type WebAttachCommandData = {
+    attached: true;
+    sessionId: string;
+    url: string;
+    /** The CDP target id of the attached tab. */
+    targetId: string;
+    /** Unix seconds. */
+    expiresAt: number;
+};
 /** `appduct sessions ls`: `sessions.list` passthrough, verbatim (ARCHITECTURE.md §10: "--json
  * passthrough"). */
 export type LsCommandData = SessionSummary[];
@@ -135,6 +160,13 @@ export type ToolGroupsListing = {
  * listing entry, picked out of `tools.list` — not a registration, so its `group` is `null` for an
  * ungrouped tool. */
 export type ToolsCommandData = ToolsListing | ToolGroupsListing | ToolsListEntry;
+/** `appduct events ls`: the daemon's `events.list` result, plus the `--name`/`--limit`/`--offset`
+ * inputs that produced it (only the ones actually given). */
+export type EventsListing = EventsListResult & {
+    name?: string;
+    limit?: number;
+    offset?: number;
+};
 /** `appduct tools call`: the tool's raw result payload, printed as-is. */
 export type InvokeCommandData = unknown;
 export type RevokeCommandData = {
@@ -164,7 +196,7 @@ export type DaemonStopCommandData = {
         method: "rpc" | "sigterm";
     };
 };
-/** `appduct doctor <artifact>`: artifact-level Appduct inclusion report (docs/tasks/08). */
+/** `appduct doctor <artifact>`: artifact-level Appduct inclusion report. */
 export type DoctorCommandData = {
     artifact: string;
     platform: "ios" | "android";
@@ -187,6 +219,7 @@ export type DaemonStatusCommandData = {
         pid: number;
         started_at: string;
         wss_port: number;
+        web_port: number;
         pinned_keys: string[];
         session_count: number;
     };