The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
docs: phone overnight report and handoff
deeca7c617ad49f
diff --git a/docs/research/2026-09-28-phone-overnight.md b/docs/research/2026-09-28-phone-overnight.mdnew file mode 100644index 000000000..c6af9b6e5--- /dev/null+++ b/docs/research/2026-09-28-phone-overnight.md@@ -0,0 +1,220 @@+# Phone app, overnight 2026-09-27 → 28++The goal set at bedtime was to make the Harness phone app world class. That meant:+- test coverage and edge cases;+- fixing the bugs found;+- improving the UI/UX;+- a panel of AI users playing the target audience, whose feedback drives the fine-tuning.++That audience is people with strong consumer-app taste who now run Claude Code and Codex and want to manage them from a phone.++Everything below is on branch `phone-overnight-polish` (pushed to origin). Nothing was merged or released overnight. **The last section is the handoff for the next agent.**++## In one screen++- **Tests:** 486 → 1,555 (plus 25 skipped). The whole suite passes. `flutter analyze` is clean outside `third_party/`.+- **Coverage:** 50.4% → **87.0%** of lines, not counting `third_party/`.++ | Area | Coverage |+ |---|---|+ | e2ee, api, auth, notify, theme | 100% |+ | viewer | 99.2% |+ | p2p | 98.5% |+ | core | 97.2% |+ | usage | 95.0% |+ | ws | 93.1% |+ | analytics | 92.1% |+ | widgets | 89.8% |+ | phone | 89.0% |+ | shared | 81.2% |+ | state | 80.3% |+ | demo | 77.0% |+ | terminal | 74.9% |+ | logging | 72.6% |+ | settings | 46.2% |+ | clipboard | 33.3% |++- **Dead code:**+ - 52 files and about 17,100 lines the phone never runs were deleted. Each deletion was proved with tree-shaken AOT builds for iOS and Android.+ - The desktop's half of `AppNotifier` was cut: 7,100 more lines, 13 files. `viewer` is now non-nullable.+- **Bugs:** 38 real bugs fixed, each with a regression test (listed below).+- **Test safety:** every test now runs in a throwaway home (`test/flutter_test_config.dart`), so no test can read or write a developer's `~/.harness`. `test/test_home_guard_test.dart` pins this.+- **Review panel:** five AI personas, two rounds. The average score went from 6/10 to 7/10. The round 2 fixes landed after scoring; round 3 has not run yet.++## The review panel++Five personas each reviewed renders of every phone screen. In round 2 they also saw an 18-screen walk-through of the real app, recorded on the iOS simulator in sample mode.++| Persona | Lens | Round 1 | Round 2 |+|---|---|---|---|+| Maya | design lead on two iconic consumer apps | 6 | 7 |+| Theo | founder of a Things/Superhuman/Linear-style productivity app | 6 | – |+| Priya | runs 6–10 Claude Code and Codex harnesses across three machines | 6 | 7 |+| Sam | first-time user with consumer taste; Claude Code on the Mac, no Harness | 6 | 7 |+| Jordan | former Apple Design Award juror (HIG, accessibility) | 6 | 7 |++### Round 1 findings that all five agreed on, and what happened++| Finding | Outcome |+|---|---|+| The terminal is clipped at the right edge (a blocker, 5/5) | **A fixture bug, not the app.** The render test seeded a 46-column screen into a 42-column view. Fixed the fixture; the simulator walk-through confirms the live app fits. |+| The mic covers the agent's input line | **Kept.** Your decision: "the current mic location is perfect". |+| Voice sends words you never saw | **Kept.** Your decision: auto-send. |+| "Harness" confuses as a noun | **Kept.** A harness is a session: one agent, many harnesses. It is now taught where it is first met: New ("A harness is one session of an agent"), How Harness works, and the "N harnesses" count. |+| Every other computer needs its own password | **Fixed.** A locked computer unlocks by scanning its Add Phone QR; the password stays as the fallback for servers. |+| Two different set-up screens | **Fixed.** There is one set-up page (the website's download menu). Signed in, it also watches for the computer and pairs by scan. |+| Settings duplicates and unclear labels | **Fixed:** "Phone name", "App colors", the lone "usage" header removed, readable heading contrast. |+| VoiceOver can't read the terminal or reach Find or New | **Fixed.** |+| The scroll-position tag "[22/39]" is jargon | **Removed.** Your call: "we don't need the scrolling indicator". |++### Round 2 fixes++- **The sample.** Its agents stopped parroting your words back ("On it — run the tests…"). This matters because the "how it works" video is recorded from the sample. It also announces permissions the way the daemon does ("Approve Bash command: psql …") rather than "Do you want to proceed?", and names its computer "studio" rather than the fixture id "sample-studio".+- **The line above the mic** hides while you read history; it used to print over the rows being read.+- **The key strip** opens on its own keys. It used to scroll to the agent's `shift+tab` hint on every open, which pushed **esc** off the edge while the agent said "esc to interrupt".+- **VoiceOver:** it can cancel a voice take, hears "Asking: …" when a question opens, and reads the line above the mic as a live region.+- **Copy:** "5 harnesses", "Leave the sample" (both places), "Choose an agent and a project".+- **The scan page** says the link is end-to-end encrypted, which was the first-time user's trust gap.+- **New** shows branch, approvals and profile all the time. The `[+]` toggle is gone; it hid the two things worth checking before a harness starts, over an empty half-screen.+- **Settings:** Usage, Computers and Phone name join the account group. There is no lone Usage card, and Phone name is no longer filed under *terminal*.+- **"Stop this harness…"** stays small at the foot of the menu but is now red; faint grey read as disabled.+- **Form rows** put the label on the value's first line; "approvals" used to sit beside its note.++## Bugs fixed (each with a regression test)++**Sign-in and pairing**+- A scanned pairing code no longer outlives its session.+- A refresh in flight cannot bring back a signed-out session.+- A rate-limited refresh no longer signs the phone out.+- No sign-out from a closed socket, and no hot loop on a refused token.+- Linking never throws, so Unlock and Pairing cannot hang for good.+- Pairing times out on a dial that never opens, and keeps a lockout's retry time.+- A scanned code whose account cannot be read no longer hangs on "Pairing…".+- Pairing by password names this phone to the computer (it was "harness link").++**Connection**+- A replaced relay connection can no longer speak for its machine.+- A replayed welcome or rekey cannot roll the group key back.+- A data channel closing under an open link no longer throws uncaught.+- A second `terminal_ready` for one open no longer leaks a heartbeat.+- A locked state file no longer stops a machine reconnecting for good.+- A terminal switched off by an unanswered negotiation is asked about again.++**Terminal and Focus**+- The terminal follows a keyframe that swaps its screen, not only a rebuild from above.+- A pager guess reopened after its stream died no longer takes the terminal.+- A tap reopens a dead stream.+- The kept screen of an agent read a moment ago is shown, not a blank page.+- A conversation open in a terminal is refused in words, not as a lost reply.+- A question's refusal of a voice answer says why, not "terminal not taking input".+- A resume the machine never received is sent again, not checked forever.+- A stopped harness stays on the phone; the minute's sync sees every field it draws.++**Layout**+- An emoji where a name is cut no longer crashes Focus or Settings.+- The Focus title and the sample's end card no longer overflow at large text.+- The welcome screen and pairing scroll instead of overflowing.+- New's dock scrolls instead of overflowing on a small phone.+- The attaching skeleton shows with Reduce Motion on.++**Dialogs**+- A field inside an app dialog gets the focus it asks for, and the keyboard.+- A rename answer landing as the dialog closes no longer pops the page under it.++**Usage and notifications**+- A reset time past what a DateTime holds no longer drops a machine's usage.+- A partial or failed usage cycle keeps the figures it could not renew.+- One failed start of the notification plugin no longer silences the launch.+- A notification body is never cut through the middle of an emoji.++**Privacy and logs**+- The debug log keeps the length of a harness's first task and a Find search, never the words.+- Log redaction blanks plain-base64 bearer tokens, Basic auth and sign-in codes in URLs.+- An analytics event trimmed while on the wire no longer takes the next one with it.+- A busy analytics visit keeps `analytics.json` within a minute of the clock.++## Decisions already made by the user (do not re-propose)++- Voice keeps auto-send.+- The mic stays where it is; the terminal is full screen under it.+- Keep the word "harness" (harness = session; one agent, many harnesses). Teaching it is fine; renaming it is not.+- No scroll-position indicator. The "api-fix asking" label stays.+- PRs only. The user merges and releases; nothing is merged or released without their explicit word.++## Handoff for the next agent++### State++- Branch `phone-overnight-polish`, pushed. It is 113 commits ahead of `main`. **No PR is open yet**; opening one is the next step (the user merges).+- Merged into it and finished: `coverage-rest` (coverage engineer), `desktop-cut` (the desktop's half of the notifier), and the phone-screens and state-core engineers' passes. No engineer is still running.+- Never commit `mobile/ios/Runner.xcodeproj/project.pbxproj`. It carries the local signing team and stays modified in the worktree.++### How to run++From `mobile/`, with Flutter 3.47.2:++- **Everything:** `flutter test`, about one minute. For coverage, `flutter test --coverage`, then read `coverage/lcov.info`.+- **Screen renders:** `PHONE_RENDER_DIR=<dir> flutter test test/render/phone_screens_render_test.dart`. It writes 25 PNGs, one per screen. The fixture terminal is 42 columns, so canned lines must fit in 42.+- **Walk-through on the iOS simulator, sample mode only:** `HARNESS_JOURNEY_OUT=<dir> flutter drive --driver=test_driver/journey_driver.dart --target=integration_test/tour_test.dart`.++### Rules++- **No real account, device or daemon from any automated or AI-driven input.** Personas and engineers drive only sample mode, renders and the simulator in sample mode.+ - No test may use the network.+ - Engineers do not push; the lead merges their branches.+- Unset `TMUX` in tests.+- Every git and gh action is done as `deehw`.+- No private data in the repo (no home paths, real usernames or emails).++### Open work, in order++1. **Open the PR** for `phone-overnight-polish`, with this document as its summary.+2. **Panel round 3.** Re-render, re-record the walk-through, and re-run the four personas on the same brief. The target is 8+/10.+3. **Round 2 items still open.** None of these conflict with the user's decisions:+ - **The "needs you" line above the mic.**+ - Its dot is green, but green means *working* in Find; make it the asking yellow.+ - Give it an opaque band so terminal text never shows through it.+ - Keep the dot at a fixed offset from the text; it moves between frames.+ - Left-align it on the terminal gutter.+ - **Sheets.**+ - The Agent sheet covers about 75% of the screen for three rows; size sheets to their content.+ - The sheet titles "Project" and "Agent" sit about 4pt right of the rows below them.+ - Consider the system grabber.+ - **Placeholder contrast.** #8B8B8B on the #2C2C2C raised field is 4.1:1. Use about #9A9A9A (5:1).+ - **The Unlock page** says "Machines → studio → Set password". Check what the desktop menu actually calls it first, then use the same word, with ▸ as elsewhere.+ - **The sample.**+ - The pick-up heading should say it is a sample.+ - The placeholder in Claude's input line (`Try "run the…`) runs under the mic; shorten it in `lib/demo/sample_scripts.dart`.+ - "Try the sample" should be a first-class row near the top of the set-up page, not the last, dimmest line.+ - **Settings:** the lone "?" avatar is the only blue in the app.+4. **Dead code** found by the desktop-cut engineer, now with no callers:+ - In `app_state.dart`:+ - `SpokenTaskRequest`, `spokenTasks`, `reportVoiceRoute` and the handling of `voice_route_request`;+ - `selectAutonomousEnv`;+ - `hasNavigationRail`, and the pin and grid-keyboard methods (`togglePinPane`, `focusLastPane`, `toggleZoomPane`, `focusPaneBy*`, `movePaneBy`, `reorderPane`);+ - `paneFocusRequest`, `seedSwarm`, `openAgentFromDial`.+ - Elsewhere:+ - `DialState.restore`;+ - `WsTransportKind.localPlaintext` in `ws_conn.dart`/`ws_pool.dart`;+ - ApiClient's no-auth `localCliBaseUrl` mode;+ - `TerminalLinkOpener.open(isLocalMachine:)`;+ - the `cliLog` channel.+5. **Coverage gaps**, weakest first: `settings` (46%), `clipboard`, `logging` (73%), `terminal` (75%), `demo` (77%), `state` (80%).++### Proposals that need the user's decision (do not build without it)++- **Push notifications** that say what a harness wants, with Yes/No as notification actions. Priya and Sam both named this as the thing that makes the app daily.+- **A one-line Focus header** (`fix-login · studio:web`), pinned while reading history. The branch line would move to the title sheet.+- **Dynamic Type.** `lib/app_shell.dart` pins text scaling to the in-app "Text size", so iOS Larger Text is ignored. Jordan rated this a blocker.+- **Settings duplicates:** "Text size" beside the terminal's "Size", and "App colors" beside "Colors". All four personas asked for one of each. They mirror separate desktop settings, which is why they were kept.+- **Streaming the words into the `>` line while recording.** This is display only; auto-send is unchanged. First check whether the speech engine gives partial results.+- **The pick-up screen.** Two personas called it Find with a headline; they suggest launching into the last harness, or Find.+- **Unseen finished harnesses under "needs you"**, with their last line.+- **Discoverability:** a visible `⌄` on the Focus title, and a visible route to Find and New for Voice Control and Switch Control users.+- **Sentence case** ("New harness", "Open folder"). This touches desktop naming, which uses "New Harness".++### Outside this branch++- **Desktop PR #393** ("Your phones", with Remove, on the Mac) is waiting for the user to merge it.+- **Website `/pair` page:** PR autonomous-ai/autonomous-code#4 needs a `_web` tag to deploy.+- **TestFlight** is blocked until someone is on the release Mac, which has the App Store Connect key. Until then, the phone is a local `devicectl` install only.