Manual-test harness: devices and sessions¶
Part of the manual-test harness.
Devices and teardown¶
devices --batch-dir "$B" [--daemon K] [--timeout-ms 30000] lists only running
devices with a nonempty runtime device ID and lifecycle booting, booted or
shutting-down. JSON: batchDir, protectedDevices, baseline availability, daemon
liveness/errors, and device rows. Each row has deviceId, name, identity.stableId,
platform, isVirtual, seenByDaemons (visibility, not boot ownership), pid (+ optional
pidReason; null for iOS and physical), provenance, protected, poolStatus, and
heldBy when exposed. Rows also carry optional bootedBy: "daemon<N>" (from MT_DAEMON)
and processAvdName (the process’s -avd argument).
Positive evidence is the MT_BATCH/MT_DAEMON environment an emulator inherits
from its private daemon. The harness reads it with ps eww -o command= -p <pid> for the
one Android console-port listener PID lsof resolved (5000 ms per probe). This has not
yet been observed on a live batch. A missing PID, failed/empty read, or any iOS simulator has
no process evidence. Provenance:
batch-booted: the process carries exactly this batch’sMT_BATCHmarker.foreign: environment read without this batch’s marker, regardless of baseline.preexisting: no process evidence; runtime ID is in the first-start baseline (shared/host-devices-at-start.json).batch-inferred: no process evidence; ID absent from a recorded baseline for its platform.unknown: no process evidence and the platform baseline is missing, or two daemon rows conflict.
Baseline recording is best-effort: a failed write prints one BASELINE WARNING: and
never changes the launch result.
shutdown-devices --batch-dir "$B" stops by default only unprotected virtual devices
with positive batch-booted evidence. Unprotected batch-inferred devices are
reported inferred-not-stopped (exit 1). Verify the batch started them, then name
them by exact device ID (serial/UDID) with --device ID; every iOS simulator needs
this. A unique name may select a batch-booted device. An ambiguous selector stops
nothing and reports ambiguous for every match (a separate unambiguous selector
still applies). The harness never sends a frame to foreign, preexisting,
unknown and physical devices, even when named. The --daemon K option restricts
the view, --dry-run reports without stopping, and --timeout-ms defaults to 60000.
Protection matches any of deviceId, name, identity.stableId, processAvdName.
When the protected list is nonempty, the harness refuses an empty or
Unknown (<serial>) Android name without a process AVD name. It also refuses
heldBy: "other_daemon" and every other heldBy string locally (unknown hold labels
count as held, never as permission). The harness asks a listing daemon’s killDevice without force and never signals a
device process.
| Outcome | Meaning |
|---|---|
stopped |
Shutdown succeeded, or device_already_stopped confirmed the goal state; the daemon’s message is retained. |
refused |
The daemon refused, with its code/message. |
failed |
The request failed; no retry of a possibly completed mutation. |
timeout |
The request deadline expired. |
protected |
The target matches protection or its name cannot be safely checked. |
not-batch-booted |
The target is physical, foreign, preexisting, or unknown; selectors cannot override this. |
inferred-not-stopped |
Check the inferred device and name it by exact device ID (serial/UDID) with --device. |
broker-held |
A held device is refused before sending a frame; use broker release. |
held-by-other-daemon |
The inventory reports another daemon holding it; no frame is sent. |
ambiguous |
Multiple devices match; this selector stops nothing. Name each target by device ID (serial/UDID). |
not-found |
No device in the selected view matches the explicit selector. |
dry-run |
An eligible target would be stopped. |
Every result row includes provenance and bootedBy when known. Shutdown exits 0
when every target is stopped/dry-run (including no targets) and every selected
daemon produced an inventory; otherwise 1. Inventory refusals, unparseable replies
and transport failures add top-level daemonErrors: [{name,error}] while devices
from healthy daemons are still processed. A daemon whose socket replies is
alive: true even if the reply cannot be parsed. devices exits 1 only when no
daemon produced an inventory.
Without inventories, devices/shutdown-devices fall back to
shared/devices-last.json, reporting unprotected batch-booted and batch-inferred
snapshot devices with refreshed PID evidence, exit 1 and no shutdown frames.
Selectors restrict the fallback (ambiguous gives ambiguous, missing gives
not-found), and explicitly selected protected/foreign/preexisting/unknown devices
keep their refusal rows. Run devices before stopping the daemon to retain
evidence. A dead daemon’s snapshot never authorizes signalling a device PID; restart
only the recorded private daemon and let product recovery own cleanup.
Broker batches add allowed/foreign/protected classification from
evidence/ledger.jsonl. A ready init.json.session grant plus matching
session-info native name, device ID and platform establishes the batch binding;
protection always wins. Allowed rows include client and sessionUuid.
devices --ledger reads only that evidence, without sockets or host probes. The
product’s isSessionBrokerDeviceName predicate recognizes names including legacy
amslot-*; the harness never hardcodes that prefix, and a matching name alone never
makes a device allowed: the batch ledger must also bind it.
Broker teardown order: broker1 down, broker1 report, stop the private daemon,
then stop the batch’s caffeinate by its recorded PID. For separate plain batches use
shutdown-devices before daemon stop. Broker-held rows must be released through the
broker; no force bypass. After closing clients and joining release receipts,
broker1 down drains the broker pool through daemon/drainBrokerPool before checking
native absence. Devices the drain leaves running are reported as retained;
shutdown-devices refuses them as broker-held, and they are never signalled.
Persistent stdio-proxy sessions¶
Use proxy1 (or in-daemon-env.sh … proxy) with --client NAME, resolved through
broker/clients.json. The --dir option is exclusive with --client and is for plain proxies
in a separate non-broker batch; broker batches refuse sessionless proxy operations.
The up/serve commands require a private PID file naming a live process and an answering
control socket (broker clients also session-broker/v1). Start the private daemon
first; a proxy never wakes it.
# Gate every manual acquisition; broker1 up does this automatically.
bun scripts/manual-test/private-daemon.ts boot-gate --batch-dir "$B" --role a-phone \
-- "$B/bin/proxy1" up --client a-phone --profile phone --expect ready < /dev/null
"$B/bin/proxy1" call --client a-phone observe '{}' < /dev/null
"$B/bin/proxy1" tools --client a-phone < /dev/null
"$B/bin/proxy1" info --client a-phone < /dev/null
"$B/bin/proxy1" status --client a-phone < /dev/null
"$B/bin/proxy1" status --all < /dev/null
"$B/bin/proxy1" release --client a-phone < /dev/null
"$B/bin/proxy1" close --client a-phone < /dev/null
upcreates a fresh attempt ID and archives prior evidence, refusing an already-live driver. The--resumeflag replays the exact persistedrequest.jsonandowner-tokenbytes and never creates a replacement after a refusal. A terminal capacity refusal stays refused after capacity frees, so use a freshup.--expect readyor--expect failed:<code>exits 0 for the expected outcome, 2 on mismatch. Without it, failed/pending outcomes are typed failure data.--profiletakes an archetype name or inline device requirement JSON;--requesttakes SessionConfig JSON or a file path and assigns a fresh attempt ID. Both are forup/serveand mutually exclusive.--owner driveris the default. The--owner disposableoption starts a recorded harness-owned sleep process with a process start identity. Theowner-kill --client NAMEcommand signals only that owner after identity confirmation (tests owner death without killing an unrelated driver or parent).release --client NAMEreleases the granted session with its stored token;abandon --client NAMEconsumes the stored request identity even if unknown to the daemon (240 s RPC budget). Release polls for cleanup; abandonment prints its receipt, which may still havecleanupPending: true. Verify settled cleanup and native absence before continuing. Theupcommand captures native info best-effort within 5 s after readiness;infosaves the native descriptor toinfo.jsonand feeds the ledger.close --client NAMEcloses MCP/stdin and waits up to 240 s for a released receipt of a granted session. Theupcommand refuses while a client driver is alive. Release does not end the driver; runclose --client NAMEfirst, then retryup. A refused or failed attempt (e.g.daemon_unavailable, abandoned request) has no receipt:closereturns at once with exit 0 andrelease.outcome: "failed"inclosed.json(receiptMissing: truewhen the daemon holds no receipt or is unreachable). It then joins the driver’s exit (5 s), including one resumed byup --resume, so the nextupnever sees “Previous attempt driver is alive”. It signals a lingering driver only when its recorded start identity (driver-identity) still matches; otherwisecloseexits 2 without signalling.statusshows initialize/live outcome, grant/profile, typed failure, owner liveness anddaemonSocketAlive;--allprints all clients.calltakes inline JSON or@file,--timeout-ms(default 900000) and--full, and requires a ready grant and live driver. Explicit selectors must match the grant. The--allow-foreign-session OTHERoption permits selectors for that named ready batch client only, for a deliberate isolation test (the product must still refuse).release/abandon --as-client OTHERuse that batch client’s stored token to test wrong-owner refusals and print an isolation notice. No token flag exists; tokens stay in files and are redacted from output.
Each sessions/<client>/ holds immutable request.json, owner-token (0600),
attempts.json, init.json.session, driver.pid, proxy.pid, events.jsonl,
notifications.jsonl, in/, out/<id>.json, serve.log, proxy.stderr.log, and
eventually closed.json; disposable owners add owner.pid and owner-identity.
Initialize has a 900000 ms default deadline (--init-timeout-ms). Full responses
stay in out/; stdout can be compact.
Clean close, explicit release, proxy owner loss and abandonment end the broker
execution through product lifecycle operations; under zero pooling the product
destroys the device. A receipt alone is not native absence proof: batch teardown
joins cleanupPending: false with a healthy native inventory and records released
and absent (or leaked) in the ledger. An info-less grant with a settled released
receipt is recorded released with absence: not-verifiable (teardown can finish
without claiming absence); a dead daemon or unavailable inventory cannot prove
absence. Android may reuse a serial for a fresh device, so retain native name and
session identity too. See the broker lifecycle contract.
Known limit: the proxy receives its owner token via --liveness-owner-token on argv,
visible in ps to other users on a shared host despite output redaction.
Raw daemon frames¶
frame1 send writes newline-delimited frames on one private control connection,
prints every answer with elapsed milliseconds, and sends the exact method named.
daemon/*, ide/*, input/* default to daemon_request; tools/call defaults to
mcp_request; --type overrides. Session-info uses daemon/sessionInfo; heartbeat
uses the external CLI keeper without claiming ownership (the daemon rejects it for a
proxy-owned session).
--broker-binding CLIENT reuses that batch client’s unchanged request and token on
the frame connection and keeps its ready grant on exit. With --broker-binding
/absolute/request.json, the tool acquires a standalone session on the same connection,
heartbeats it and releases it on graceful exit. It can boot real devices, needs the
same boot gate, and is allowed only outside broker batches (untracked paths inside
batches refuse with guidance to use --broker-binding <client>). Templates:
{{ownSessionId}}, {{clientSessionId:<name>}} (cross-client tests),
{{ownLivenessOwnerToken}}; unresolved values refuse before connecting.
"$B/bin/frame1" send tools/call \
'{"name":"observe","arguments":{"sessionUuid":"{{ownSessionId}}"}}' \
--broker-binding a < /dev/null
"$B/bin/frame1" send tools/call \
'{"name":"observe","arguments":{"sessionUuid":"{{clientSessionId:b}}"}}' \
--broker-binding a --expect-refused < /dev/null
"$B/bin/frame1" send tools/call '{"name":"startDevice","arguments":{}}' \
--broker-binding a --expect-refused < /dev/null
"$B/bin/frame1" send daemon/releaseBrokerSession '{"sessionId":"{{ownSessionId}}"}' \
--broker-binding a --token-of b --expect-refused < /dev/null
--expect-refused (send mode only) requires every response to be an error with a
product refusal code or message (success or unrelated errors exit 2). Product
refusal codes: device_outside_broker_grant (labels and unbound devices),
device_outside_bound_session (a bound connection naming another session or device,
as in the cross-client-isolation-live probe), read_session_not_bound (a read naming
a session another connected client owns) and session_ownership_lost.
Lifecycle probes accept only {} or an object containing only the client’s own
sessionUuid; device names and selectors refuse before sending. Resources/list,
automobile:devices/* reads and --allow-selector remain forbidden. The --token-of
OTHER option changes only the user status/release isolation frames to another batch
client’s stored token (binding and heartbeats keep their own). Tokens are redacted
and a notice is printed.
The --hold-ms option defaults to 0. The --mode cancel or cancel-after:<ms>
mode destroys the socket (standalone grants end through owner loss). The
cancel-keep-open[:<ms>] mode (read window default 5000 ms) waits --cancel-after-ms (default 0), sends same-connection
daemon/cancelRequest for each ID, prints answers and a cancelled/answered summary,
and closes gracefully. Deliberate cancel exits 0; missing transport exits 3. Send
mode awaits every requested answer. Repeatable --then '<method> <params
json|@file>' sends sequentially after the initial replies (send mode only).
The --timeout-ms option defaults to 30000, --count to 1. Host restart/maintenance frames
require --allow-host-mutation. No raw frame bypasses broker ownership or resident
protection.