Files
pipelines/android/AGENTS.md
T
alan 9130ae8c7a Add stage-exclusive resource waiting
Add durable FIFO capacity-one resource leases for executable stages, including cleanup-confirmed release, conservative restart quarantine, queue state events, and CLI/TUI/Android waiting presentation. Add scheduler, cleanup, protocol, client, and Android coverage plus a proposed Android v3 resource draft.

Checked packaged templates and authoring skill references: neither needs updating in this item. The per-item docs note records the shared documentation that docs-fold must update; no shared README or packaged reference was edited.
2026-10-18 12:30:30 +01:00

5.3 KiB

The Android app — working map

Read this before touching android/. It is the project-specific half; how Android projects in general are built, tested and reviewed belongs to the pipeline that started you.

Build and test (offline, never with the daemon)

This checkout has no gradlew; the toolchain uses the installed distribution:

export JAVA_HOME='/Applications/Android Studio.app/Contents/jbr/Contents/Home'
export ANDROID_HOME="$HOME/Library/Android/sdk"
GRADLE=/Users/alan/.gradle/wrapper/dists/gradle-8.11.1-bin/bpt9gzteqjrbo1mjrsomdt32c/gradle-8.11.1/bin/gradle
"$GRADLE" --offline --no-daemon :app:assembleDebug        # ~7 s incremental
"$GRADLE" --offline --no-daemon :app:testDebugUnitTest    # 400+ tests, ~8-13 s

Always --no-daemon: a leftover daemon is what makes these look slow. Add one test class at a time while iterating — the full suite is for the end.

The dev device

Only the UI reviewer, while its stage holds a declared runner-exclusive resource for the selected phone, may use the device. Implementers and code reviewers do code, builds, unit tests and source review only: no adb, installs, captures, device-setting changes or main-build restoration. Never acquire a phone using sleep/check loops. Do not use the phone until compatible resource scheduling is deployed and every device user has opted in or has been reconciled by the operator. Existing pinned runs are not retroactively protected. The resource for the device below is phone-47241FDAS00DLK.

The only device is the operator's Pixel 9 Pro XL, serial 47241FDAS00DLK. The operator's Pixel 10 Pro Fold (58281FDCG000JF) is theirs: use it only where an item's brief explicitly allows it, and never make it a default. Never start or use an emulator.

The UI reviewer records original app connection/workspace, display size and power/settings before changing them. Before any capture: svc power stayon usb, settings put global stay_on_while_plugged_in 7, input keyevent KEYCODE_WAKEUP, wm dismiss-keyguard. Capture with adb -s <serial> shell screencap -p /sdcard/shot.png then adb pull — never exec-out > file. Wide layout: wm size 2000x2244; the fold's unfolded shape is wm size 2076x2152; wm size reset afterwards either way.

Create controlled fixtures for changed screens/states (including human-decision sheets) on a scratch server/database and throwaway session; never depend on incidental production state, change a real operator session, or restart a deployed service. Use the configured authoritative endpoint, never a scratch URL as a project default. Keep all shell/ADB work foreground and awaited: no detached/background processes may outlive the lease. UI review includes restoring the captured original settings and main's build before its successful return. Confirm every tool has exited. If capture, restoration or cleanup fails, report the failure explicitly; do not claim verification or readiness. Uncertain termination must fail closed and keep ownership quarantined, not delete a lock or expire it by age. Return output.resource_cleanup_confirmed=false if restoration/readiness is uncertain; that generic release veto retains the runner lease even if the harness reports idle.

Geometry is tokenised, and a test enforces it

Every dimension comes from ui/theme/Dimens.kt (plus the layout itself) — no new hardcoded dp, no percentages. DimensTest fails the build for a raw literal outside that file, so a value that genuinely needs a new token goes there, named for its purpose.

Where things are

  • ui/PipelinesApp.kt — the app shell: destinations, the floating pill, the omni-search morph.
  • ui/chat/ — the chat: ChatScreen/ChatTranscript/ChatComposer (list, transcript, composer), ChatStore (multi-conversation state), ChatFormat (parts → rendering), ChatOverrides (local rename/hide), Markdown, ChatScroll.
  • ui/screens/ — PipelineListScreen, PipelineDetailScreen, RunHistoryScreen, RunDetailScreen, SettingsScreen, Timeline.
  • ui/graph/ — the workflow graph, stage panes, artifacts gallery and viewer.
  • ui/components/ — ListRow, DetailTabs, PaneIdentity, RunStatus, AttentionSurface.
  • data/ — PipelinesRepository (the socket client) and data/protocol/ (wire shapes).
  • The app talks to the Pipelines server over the websocket in data/PipelinesRepository.kt; live run state arrives as pushed run_event frames, and every view that shows run state folds them.

Publishing a build

Copy the APK into the running run's artifacts directory as pipelines-debug-wip-<short-HEAD>.apk and report the LAN URL. The UI reviewer alone, under the same lease, restores main's build after an install: /private/var/folders/jp/q0qvjyg54fl_c5vhhk1ylz2m0000gn/T/opencode/deploy-app.sh main.

Traps

  • A build made in a worktree that is behind main is missing features main has — sync before building, and say which revision you built.
  • Restore the app's captured original connection and workspace after a fixture test, using the configured authoritative endpoint; then force-stop and relaunch under the lease. Never substitute a hardcoded or disposable scratch endpoint for the original configuration.
  • mStayOn/screen timeout are already set; do not "fix" the device by locking or sleeping it.