Skip to content

Android driver: passthrough-rules.ts holds the adb refusal rules #1267

Closed

Description

@V3RON

Part of #1259.

Scope

After this PR, passthrough-rules.ts is a part of the Android driver (ADR 0063 §4). It owns no state, and does the adb passthrough: which arguments are refused (with today's messages), filling in -s <serial> for a command that needs a device, and running it on the device's adb server. AndroidDriver builds it in its constructor, passes it the options it needs, and delegates to it. Behaviour, messages, timeouts and files on disk do not change. index.ts keeps exporting ANDROID_PASSTHROUGH_TOOLS, REFUSED_ADB_VERB and REFUSED_ADB_SEQUENCES (F9, F10), and keeps passthroughTools and the passthrough verb, which delegates. The test at index.test.ts:3483 stays in index.test.ts: it proves the verb reaches the part with the -P <port> prefix and the scoped env.

In short

About 216 lines of code move out of the 3,573-line driver into a file an agent reads whole. Nothing a user or a caller sees changes. A part is a file that owns its own state and takes its collaborators in an options object; it never imports index.ts.

flowchart LR
  R["index.ts: AndroidDriver"] --> P["passthrough-rules.ts (new part)"]
  R --> O[parts moved earlier]
  P --> O
Loading

What a user would notice if this goes wrong: a refused adb command passes, or an allowed one is refused.

Technical spec

Facts

Commit 059a270. Line numbers are on that commit; earlier tasks of #1259 move code, so the implementer finds each name by search.

# Fact Source
F1 every name this task moves, at its line on 059a270 (the exact assignment of every name of the file, made from its syntax tree) ANDROID_PASSTHROUGH_TOOLS at src/drivers/android/index.ts:308; RECLAIM_INSTEAD at src/drivers/android/index.ts:323; REFUSED_ADB_VERB at src/drivers/android/index.ts:333; REFUSED_ADB_SUBCOMMAND at src/drivers/android/index.ts:341; STOPS_A_RUNNING_DEVICE at src/drivers/android/index.ts:351; SELF_CONTAINED_ACTIONS at src/drivers/android/index.ts:396; allowedGlobalArity at src/drivers/android/index.ts:398; GlobalsWalkResult at src/drivers/android/index.ts:406; walkGlobals at src/drivers/android/index.ts:420; NO_DEVICE_SUBCOMMANDS at src/drivers/android/index.ts:448; actsOnNoDevice at src/drivers/android/index.ts:463; namesOwnSerial at src/drivers/android/index.ts:471; fillAdbDevice at src/drivers/android/index.ts:491; callerSuppliedScopeFlag at src/drivers/android/index.ts:497; REFUSED_ADB_SEQUENCES at src/drivers/android/index.ts:502; isBareShell at src/drivers/android/index.ts:533; containsSequence at src/drivers/android/index.ts:550; refusedSequenceMessage at src/drivers/android/index.ts:571; passthrough at src/drivers/android/index.ts:911; #runAdbOn at src/drivers/android/index.ts:937; #assertProxyable at src/drivers/android/index.ts:952
F2 a part in this folder takes an options object and is built by the driver src/drivers/android/adb-registrar.ts:22-25, src/drivers/android/index.ts:675
F3 such a part has its own test file that builds it directly src/drivers/android/adb-registrar.test.ts:9
F4 the folder's testing.ts is imported by index.test.ts, and the test file's shared helpers sit outside any describe src/drivers/android/index.test.ts:46, src/drivers/android/index.test.ts:5117-5410, src/drivers/android/index.test.ts:7306-8212
F5 Fallow fails CI on an import loop between files (circular-dependencies, default error) and on any dead-code finding node_modules/fallow/schema.json RulesConfig at pnpm-lock.yaml:2180; docs/internal/agent-rules/toolchain.md:51-53
F6 test-lint flags an added sibling import in a test unless a why: sits above the first describe .agents/scripts/test-lint.mjs:141-148
F7 the module manual is 141 lines, and manuals may have at most 150 src/drivers/android/AGENTS.md:1-141, src/docs-manuals.test.ts:9
F8 the root tests that prove the root still reaches this part src/drivers/android/index.test.ts:3483 "points an adb passthrough at Simlock's own server, which is the only one that sees it"
F9 src/instructions/index.test.ts imports REFUSED_ADB_SEQUENCES and REFUSED_ADB_VERB from the Android index src/instructions/index.test.ts:9
F10 src/daemon/main.ts imports ANDROID_PASSTHROUGH_TOOLS from the Android index src/daemon/main.ts:54

Modules touched

Searches: grep -rn of each F1 name under src/ (hits only in src/drivers/android/index.ts, src/drivers/android/index.test.ts and, for the exports index.ts keeps, their importers); ls src/drivers/android/passthrough-rules.ts (absent on 059a270).

flowchart LR
  R["index.ts (changed)"] --> P["passthrough-rules.ts (new)"]
  P --> E["earlier parts, data.ts"]
Loading
  • src/drivers/android/passthrough-rules.ts: new; the part. It imports only data.ts, files that exist on 059a270 and the parts of earlier tasks; anything else reaches it as an option or a callback.
  • src/drivers/android/index.ts: builds the part, delegates, and loses the F1 names.
  • src/drivers/android/index.test.ts: loses the tests named under Tests.
  • src/drivers/android/passthrough-rules.test.ts: new; its tests.
  • src/drivers/android/data.ts: takes a type two parts share, when this task moves one.
  • src/drivers/android/testing.ts: takes any helper two test files now use.
  • src/drivers/android/AGENTS.md: the one Files row for the parts (ADR 0063), which Android driver: adb-tools.ts, the leaf part for env, commands and device folders #1264 adds, gains passthrough-rules.ts and a few words; no new row (F7).
  • src/source-hygiene.test.ts: the two Android entries of the shrink-only list take their new lengths; an entry whose file is now within its limit is removed.

Contract and event changes

none: the task moves code inside the Android driver; no file under src/contract/ and no event changes (search: git grep -n "drivers/android" src/contract gives 0 hits).

Other code on the same state

The state this part owns: no state. Searches: grep -n of each owned name in src/drivers/android/index.ts and under src/ outside the Android folder (0 hits outside). After this task the root and later tasks (#1268, #1269, #1270, #1273, #1271, #1272) reach that state only through this part's interface; none keeps a copy.

Failure modes

none: the task crosses no new boundary and writes no new state. Every call to adb, emulator, avdmanager or sdkmanager it moves keeps its arguments, environment and time limit (F1).

Rules in play

  • ADR 0063 §1, "A part never calls the root": the part takes collaborators and callbacks in its options and imports no index.ts (F5 fails a loop).
  • ADR 0063 §2, tests sit with the part: a test moves only when everything it asserts is made by this part; a test across parts stays in the root's tests. A part test file has one why: above its first describe naming "a part of a decomposed module" (F6).
  • ADR 0063 §3: a listed file that is now within its limit leaves the shrink-only list in this PR.
  • Architecture rule 14, "nothing outside the directory imports a file inside it": only files in src/drivers/android/ import the part.
  • Architecture rule 17, "A comment starts with why:": a moved comment that is not a why:, or that no longer holds, is deleted.
  • Documentation rule 7 and src/docs-manuals.test.ts: the manual stays within 150 lines (F7).

Tests

The seam is src/drivers/android/passthrough-rules.test.ts, a new file modelled on src/drivers/android/adb-registrar.test.ts. These 12 tests move there, each keeping its claim and cases, because everything each asserts is made by this part: src/drivers/android/index.test.ts:3498 "fills an emulator's serial into an adb command that names no device"; src/drivers/android/index.test.ts:3546 "refuses an emulator adb command that names another device, or that runs on another platform…"; src/drivers/android/index.test.ts:3600 "rejects a refusal with PassthroughRefusedError naming adb, never throwing it synchronously…"; src/drivers/android/index.test.ts:3614 "refuses kill-server, which would detach every leased emulator at once"; src/drivers/android/index.test.ts:3622 "refuses kill-server behind a global flag, not only in first position"; src/drivers/android/index.test.ts:3633 "refuses adb disconnect with or without an address, on the local CLI and through device.exec…"; src/drivers/android/index.test.ts:3680 "refuses an emu avd stop that would stop a device Simlock believes is running: %j"; src/drivers/android/index.test.ts:3691 "refuses every emu avd snapshot subcommand except list, since the boot snapshot is what later l…"; src/drivers/android/index.test.ts:3733 "refuses an emu kill pair even behind the -s serial that targets a device"; src/drivers/android/index.test.ts:3745 "refuses a caller-supplied server flag in the globals, in every spelling adb accepts, and any g…"; src/drivers/android/index.test.ts:3820 "refuses a bare adb shell only where the caller has no terminal, never merely because shell…"; src/drivers/android/index.test.ts:3870 "proxies the emu subcommands that do not stop a device". Every other test stays where it is; F8's tests stay in src/drivers/android/index.test.ts and keep proving the root reaches the part.

  • A caller passes adb arguments through passthrough-rules.ts, and is refused or served exactly as before; cases: "fills an emulator's serial into an adb command that names no device"; "refuses an emulator adb command that names another device, or that runs on another platform…"; "rejects a refusal with PassthroughRefusedError naming adb, never throwing it synchronously…"; "refuses kill-server, which would detach every leased emulator at once"; "refuses kill-server behind a global flag, not only in first position"; "refuses adb disconnect with or without an address, on the local CLI and through device.exec…"; and the other tests named in its task.

Done when

  • pnpm exec vitest run --project unit src/drivers/android passes, and its number of tests is the base's plus the tests this task adds.
  • src/drivers/android/passthrough-rules.ts exists, and only files in src/drivers/android/ import it: dependency-cruiser's past-index rule (.dependency-cruiser.mjs:36-37), run by pnpm check, fails any import of it from outside the folder.
  • src/drivers/android/index.ts defines none of the F1 names, except each Driver method (and other AndroidDriver member the core or the daemon calls), which stays and delegates; the root's field that holds the part takes a name that is not an F1 name; an F1 constant the root still uses is imported from the part.
  • In src/source-hygiene.test.ts, each Android entry equals its file's new line count, or is gone when the file is within its limit.
  • pnpm check passes.

Out of scope

Depends on

Written by an agent.

Activity

  1. added
    task:draftScope written; technical spec or its spec check missing.
    on Nov 4, 2026
  2. added
    task:readySpec checked. An agent may implement it once its Depends on allow.
    and removed
    task:draftScope written; technical spec or its spec check missing.
    on Nov 4, 2026
  3. self-assigned this
    on Nov 4, 2026
  4. added a commit that references this issue on Nov 4, 2026
    8562cb2
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

task:readySpec checked. An agent may implement it once its Depends on allow.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions