Merge pull request #14130 from esengine/docs/release-notes-2.48.0

docs(release): studio 2.48.0 notes
2026-11-07 10:45:59 -10:00 · 2026-10-21 19:01:52 -07:00 · 2026-10-21 18:46:55 -07:00 · 2026-10-21 18:46:38 -07:00 · 2026-10-21 18:14:05 -07:00 · 2026-10-21 18:13:33 -07:00
1365 changed files with 83190 additions and 3675 deletions
@@ -5,6 +5,7 @@
 *.bat text eol=crlf
 *.css text eol=lf
 *.go text eol=lf
+*.golden text eol=lf
 *.html text eol=lf
 *.js text eol=lf
 *.json text eol=lf
@@ -25,6 +26,8 @@
 *.xml text eol=lf
 *.yaml text eol=lf
 *.yml text eol=lf
+Makefile text eol=lf
 .githooks/** text eol=lf
 benchmarks/**/*.sh text eol=lf
 internal/runtime/agent/testdata/perseveration/** -text
+desktop/frontend-next/perf/media/delivery.pdf binary
@@ -179,6 +179,23 @@ jobs:
          REASONIX_RELEASE_CACHE_GUARD: "1"
        run: go test ./...

+      - name: test (Windows composition links)
+        if: env.RUN_STEPS == 'true' && runner.os == 'Windows' && github.event_name == 'pull_request'
+        timeout-minutes: 5
+        shell: bash
+        run: |
+          set -o pipefail
+          go test -count=1 -timeout=3m -json -run '^Test(CaptureDirectoryMaterializesContainedLinks|CaptureDirectoryRefusesUnsafeLinks|CaptureHookFileFlattensContainedLink|MaterializeStillRejectsLinkedRetainedFilesAndRoot|WindowsCompositionJunctions|WindowsLiveSkillJunctions|CompositionRetainsLinkedSkillAcrossRestart|CompositionLinkedSkillRejectsLinkedResources|CompositionLinkedExtensionResources|CompositionLinkedHookResources)$' ./internal/state/agentpreset ./internal/ext/skill ./internal/assembly/boot | tee "$RUNNER_TEMP/composition-links.jsonl"
+          jq -se '
+            ["TestCaptureDirectoryMaterializesContainedLinks", "TestCaptureDirectoryRefusesUnsafeLinks",
+             "TestCaptureHookFileFlattensContainedLink", "TestMaterializeStillRejectsLinkedRetainedFilesAndRoot",
+             "TestWindowsCompositionJunctions", "TestWindowsLiveSkillJunctions", "TestCompositionRetainsLinkedSkillAcrossRestart",
+             "TestCompositionLinkedSkillRejectsLinkedResources", "TestCompositionLinkedExtensionResources",
+             "TestCompositionLinkedHookResources"] as $required |
+            [.[] | select(.Action == "pass") | .Test] as $passed |
+            all(.[]; .Action != "skip") and (($required - $passed) | length == 0)
+          ' "$RUNNER_TEMP/composition-links.jsonl"
+
      # Pull requests run a Windows smoke suite: the packages that actually
      # carry *_windows.go code, the startup/checkpoint packages with portable
      # filesystem contracts, plus cmd/. The full ./... sweep stays on pushes
@@ -244,7 +261,9 @@ jobs:
          WINDOWS_SANDBOX_WAIT_MS: "20000"
        shell: bash
        run: |
-          go test -count=1 -p 4 -timeout=18m -json ./... | tee "$RUNNER_TEMP/full.jsonl" |
+          # internal/assembly/boot alone takes 14-15 minutes on a Windows runner;
+          # the package limit leaves headroom inside the step limit above.
+          go test -count=1 -p 4 -timeout=28m -json ./... | tee "$RUNNER_TEMP/full.jsonl" |
            jq -rj --unbuffered 'select(.Action == "output" and .Test == null) | .Output'

      - name: test (full) failure detail
@@ -0,0 +1,32 @@
+name: Deploy website
+
+# GitHub requires workflow_dispatch to be registered on the default branch.
+# The production implementation is the same workflow path on website.
+on:
+  workflow_dispatch:
+    inputs:
+      release_version:
+        description: "Optional product release version associated with this publication"
+        required: false
+        default: ""
+        type: string
+      release_request:
+        description: "Optional release workflow correlation ID"
+        required: false
+        default: ""
+        type: string
+      studio_version:
+        description: "Studio version that must be present in the generated changelog"
+        required: false
+        default: ""
+        type: string
+
+permissions: {}
+
+jobs:
+  require-website:
+    runs-on: ubuntu-latest
+    steps:
+      - run: |
+          echo "::error::Deploy the website with --ref website; production is restricted to that branch."
+          exit 1
@@ -1302,6 +1302,25 @@ jobs:
            --cache-control "public, max-age=300, stale-if-error=86400"
          echo "Studio catalog -> $VERSION"

+  website:
+    name: publish the Studio website changelog
+    needs: [resolve, publish]
+    if: github.repository == 'esengine/DeepSeek-Reasonix' && needs.resolve.outputs.candidate != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      actions: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: ${{ github.workflow_sha }}
+      - name: Deploy and verify the website changelog
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ needs.resolve.outputs.version }}
+        run: bash scripts/publish-studio-changelog.sh
+
  # A CLI channel that moves while 1.x still publishes would have two lines
  # writing it, so every CLI job waits for this check. It runs no repository code.
  cli-gate:
@@ -147,7 +147,9 @@ jobs:
          node perf/git-panel.mjs
          node perf/session-move-to.mjs
          node perf/shell-refused.mjs
+          node perf/external-origin.mjs
          node perf/rail-search-hold.mjs
+          node perf/rail-toggle-panes.mjs
          node perf/session-move.mjs
          node perf/session-ref.mjs
          node perf/browser-full.mjs
@@ -159,8 +161,11 @@ jobs:
          node perf/context-card-hover.mjs
          node perf/sessquick.mjs
          node perf/sessionrows.mjs
+          node perf/session-row-marker.mjs
+          node perf/session-selected-row.mjs
          node perf/wheel.mjs
          node perf/branch-tooltip.mjs
+          node perf/branch-alignment.mjs
          node perf/branch-menu.mjs
          node perf/image-preview.mjs
          node perf/user-images.mjs
@@ -168,6 +173,7 @@ jobs:
          node perf/addfolder-rest.mjs
          node perf/scroll-jump.mjs
          node perf/add-project-selects.mjs
+          node perf/project-header.mjs
          node perf/setup-defer.mjs
          node perf/narrow.mjs
          node perf/settings-rows.mjs
@@ -176,6 +182,12 @@ jobs:
          node perf/mcp-actions.mjs
          node perf/web-access.mjs
          node perf/peers-settings.mjs
+          node perf/output-cap.mjs
+          node perf/changes-cap.mjs
+          node perf/session-menu-fit.mjs
+          node perf/progress-tail.mjs
+          node perf/trust-wait.mjs
+          node perf/nest-nodes.mjs
          node perf/provider-ports.mjs
          node perf/peer-threads.mjs
          node perf/text-size.mjs
@@ -257,6 +257,7 @@ For advanced CLI usage and configuration, see the **[CLI reference](./docs/CLI.m
  [Capability diagnostics](./docs/CAPABILITY_DIAGNOSTICS.md) ·
  [Recovery and updates](./docs/RECOVERY.md) ·
  [Checkpoints & rewind](./docs/CHECKPOINTS.md)
+- **Agent presets:** [Session Agent compositions](./docs/AGENT_COMPOSITIONS.md)
 - **Engineering & migration:** [Spec](./docs/SPEC.md) ·
  [Task contracts & pause policy](./docs/TASK_CONTRACT.md) ·
  [Tool contract](./docs/TOOL_CONTRACT.md) · [Moving from 1.x to 2.x](./docs/MIGRATING.md) ·
@@ -288,10 +289,10 @@ A small list of folks whose work has shaped Reasonix the most — the current to
 | Contributor | Contributor | Contributor | Contributor |
 | --- | --- | --- | --- |
 | [**SivanCola**](https://github.com/SivanCola) | [**KHG420**](https://github.com/KHG420) | [**ttmouse**](https://github.com/ttmouse) | [**lifu963**](https://github.com/lifu963) |
-| [**HUQIANTAO**](https://github.com/HUQIANTAO) | [**Harbor404**](https://github.com/Harbor404) | [**GTC2080**](https://github.com/GTC2080) | [**mchenziyi**](https://github.com/mchenziyi) |
-| [**Li-Charles-One**](https://github.com/Li-Charles-One) | [**light-front-theory**](https://github.com/light-front-theory) | [**XTLine**](https://github.com/XTLine) | [**eghrhegpe**](https://github.com/eghrhegpe) |
-| [**noreply**](https://github.com/noreply) | [**chuiwenwei**](https://github.com/chuiwenwei) | [**xxoingr**](https://github.com/xxoingr) | [**Bernardxu123**](https://github.com/Bernardxu123) |
-| [**HaoyueQin**](https://github.com/HaoyueQin) | [**BuGlessRB**](https://github.com/BuGlessRB) | [**CVEngineer66**](https://github.com/CVEngineer66) | [**JesonChou**](https://github.com/JesonChou) |
+| [**XTLine**](https://github.com/XTLine) | [**HUQIANTAO**](https://github.com/HUQIANTAO) | [**chuiwenwei**](https://github.com/chuiwenwei) | [**Harbor404**](https://github.com/Harbor404) |
+| [**GTC2080**](https://github.com/GTC2080) | [**mchenziyi**](https://github.com/mchenziyi) | [**Li-Charles-One**](https://github.com/Li-Charles-One) | [**light-front-theory**](https://github.com/light-front-theory) |
+| [**xxoingr**](https://github.com/xxoingr) | [**eghrhegpe**](https://github.com/eghrhegpe) | [**noreply**](https://github.com/noreply) | [**par73e**](https://github.com/par73e) |
+| [**Bernardxu123**](https://github.com/Bernardxu123) | [**Guan0923**](https://github.com/Guan0923) | [**HaoyueQin**](https://github.com/HaoyueQin) | [**BuGlessRB**](https://github.com/BuGlessRB) |
 <!-- reasonix-top-contributors:end -->

 Special thanks to [**Bernardxu123**](https://github.com/Bernardxu123) for designing the project logo and intro video.
@@ -237,6 +237,7 @@ CLI 进阶用法和详细配置见 **[CLI 命令参考](./docs/CLI.zh-CN.md)**
  [能力诊断](./docs/CAPABILITY_DIAGNOSTICS.md) ·
  [恢复与安全模式](./docs/RECOVERY.md) ·
  [Checkpoints 与 rewind](./docs/CHECKPOINTS.md)
+- **Agent 预设：** [会话级组合](./docs/AGENT_COMPOSITIONS.zh.md)
 - **工程与迁移：** [规格](./docs/SPEC.md) ·
  [任务合约与暂停策略](./docs/TASK_CONTRACT.md) ·
  [工具合约](./docs/TOOL_CONTRACT.md) ·
@@ -269,10 +270,10 @@ CLI 进阶用法和详细配置见 **[CLI 命令参考](./docs/CLI.zh-CN.md)**
 | Contributor | Contributor | Contributor | Contributor |
 | --- | --- | --- | --- |
 | [**SivanCola**](https://github.com/SivanCola) | [**KHG420**](https://github.com/KHG420) | [**ttmouse**](https://github.com/ttmouse) | [**lifu963**](https://github.com/lifu963) |
-| [**HUQIANTAO**](https://github.com/HUQIANTAO) | [**Harbor404**](https://github.com/Harbor404) | [**GTC2080**](https://github.com/GTC2080) | [**mchenziyi**](https://github.com/mchenziyi) |
-| [**Li-Charles-One**](https://github.com/Li-Charles-One) | [**light-front-theory**](https://github.com/light-front-theory) | [**XTLine**](https://github.com/XTLine) | [**eghrhegpe**](https://github.com/eghrhegpe) |
-| [**noreply**](https://github.com/noreply) | [**chuiwenwei**](https://github.com/chuiwenwei) | [**xxoingr**](https://github.com/xxoingr) | [**Bernardxu123**](https://github.com/Bernardxu123) |
-| [**HaoyueQin**](https://github.com/HaoyueQin) | [**BuGlessRB**](https://github.com/BuGlessRB) | [**CVEngineer66**](https://github.com/CVEngineer66) | [**JesonChou**](https://github.com/JesonChou) |
+| [**XTLine**](https://github.com/XTLine) | [**HUQIANTAO**](https://github.com/HUQIANTAO) | [**chuiwenwei**](https://github.com/chuiwenwei) | [**Harbor404**](https://github.com/Harbor404) |
+| [**GTC2080**](https://github.com/GTC2080) | [**mchenziyi**](https://github.com/mchenziyi) | [**Li-Charles-One**](https://github.com/Li-Charles-One) | [**light-front-theory**](https://github.com/light-front-theory) |
+| [**xxoingr**](https://github.com/xxoingr) | [**eghrhegpe**](https://github.com/eghrhegpe) | [**noreply**](https://github.com/noreply) | [**par73e**](https://github.com/par73e) |
+| [**Bernardxu123**](https://github.com/Bernardxu123) | [**Guan0923**](https://github.com/Guan0923) | [**HaoyueQin**](https://github.com/HaoyueQin) | [**BuGlessRB**](https://github.com/BuGlessRB) |
 <!-- reasonix-top-contributors:end -->

 特别感谢 [**Bernardxu123**](https://github.com/Bernardxu123) 设计的项目 logo和开场视频。
@@ -413,8 +413,13 @@ moving a number here must not move the promise.
 - Symlinks are recorded by `Lstat`, so a write through one lands outside what
  the walk compares. Confining the resolved target is the sandbox's job.
 - `internal/safety/sandbox` confines writes to the workspace, configured extras, temp
-  and toolchain caches — on macOS and Linux. Windows has no OS-level bash
-  sandbox, so there nothing the host enforces bounds `Writable`.
+  and toolchain caches on macOS and Linux.
+- On Windows a user-enabled write-restricted token bounds the *creation* of files
+  (create, append, overwrite, `mkdir`, HKCU writes, global git config, writes through links).
+- There, deleting or renaming away an existing file is not bounded, and with the
+  setting off nothing the host enforces bounds `Writable`.
+- The caches a command may write can be poisoned for the user's later unsandboxed
+  builds, on every platform.
 - The governed host authorities are a *named* set — ssh-agent, docker, podman.
  DBus, Wayland, X11, gpg-agent, keyrings and arbitrary sockets stay reachable,
  so the claim is "these endpoints are governed", never "host IPC is isolated".
@@ -460,9 +465,13 @@ stop a connect. Possession is not authority: the key can be unreadable while an
 agent still signs with it.

 A protection claim exists only where a backend has a demonstrated enforcement
-primitive for that dimension. Unsupported dimensions stay explicitly unsupported
-— Windows currently enforces none of the three — because a claim that outruns
-its enforcement is worse than an absent one: it is believed.
+primitive for that dimension. Unsupported dimensions stay explicitly unsupported,
+because a claim that outruns its enforcement is worse than an absent one: it is
+believed.
+
+Windows enforces Integrity on file creation only, when the user turns it on.
+Deletion and rename, Confidentiality and Authority (the named pipes of ssh-agent
+and docker, COM and RPC services) are not enforced there.

 **Known unmeasured surface — macOS host-mediated delegation:** Apple Events and
 Mach-service lookup are not denied by the current allow-default profile. Prior
@@ -0,0 +1,22 @@
+# Build output and local tooling state.
+build/
+.gradle/
+.kotlin/
+local.properties
+*.iml
+.idea/
+
+# The signing key and the file that names it.
+#
+# A key is not part of the project: it is the identity one person ships under,
+# and publishing it would let anyone else sign an APK that installs over
+# everyone's. Neither the keystore nor its password belongs in version control.
+# `app/build.gradle` reads both from here when present and falls back to the
+# debug key when they are not, so a fresh clone builds without them.
+keystore/
+
+# Build inputs, produced by scripts/ before Gradle runs.
+# jniLibs/ holds the cross-compiled kernel, assets/page/ the built
+# frontend. assets/LICENSE is hand-placed and stays tracked.
+app/src/main/jniLibs/
+app/src/main/assets/page/
@@ -0,0 +1,216 @@
+---
+owner: @esengine
+backup: @SivanCola
+status: active
+reviewed: 2026-10-20
+---
+
+# Reasonix Mobile — the Android shell
+
+Runs Reasonix as an Android app: the kernel ships inside the APK and starts on the
+device, the interface is the same `desktop/frontend-next` build the desktop Studio
+serves, and the agent reaches servers over SSH.
+
+This file is for people building it. What a person installing it needs — what it
+does, how to pair with a computer, what it cannot do — belongs in the release
+notes.
+
+## One command
+
+```bash
+./scripts/build.sh release     # or debug
+```
+
+Three steps, in this order:
+
+1. `build-kernel.sh` → `app/src/main/jniLibs/arm64-v8a/libreasonix.so`
+2. `sync-page.sh` → `app/src/main/assets/page/`
+3. `./gradlew assembleRelease`
+
+Output: `app/build/outputs/apk/release/app-release.apk`
+
+The kernel and the page are **inputs to packaging, not Gradle build steps**.
+Running `gradle assembleRelease` on its own fails on purpose and names the script
+that produces whichever input is missing (`requireBuildInputs` in
+`app/build.gradle`): an APK with no kernel in it should not be buildable by
+accident.
+
+## Requirements
+
+| Component | Version |
+| --- | --- |
+| JDK | 21 (17 also works) |
+| Android SDK | `platforms;android-35`, `build-tools;35.0.0`, `platform-tools` |
+| Gradle | the committed wrapper, 8.14.3 (for AGP 8.11.1) |
+| Go | 1.26+ |
+| Node / pnpm | Node 24+ / pnpm 10 |
+
+```bash
+export ANDROID_HOME="$HOME/Android/Sdk"
+export ANDROID_SDK_ROOT="$ANDROID_HOME"
+export JAVA_HOME="/path/to/jdk-21"
+export PATH="$PATH:$(go env GOPATH)/bin"
+```
+
+`ANDROID_HOME` is the one thing nothing sets for you.
+
+## Scripts
+
+| Script | What it does |
+| --- | --- |
+| `build.sh [debug\|release]` | The whole chain |
+| `build-kernel.sh` | Cross-compiles the kernel only (`GOOS=android GOARCH=arm64 CGO_ENABLED=0`) |
+| `sync-page.sh` | Builds the frontend, copies `dist/` into assets, copies `LICENSE` |
+| `verify-page.sh` | **No phone needed**: starts the real kernel against the packaged page |
+| `run.sh [debug\|release]` | `adb install`, launch, follow the log |
+
+`verify-page.sh` is the one to run after a change: it starts the kernel with the
+same arguments `Kernel.kt` uses (`--auth token`, `--token-file`, `--port-file`,
+`-page`) and checks that it binds a port and answers 200. Without a device, that
+is as deep as the chain can be verified.
+
+## Where the code is
+
+| File | Owns |
+| --- | --- |
+| `MainActivity.kt` | The WebView, the back gesture, downloads, external links, renderer restart |
+| `Kernel.kt` | Unpacking the page, starting and stopping the kernel, waiting for the port, health probes, logs, the workspace directory |
+| `KernelService.kt` | The foreground service that keeps a long turn alive |
+| `NativeBridge.kt` | `@JavascriptInterface`: what the page may ask the phone for |
+| `BrowserShellServer.kt` | Loopback HTTP server the kernel's browser tools drive the overlay WebView through |
+| `Downloader.kt` | Writing a kernel-produced file through the system document picker |
+
+The page reaches the shell through `window.reasonixHost` and `ReasonixNative`,
+defined in `desktop/frontend-next/src/port/host.ts` (`AndroidHost`).
+
+**Phone and desktop share one page build.** What differs only on a phone is
+decided at runtime, not by a second set of components. `phoneShell()` in
+`src/port/host.ts` and the `[data-shell="android"]` selector in `mobile.css` both
+read `<html data-shell="android">`, which `index.html` sets before the bundle
+loads.
+
+One attribute feeding both is what keeps style and components from disagreeing
+about what a phone is.
+
+## What the page may ask the phone for
+
+`NativeBridge` is reachable from whatever document the WebView holds, so every
+method that touches the device asks `trusted()` first.
+
+The activity answers by comparing the **main frame's** origin against the
+kernel's and against the one paired computer the person scanned a code for. A
+page that navigated elsewhere is not trusted, even though it may still hold the
+object.
+
+Five methods answer without the check — `version`, `systemTheme`, `safeArea`,
+`setLayerOpen`, `setRunning` — because they report back what the page already
+knows about its own window and grant nothing.
+
+`openInApp(url)` is the pairing decision, not a navigation one: it loads a URL in
+this window only for the origin the scanner just returned, and only once.
+Without that, any page holding the kernel origin could hand itself the bridge.
+
+External links leave through the browser. A non-web scheme is routed to the
+system only for `mailto:` and `tel:`; everything else is dropped, because an
+`intent://` URL can start an arbitrary exported activity with caller-supplied
+extras.
+
+## Permissions, and what they cost
+
+`MANAGE_EXTERNAL_STORAGE` — opening a folder on the phone as a workspace. The
+kernel is a Go binary: it opens real paths with `open(2)`, and SAF hands back a
+`content://` URI it cannot open.
+
+Requested from the folder-picker action, never at launch. Android shows no dialog
+for it and opens system settings instead.
+
+**There is no OS-level sandbox around this kernel.** The PR sets the sandbox to
+off on Android, so confining the agent to the chosen folder is Reasonix's own
+write-root check and nothing else. A shell tool with all-files access can reach
+all shared storage.
+
+`REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` — Doze freezes the app group, which stops
+a turn that is still running. Asked once when a turn actually runs, never at
+launch, and the person can refuse. Refusing costs battery life during long turns
+and nothing else.
+
+**Google Play restricts this permission**: fine for a sideloaded build, a
+store-policy risk if this is ever listed.
+
+`FOREGROUND_SERVICE` / `FOREGROUND_SERVICE_DATA_SYNC` — keeping the kernel alive
+while the screen is off. `dataSync` is capped per 24 hours from Android 15. It is
+the closest honest description of "an agent is working".
+
+`CAMERA` — reading the pairing code a computer shows. Requested when the person
+asks to scan, never at launch. `ScanActivity` is not exported.
+
+`READ_EXTERNAL_STORAGE` / `WRITE_EXTERNAL_STORAGE` — the same folder walk below
+API 33. `maxSdkVersion`-gated; above 33 they are superseded by the permission
+above.
+
+`allowBackup=false` with explicit extraction rules, so a `keystore` or a token in
+app storage never leaves the device in a cloud backup.
+
+## Cleartext HTTP
+
+The kernel serves its page on `127.0.0.1:<port>`, and a paired computer serves
+the same page over its LAN address. Both are plain HTTP.
+
+Neither address can be written into a `network-security-config`: the port is
+chosen at start, the LAN address at scan time, and the format matches literals
+and domains, not subnets.
+
+So the config permits cleartext and the boundary is in the code instead.
+`shouldOverrideUrlLoading` sends every other http(s) origin to the browser, and
+the bridge answers only the kernel and the just-paired computer. A plaintext page
+on the LAN cannot become the document holding the bridge.
+
+## What goes into the APK
+
+| Content | Size | Why it is shaped this way |
+| --- | --- | --- |
+| `lib/arm64-v8a/libreasonix.so` | 45 MB | Go static binary, stripped. It is a `.so` rather than a file in `assets/` because only `nativeLibraryDir` is guaranteed executable — a binary copied to app storage fails on a device whose data partition is mounted `noexec`. |
+| `assets/page/` | 14 MB | The frontend build, including the Inter and Noto Sans SC fonts, `noCompress` |
+| `assets/LICENSE` | 1 KB | The repository's MIT licence, verbatim. MIT requires the notice and the licence text to accompany a binary distribution. |
+
+`assets/LICENSE` is generated by `sync-page.sh` from the repository's root
+`LICENSE`, not committed a second time: a checked-in copy drifts when the root
+file is updated.
+
+It sits in `assets/` rather than `assets/page/` because that directory is removed
+and rebuilt on every build.
+
+A release APK is about 31 MB.
+
+## Building
+
+**The Gradle wrapper is committed**, jar and all. `build.sh` refuses to run
+without `gradlew` rather than generating one from whatever `gradle` is on `PATH`:
+the dependency versions are part of the build.
+
+`gradle-wrapper.properties` pins `distributionSha256Sum`, so a mirror that serves
+a different distribution zip fails verification instead of being unpacked and
+run. Dependency repositories are the official ones only — a mirror belongs in a
+user-level init script.
+
+**Signing.** A release with no key configured comes out **unsigned**
+(`app-release-unsigned.apk`) with a warning. It used to fall back to the debug
+key, which produced an artifact that looked shippable and was signed by a
+per-machine key nobody chose: it could not install over the previous build.
+
+Point the build at a real key by writing `keystore/keystore.properties`
+(`storeFile`, `storePassword`, `keyAlias`, and optionally `keyPassword`) or by
+setting the matching `REASONIX_KEYSTORE*` environment variables. Key material
+stays out of the repository and out of build logs.
+
+Debug builds always use the debug key. Signing a debug build with the release key
+would let anyone who can read the keystore produce a build that installs over the
+shipped one under the same signature.
+
+**Non-ASCII checkout paths.** AGP refuses to build under a path with non-ASCII
+characters on Windows unless `android.overridePathCheck=true` is set. That is a
+property of one machine's disk layout, not of this project, so it is not in the
+repository's `gradle.properties`.
+
+Set it in a user-level `~/.gradle/gradle.properties` or pass
+`-Pandroid.overridePathCheck=true`.
@@ -0,0 +1,242 @@
+// The app module.
+//
+// Two things ship inside the APK and neither is fetched at runtime: the kernel
+// binary, and the built page it serves. Bundling the page is what makes the app
+// work offline and start instantly; bundling the kernel is what lets it run
+// `reasonix serve` on the phone itself, which is the whole point — the agent
+// starts locally and reaches the server over SSH, so the interface, the model
+// catalogue and the credentials all live on the phone.
+//
+// The kernel is placed as `jniLibs/arm64-v8a/libreasonix.so`, not under
+// `assets/`. That is not a trick for its own sake: Android permits executing a
+// file under `nativeLibraryDir` and nothing under `filesDir` has that
+// guarantee, so a binary shipped the ordinary way would have to be copied out
+// and made executable at runtime — which fails outright on a device mounted
+// noexec, and fails confusingly on the ones that are merely unusual. `scripts/
+// build-kernel.sh` writes it there; the name is fixed by the packaging rules.
+plugins {
+    id "com.android.application"
+    id "org.jetbrains.kotlin.android"
+}
+
+// One version, read by the About screen and the update check.
+def versionMajor = 2
+def versionMinor = 0
+def versionPatch = 0
+def versionBuild = 1
+
+// Where the two build inputs are expected. Both are produced from the checkout
+// beside this module, by the scripts named in each message.
+def upstream = rootProject.file("..")
+def pageDir = new File(projectDir, "src/main/assets/page")
+def kernelSo = new File(projectDir, "src/main/jniLibs/arm64-v8a/libreasonix.so")
+
+android {
+    namespace "io.reasonix.mobile.app"
+    compileSdk 35
+
+    defaultConfig {
+        applicationId "io.reasonix.mobile.app"
+        minSdk 26
+        // 35: the API level this app is actually built and tested against.
+        //
+        // It was briefly lowered to 26 while chasing an install failure that
+        // turned out to be a package-name collision with an unrelated app on the
+        // user's phone — the signature error named the wrong cause. Nothing about
+        // the target level ever caused it, so it goes back to the level the code
+        // is really written for.
+        //
+        // One consequence to keep in mind: from 35, Android 15 forces the window
+        // edge-to-edge and ignores a request to lay out inside the safe area. The
+        // window therefore *is* drawn under the status bar and the home indicator,
+        // and the only correct answer is for the page to pad itself — which is
+        // what `MainActivity` feeds real inset values for, since a WebView does
+        // not implement `env(safe-area-inset-*)`.
+        targetSdk 35
+        versionCode versionMajor * 10000 + versionMinor * 100 + versionPatch * 10 + versionBuild
+        versionName "${versionMajor}.${versionMinor}.${versionPatch}"
+
+        // The kernel is built for arm64 only, so every other ABI would ship an
+        // APK that installs and then cannot start. Naming the one real ABI keeps
+        // the store listing and the installer honest.
+        ndk {
+            abiFilters "arm64-v8a"
+        }
+
+        resourceConfigurations += ["zh", "en"]
+    }
+
+    // Android identifies an app by package name *and* signing key: an APK signed
+    // with a different key is not an update, it is an impostor, and the
+    // installer refuses it with "the signature does not match the installed
+    // app". Gradle's default release key is the debug key in the user's home
+    // directory, which is per-machine, so a build made on a second computer
+    // could never be installed over one made on the first.
+    //
+    // Whoever ships a build therefore pins a key — and that key is theirs, not
+    // the project's. It lives beside the checkout, in `keystore/`, which is
+    // ignored; so does the file naming it. A checkout without either signs with
+    // the debug key instead, which is what a contributor building locally wants
+    // and is what the README tells them to expect. Point the build at a real key
+    // by writing `keystore/keystore.properties` (storeFile, storePassword,
+    // keyAlias) or by setting REASONIX_KEYSTORE / REASONIX_KEYSTORE_PASSWORD /
+    // REASONIX_KEY_ALIAS.
+    def keyProperties = new Properties()
+    def keyPropertiesFile = rootProject.file("keystore/keystore.properties")
+    if (keyPropertiesFile.exists()) {
+        keyPropertiesFile.withInputStream { keyProperties.load(it) }
+    }
+    def keyStorePath = keyProperties.getProperty("storeFile") ?: System.getenv("REASONIX_KEYSTORE")
+    def keyStorePassword = keyProperties.getProperty("storePassword") ?: System.getenv("REASONIX_KEYSTORE_PASSWORD")
+    // The key's own password is a separate fact from the store's. PKCS#12 keystores
+    // almost always use one password for both, so falling back to the store's
+    // password keeps those working — but assuming they are equal is how a keystore
+    // that separates them gets a build failure at signing time, after the work is
+    // done, with an error that does not say which of the two was wrong.
+    def keyPasswordValue = keyProperties.getProperty("keyPassword") ?: System.getenv("REASONIX_KEY_PASSWORD") ?: keyStorePassword
+    def keyAliasName = keyProperties.getProperty("keyAlias") ?: System.getenv("REASONIX_KEY_ALIAS")
+    def haveReleaseKey = keyStorePath && keyStorePassword && keyAliasName &&
+            rootProject.file(keyStorePath).exists()
+
+    signingConfigs {
+        if (haveReleaseKey) {
+            releaseKey {
+                storeFile rootProject.file(keyStorePath)
+                storePassword keyStorePassword
+                keyAlias keyAliasName
+                keyPassword keyPasswordValue
+                // v1 is not optional here. Android 7+ reads v2 and ignores v1, so
+                // a v2-only APK installs on a modern phone — and then fails on the
+                // compatibility layers older devices and HarmonyOS' 卓易通 run,
+                // which know only the JAR signature and report its absence as a
+                // signature *mismatch*. Signing both is what makes one APK install
+                // everywhere.
+                enableV1Signing = true
+                enableV2Signing = true
+                enableV3Signing = true
+            }
+        }
+    }
+
+    // Nothing native is compiled here — the one .so is a prebuilt the kernel
+    // script writes — so the external native build is left alone entirely.
+    buildTypes {
+        debug {
+            applicationIdSuffix ".debug"
+            versionNameSuffix "-debug"
+            // The debug key, always. Signing a debug build with the release key
+            // would mean anyone who can read the release keystore can produce a
+            // build that installs over the shipped one under the same signature,
+            // and it buys nothing: the debug package is suffixed `.debug`, so the
+            // two already install side by side.
+        }
+        release {
+            // The kernel is a stripped Go binary and the page is minified, but
+            // the Kotlin shell still benefits and shipping the shrunk build is
+            // how a size regression gets noticed.
+            minifyEnabled true
+            shrinkResources true
+            proguardFiles getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro"
+            // A release with no key of its own comes out *unsigned*
+            // (`app-release-unsigned.apk`). It used to fall back to the debug key
+            // so the artifact would install, which produced a release that looked
+            // shippable and was signed by a per-machine key nobody chose: it could
+            // not be installed over the previous build, and every machine made a
+            // different one. An unsigned artifact says what it is.
+            if (haveReleaseKey) {
+                signingConfig signingConfigs.releaseKey
+            } else {
+                logger.warn(
+                    "release build has no signing key: producing an unsigned APK. " +
+                        "Write keystore/keystore.properties (storeFile, storePassword, keyAlias) " +
+                        "or set REASONIX_KEYSTORE / REASONIX_KEYSTORE_PASSWORD / REASONIX_KEY_ALIAS."
+                )
+            }
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+
+    buildFeatures {
+        // AGP 8 stops generating BuildConfig unless asked. `Kernel` reads the
+        // version name and code out of it to decide whether the bundled page
+        // needs unpacking, so it is asked for.
+        buildConfig = true
+    }
+
+    packaging {
+        jniLibs {
+            // `extractNativeLibs=true`: the kernel must exist as a real file on
+            // disk to be executed, and an uncompressed-and-mmap'd .so is not
+            // one. This is the only reason the flag is on.
+            useLegacyPackaging true
+        }
+        resources {
+            excludes += ["META-INF/*.version", "META-INF/*.kotlin_module", "kotlin/**", "DebugProbesKt.bin"]
+        }
+    }
+
+    // The page is read out of assets by `Kernel.publish`, not by the resource
+    // system, so it is not compressed — a page is already-compressed text and
+    // shrinking it again only costs startup time.
+    androidResources {
+        noCompress += ["json", "woff2", "ttf", "woff", "txt", "svg"]
+    }
+
+    lint {
+        abortOnError true
+        warningsAsErrors false
+        checkReleaseBuilds true
+    }
+}
+
+dependencies {
+    implementation "androidx.core:core-ktx:1.15.0"
+    implementation "androidx.appcompat:appcompat:1.7.0"
+    implementation "androidx.activity:activity-ktx:1.9.3"
+    implementation "androidx.webkit:webkit:1.12.1"
+    implementation "androidx.lifecycle:lifecycle-runtime-ktx:2.8.7"
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0"
+
+    // Scanning the pairing code a computer shows.
+    //
+    // CameraX for the preview and the frame stream, ZXing for the decode, and
+    // deliberately not ML Kit: this app installs on phones whose HarmonyOS
+    // compatibility layer has no Google Play Services, so a decoder that needs
+    // GMS would work on the developer's phone and fail on the user's. ZXing
+    // core is pure Java with no runtime dependency at all, which is what makes
+    // the scanner work on both.
+    implementation "androidx.camera:camera-core:1.4.1"
+    implementation "androidx.camera:camera-camera2:1.4.1"
+    implementation "androidx.camera:camera-lifecycle:1.4.1"
+    implementation "androidx.camera:camera-view:1.4.1"
+    implementation "com.google.zxing:core:3.5.3"
+}
+
+// Fail before the packaging step with something a person can act on, rather
+// than shipping an APK whose kernel is missing or whose page is a directory the
+// build never filled. The two messages name the script that produces each.
+tasks.register("requireBuildInputs") {
+    doFirst {
+        if (!kernelSo.exists()) {
+            throw new GradleException(
+                "内核二进制缺失：${kernelSo}\n先运行 ./scripts/build-kernel.sh（在 android/ 目录下）交叉编译内核。")
+        }
+        if (!pageDir.exists() || !new File(pageDir, "index.html").exists()) {
+            throw new GradleException(
+                "前端页面缺失：${pageDir}/index.html\n先运行 ./scripts/sync-page.sh（在 android/ 目录下）构建并同步页面。")
+        }
+    }
+}
+
+tasks.configureEach { task ->
+    if (task.name.startsWith("merge") && (task.name.contains("Assets") || task.name.contains("JniLibFolders"))) {
+        task.dependsOn("requireBuildInputs")
+    }
+}
@@ -0,0 +1,32 @@
+# R8 rules for the shell.
+#
+# There is very little to keep here, and that is the point: the app's own code
+# is reached from the manifest and from Android's own callbacks, both of which
+# R8 already traces, and nothing in it is loaded reflectively. What follows is
+# the two places where a name is looked up rather than called.
+
+# The WebView's JavaScript bridge, if one is ever added, is resolved by name on
+# the Java side and by the string the page uses. Keeping annotated members makes
+# that survive shrinking rather than failing at runtime with a method-not-found
+# that only shows up on a release build.
+-keepclassmembers class * {
+    @android.webkit.JavascriptInterface <methods>;
+}
+
+# The Kernel's child process is started by absolute path, and its own log is
+# read as text; neither is reflective, so nothing else needs keeping.
+
+# Line numbers make a stack trace from a release build readable, which is the
+# only way a crash report from a phone can be acted on.
+-keepattributes SourceFile,LineNumberTable
+-renamesourcefileattribute SourceFile
+
+# Kotlin's `@Metadata` annotation is present on every class the compiler touched
+# and nothing in this app reflects over it. It is tempting to `-assumenosideeffects`
+# it away, and that was tried: any pattern broad enough to name its members also
+# matches the methods every class inherits from `Object` — `equals`, `hashCode`,
+# `toString` — and R8 then treats those as removable, which is a silent
+# behaviour change for a few kilobytes. Left as a warning suppression instead:
+# the annotation is dropped from the shrunk output anyway, because nothing reads
+# it.
+-dontwarn kotlin.Metadata
@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  The shell's manifest.
+
+  There is no INTERNET-adjacent permission beyond INTERNET itself: the page and
+  the kernel talk over loopback, and reaching a server is the kernel's job over
+  a socket it owns. Reading and writing files goes through the system's document
+  picker (SAF), which hands back a grant for one file at a time — so no
+  storage permission is declared and none is needed.
+
+  `usesCleartextTraffic` is off here, and cleartext is re-enabled in the network
+  security config only because the kernel serves its page on `127.0.0.1` and a
+  paired computer serves the same page over its LAN address — both plain HTTP.
+  The config says what that costs and what bounds it.
+-->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <!-- Only to tell the person the kernel is still running while the screen is
+         off; it is a foreground service with a dismissible notification, not a
+         background wake-up. -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <!-- From API 34 every foreground-service *type* needs its own permission as
+         well as the general one: naming dataSync in the manifest without asking
+         for it is a SecurityException at startForeground, on the one code path
+         that keeps a long task alive. -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <!-- Only to read the pairing code a computer shows. Requested at the
+         moment the person asks to scan, never at launch. -->
+    <uses-permission android:name="android.permission.CAMERA" />
+    <!-- The kernel is a child process, and a task left running is one the person
+         expects to finish with the screen off. Android's own doze can freeze the
+         whole app group instead, which is what the shell asks to be exempt from
+         — once, when a turn is actually running, never at launch. It is a
+         request the person can refuse, and refusing it only costs battery life
+         during a long turn. -->
+    <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
+    <!-- Every-file access, for opening a folder on this phone as a workspace.
+         The kernel is a plain Go binary: it opens paths with `open(2)`, and a
+         document URI is not a path it can open. SAF would hand back exactly
+         that unusable URI, so the one honest permission is the broad one —
+         granted by the person in system settings, which is the only place
+         Android offers it. Nothing here reads storage for any other purpose. -->
+    <uses-permission
+        android:name="android.permission.MANAGE_EXTERNAL_STORAGE"
+        tools:ignore="ScopedStorage" />
+    <!-- Below API 33 the same folder walk needs the older pair; from 33 they are
+         superseded by the permission above and asking for them would be a lie. -->
+    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
+    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="29" />
+
+    <!-- A phone without a touchscreen cannot drive this interface; saying so
+         keeps the listing honest rather than letting it install on a TV. -->
+    <uses-feature android:name="android.hardware.touchscreen" android:required="true" />
+    <!-- The camera is optional: a phone without one is still a fine client for
+         a kernel it already knows, and it can still pair by opening the link the
+         computer shows. Requiring it would take the app off those devices. -->
+    <uses-feature android:name="android.hardware.camera" android:required="false" />
+    <uses-feature android:name="android.hardware.camera.autofocus" android:required="false" />
+
+    <application
+        android:name=".App"
+        android:allowBackup="false"
+        android:dataExtractionRules="@xml/data_extraction_rules"
+        android:fullBackupContent="false"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:networkSecurityConfig="@xml/network_security_config"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.Reasonix"
+        android:usesCleartextTraffic="false"
+        tools:targetApi="35">
+
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:configChanges="orientation|screenSize|screenLayout|keyboardHidden|uiMode|density|fontScale|smallestScreenSize"
+            android:launchMode="singleTask"
+            android:windowSoftInputMode="adjustResize"
+            android:theme="@style/Theme.Reasonix">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+
+        <!-- The kernel outlives the screen: a turn that takes minutes would
+             otherwise be killed when the phone is pocketed. The service is
+             `stopWithTask="false"` so swiping the app away ends it deliberately
+             rather than silently, and `foregroundServiceType="dataSync"` is the
+             closest honest description of "an agent is working". -->
+        <service
+            android:name=".KernelService"
+            android:exported="false"
+            android:foregroundServiceType="dataSync"
+            android:stopWithTask="false" />
+
+        <!-- Reading the pairing code a computer shows. Its own activity rather
+             than a dialog, because the camera preview needs the whole screen to
+             be worth pointing at anything. Not exported: only this app starts
+             it, and a scanner another app could open is one that could be made
+             to read a code on someone else's behalf. -->
+        <activity
+            android:name=".ScanActivity"
+            android:exported="false"
+            android:screenOrientation="portrait"
+            android:theme="@style/Theme.Reasonix.Scan" />
+    </application>
+</manifest>
@@ -0,0 +1,59 @@
+package io.reasonix.mobile.app
+
+import android.app.Application
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.content.Context
+
+/**
+ * The process-wide facts this app needs.
+ *
+ * The kernel is one child process, so there is exactly one of it no matter how
+ * many activities exist: it is held here, lazily, and the activity and the
+ * service both reach the same instance. Nothing else is stored — the theme, the
+ * language and every preference belong to the page and live in its localStorage.
+ */
+class App : Application() {
+
+    /**
+     * The kernel, created on first use.
+     *
+     * Lazy rather than eager so that merely launching the process to answer a
+     * notification does not unpack a 15MB page.
+     */
+    val kernel: Kernel by lazy { Kernel(this) }
+
+    override fun onCreate() {
+        super.onCreate()
+        createChannel()
+    }
+
+    /**
+     * A channel the person can mute without muting the app, and one they can
+     * find: an agent that runs for minutes on a phone has to say so somewhere
+     * the system will not kill, and a notification is the only place Android
+     * offers. `IMPORTANCE_MIN` because the notification is a receipt, not an
+     * interruption — the work it reports is on another machine.
+     */
+    private fun createChannel() {
+        // No SDK_INT guard: minSdk is 26, which is the release NotificationChannel
+        // arrived in, so every device this app installs on has it.
+        val manager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+        if (manager.getNotificationChannel(CHANNEL_KERNEL) != null) return
+        val channel = NotificationChannel(
+            CHANNEL_KERNEL,
+            getString(R.string.channel_kernel),
+            NotificationManager.IMPORTANCE_MIN,
+        ).apply {
+            description = getString(R.string.channel_kernel_desc)
+            setShowBadge(false)
+            enableVibration(false)
+            setSound(null, null)
+        }
+        manager.createNotificationChannel(channel)
+    }
+
+    companion object {
+        const val CHANNEL_KERNEL = "reasonix-kernel"
+    }
+}
@@ -0,0 +1,699 @@
+package io.reasonix.mobile.app
+
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.os.Handler
+import android.os.Looper
+import android.util.Base64
+import android.util.Log
+import android.webkit.WebView
+import org.json.JSONArray
+import org.json.JSONObject
+import java.io.BufferedInputStream
+import java.io.ByteArrayOutputStream
+import java.io.OutputStream
+import java.net.ServerSocket
+import java.net.Socket
+import java.net.SocketException
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * The kernel's browser, as a loopback HTTP server.
+ *
+ * The Go kernel (`internal/platform/browser/shell.go`) drives a WebView by
+ * POSTing JSON to a handful of paths on 127.0.0.1. This class is the other end
+ * of that conversation: it accepts connections on a random port, parses the
+ * minimal HTTP the kernel sends, and translates each path into an operation on
+ * the overlay WebView.
+ *
+ * The server is deliberately tiny — no connection pooling, no keep-alive, no
+ * chunked encoding — because the kernel is its only client and sends one
+ * request per connection. A `ServerSocket` accept loop on a daemon thread is
+ * the whole transport; each request is handled synchronously on its own thread.
+ *
+ * WebView operations must run on the UI thread. Each handler posts to the main
+ * looper and waits on a latch, with a timeout that bounds the worst case (a
+ * page that hangs the JS thread) to something the kernel's own 30-second client
+ * timeout will not outlast.
+ *
+ * Memory note on `/screenshot`: a full-page `WebView.draw` into an ARGB_8888
+ * bitmap at device resolution can reach tens of MB for a long page. The bitmap
+ * is downsampled by a factor of 2 in each dimension before PNG encoding, which
+ * keeps the peak allocation under ~10 MB for a typical 1080p viewport. The
+ * original is recycled immediately after the downsample.
+ */
+/** One thing a page asked the network for, as the WebView's request
+ *  interceptor reports it. The interceptor is handed the method and the URL
+ *  and nothing about the response, so a caller may show exactly this much and
+ *  must not read it as a completed exchange. */
+data class BrowserRequest(val method: String, val url: String, val kind: String)
+
+class BrowserShellServer(
+    /** The overlay WebView, when one already exists. The routes that act on an
+     *  open page — back, forward, reload, close — use this: with no page there
+     *  is nothing to act on, and creating one to do nothing to it would start a
+     *  renderer nobody asked for. */
+    private val existingView: () -> WebView?,
+    /** The overlay WebView, created on first use. The routes that drive a page
+     *  use this, because the kernel can open one before the panel has ever been
+     *  shown: the page's own panel asks for the view when it is displayed, and
+     *  an agent's `browser_open` can arrive first. Requiring the view to exist
+     *  already answered every such call with "browser view not ready", which
+     *  reads as a broken engine rather than as a view that was not created yet.
+     *  Called on the UI thread. */
+    private val ensureView: () -> WebView,
+    /** Why the page in the view is the browser's own error page rather than a
+     *  site, as `(url, chromium error)`; null when the last load succeeded.
+     *  `/read` asks this, because extracting `innerText` from the error page
+     *  returns the browser's own "this page could not be loaded" notice, which
+     *  the kernel would hand to the model as though the site had said it. */
+    private val loadFailure: () -> Pair<String, String>? = { null },
+    /** Begin a navigation: forget the load failure recorded for the page being
+     *  left, drop its request list, and start the wait a following `/read`
+     *  joins. Called on the UI thread, before the new address is loaded, so the
+     *  wait is in place before any callback for the new page can fire. */
+    private val startNavigation: () -> Unit = {},
+    /** What the page currently in the view has asked the network for, oldest
+     *  first. The WebView reports a request's method and URL to its interceptor
+     *  but nothing about the response, so that is all a caller may show. */
+    private val requests: () -> List<BrowserRequest> = { emptyList() },
+    /** Wait for the navigation last asked for to settle — the page arrived, or
+     *  its load failed — up to the given milliseconds. Called on the request's
+     *  own thread, never the UI thread: the settle is signalled from the UI
+     *  thread, so waiting on it there would deadlock. `/load` starts a
+     *  navigation and returns before the page has been visited; without this a
+     *  `/read` right behind it still sees the URL of the page before, and a
+     *  failure recorded for that page was handed back as the new one's answer. */
+    private val awaitNavigation: (Long) -> Unit = {},
+) {
+
+    companion object {
+        private const val TAG = "BrowserShellServer"
+
+        /** How long a UI-thread operation may take before the handler gives up.
+         *  The kernel's client timeout is 30 s; staying under it means the kernel
+         *  sees a clean error rather than a dropped connection. */
+        private const val UI_TIMEOUT_MS = 25_000L
+
+        /** The maximum text `/read` returns. Matches the kernel's `maxReadText`
+         *  (400 << 10). The shell truncates here and says so, rather than letting
+         *  the kernel truncate silently. */
+        private const val MAX_READ_TEXT = 400 * 1024
+
+        /** Screenshot downsample factor. 2 means half width and half height. */
+        private const val SCREENSHOT_SCALE = 2
+
+        /** The address the kernel dials. Both ends must agree on the family:
+         *  see [start] for what goes wrong when they do not. */
+        private const val LOOPBACK_V4 = "127.0.0.1"
+
+        /** How long `/read` waits for a navigation it follows to settle before
+         *  reading whatever the view is on. A page that never finishes loading
+         *  must not hold the tool call open to the kernel's own timeout. */
+        private const val NAV_SETTLE_MS = 10_000L
+
+        /** How long `/read` then waits for the page's own script to answer.
+         *  `NAV_SETTLE_MS + READ_SCRIPT_MS` has to stay under [UI_TIMEOUT_MS],
+         *  and that under the kernel's 30-second client timeout: a read that
+         *  waited out both budgets would outlast the caller, which would see a
+         *  dropped connection instead of this shell's answer. 10 + 15 = 25 s. */
+        private const val READ_SCRIPT_MS = 15_000L
+    }
+
+    @Volatile
+    private var serverSocket: ServerSocket? = null
+
+    /** The port the server is listening on. Valid after [start] returns. */
+    @Volatile
+    var port: Int = 0
+        private set
+
+    /**
+     * The bearer credential every request must carry. Minted by the activity
+     * and handed to the kernel through the child's environment, so the server
+     * answers only the process this shell started.
+     *
+     * A phone's loopback is not a boundary: any other app may connect to
+     * 127.0.0.1, and the routes here run script in and read text out of
+     * whatever page is loaded. Binding to `getLoopbackAddress()` keeps other
+     * machines out but not other apps, so the credential is what makes "only
+     * the kernel this shell started" true.
+     */
+    @Volatile
+    var token: String = ""
+        private set
+
+    private val mainHandler = Handler(Looper.getMainLooper())
+
+    /**
+     * Start listening on 127.0.0.1 with an ephemeral port. The port is available
+     * via [port] immediately after this returns, and the credential the kernel
+     * must present via [token].
+     */
+    fun start() {
+        token = newToken()
+        // The loopback address is spelled out as IPv4, not taken from
+        // `InetAddress.getLoopbackAddress()`. That call is allowed to answer
+        // either family and Android's libcore answers IPv6 (`::1`), while the
+        // kernel's client is hardcoded to `http://127.0.0.1:<port>`
+        // (`internal/assembly/boot/browser.go`). A socket bound to `::1` does
+        // not answer a dial to `127.0.0.1`, so every browser call failed with
+        // "connection refused" while the port was bound and reported — the
+        // failure looked like a server that never started. Both ends have to
+        // name the same family, and IPv4 is the one the kernel names.
+        val ss = ServerSocket(0, 16, java.net.InetAddress.getByName(LOOPBACK_V4))
+        serverSocket = ss
+        port = ss.localPort
+        Log.i(TAG, "browser shell server listening on $LOOPBACK_V4:$port")
+
+        Thread({
+            while (!ss.isClosed) {
+                try {
+                    val client = ss.accept()
+                    Thread({ handleClient(client, token) }, "browser-shell-conn").apply { isDaemon = true }.start()
+                } catch (_: SocketException) {
+                    // Server was closed; exit the loop.
+                }
+            }
+        }, "browser-shell-accept").apply { isDaemon = true }.start()
+    }
+
+    fun stop() {
+        runCatching { serverSocket?.close() }
+        serverSocket = null
+    }
+
+    /** A fresh 256-bit credential, hex-encoded, for one launch of the server. */
+    private fun newToken(): String {
+        val bytes = ByteArray(32)
+        java.security.SecureRandom().nextBytes(bytes)
+        return bytes.joinToString("") { "%02x".format(it) }
+    }
+
+    // ---- HTTP plumbing --------------------------------------------------------
+
+    private fun handleClient(client: Socket, expected: String) {
+        try {
+            client.soTimeout = 30_000
+            val input = BufferedInputStream(client.getInputStream())
+            val output = client.getOutputStream()
+
+            // Parse the request line.
+            val requestLine = readLine(input) ?: return
+            val parts = requestLine.split(" ", limit = 3)
+            if (parts.size < 2) return
+            val method = parts[0]
+            val path = parts[1].substringBefore('?')
+
+            // Read headers.
+            var contentLength = 0
+            var bearer: String? = null
+            while (true) {
+                val header = readLine(input) ?: break
+                if (header.isEmpty()) break
+                val lower = header.lowercase()
+                if (lower.startsWith("content-length:")) {
+                    contentLength = header.substringAfter(':').trim().toIntOrNull() ?: 0
+                } else if (lower.startsWith("authorization:")) {
+                    bearer = header.substringAfter(':').trim().removePrefix("Bearer ").trim()
+                }
+            }
+
+            // Nothing behind this server is safe to hand out on the strength of
+            // an address: the port is on loopback, which any other app on the
+            // phone can dial, and the routes run script in and read text out of
+            // the loaded page. The credential the kernel was started with is the
+            // only thing that says a caller is that kernel. Every route is
+            // refused without it, /health included — a probe needs no exemption.
+            if (expected.isEmpty() || bearer != expected) {
+                writeResponse(output, 401, """{"error":"unauthorized"}""")
+                return
+            }
+
+            // Read body.
+            val body = if (contentLength > 0) {
+                val buf = ByteArray(contentLength)
+                var read = 0
+                while (read < contentLength) {
+                    val n = input.read(buf, read, contentLength - read)
+                    if (n == -1) break
+                    read += n
+                }
+                String(buf, 0, read, Charsets.UTF_8)
+            } else ""
+
+            // Route.
+            val (status, responseBody) = route(method, path, body)
+            writeResponse(output, status, responseBody)
+        } catch (e: Exception) {
+            Log.w(TAG, "connection error: ${e.message}")
+        } finally {
+            runCatching { client.close() }
+        }
+    }
+
+    private fun route(method: String, path: String, body: String): Pair<Int, String> {
+        return when {
+            method == "GET" && path == "/health" -> 200 to """{"ok":true}"""
+            method == "POST" && path == "/load" -> handleLoad(body)
+            method == "POST" && path == "/close" -> handleClose()
+            method == "POST" && path == "/read" -> handleRead()
+            method == "POST" && path == "/screenshot" -> handleScreenshot()
+            method == "POST" && path == "/click" -> handleClick(body)
+            method == "POST" && path == "/eval" -> handleEval(body)
+            method == "POST" && path == "/back" -> handleBack()
+            method == "POST" && path == "/forward" -> handleForward()
+            method == "POST" && path == "/reload" -> handleReload()
+            method == "POST" && path == "/requests" -> handleRequests()
+            else -> 404 to """{"error":"not found"}"""
+        }
+    }
+
+    private fun writeResponse(out: OutputStream, status: Int, body: String) {
+        val reason = when (status) {
+            200 -> "OK"
+            404 -> "Not Found"
+            500 -> "Internal Server Error"
+            else -> "Error"
+        }
+        val bytes = body.toByteArray(Charsets.UTF_8)
+        val header = "HTTP/1.1 $status $reason\r\n" +
+            "Content-Type: application/json\r\n" +
+            "Content-Length: ${bytes.size}\r\n" +
+            "Connection: close\r\n" +
+            "\r\n"
+        out.write(header.toByteArray(Charsets.UTF_8))
+        out.write(bytes)
+        out.flush()
+    }
+
+    private fun readLine(input: BufferedInputStream): String? {
+        val sb = StringBuilder()
+        while (true) {
+            val b = input.read()
+            if (b == -1) return if (sb.isEmpty()) null else sb.toString()
+            if (b == '\r'.code) {
+                val next = input.read()
+                if (next == '\n'.code) return sb.toString()
+                sb.append(b.toChar())
+                if (next != -1) sb.append(next.toChar())
+                continue
+            }
+            if (b == '\n'.code) return sb.toString()
+            sb.append(b.toChar())
+        }
+    }
+
+    // ---- endpoint handlers ----------------------------------------------------
+
+    /** POST /load {"url":"..."} → {"url":"...","title":"..."} */
+    private fun handleLoad(body: String): Pair<Int, String> {
+        val json = runCatching { JSONObject(body) }.getOrNull()
+            ?: return 500 to """{"error":"invalid request body"}"""
+        val url = json.optString("url", "")
+        if (url.isEmpty()) return 500 to """{"error":"missing url"}"""
+
+        val result = AtomicReference("")
+        val latch = CountDownLatch(1)
+        mainHandler.post {
+            val wv = ensureView()
+            // The failure recorded for the page being left stops being this
+            // tab's, and the wait a following `/read` joins is armed before the
+            // new address is loaded, so no callback for the new page can fire
+            // ahead of it. `/load` answers before the page arrives, which is
+            // what left the old failure to be read back as the new page's.
+            startNavigation()
+            wv.loadUrl(url)
+            // The title and final URL are not available synchronously after
+            // loadUrl; answer with what was requested. The kernel stores this
+            // as the tab's URL and reads the real one on the next /read.
+            result.set(JSONObject().apply {
+                put("url", url)
+                put("title", "")
+            }.toString())
+            latch.countDown()
+        }
+        if (!latch.await(UI_TIMEOUT_MS, TimeUnit.MILLISECONDS)) {
+            return 500 to """{"error":"timeout waiting for UI thread"}"""
+        }
+        return 200 to result.get()
+    }
+
+    /** POST /close {} → 200 */
+    private fun handleClose(): Pair<Int, String> {
+        val latch = CountDownLatch(1)
+        mainHandler.post {
+            val wv = existingView()
+            if (wv != null) {
+                wv.loadUrl("about:blank")
+                wv.clearHistory()
+            }
+            latch.countDown()
+        }
+        if (!latch.await(UI_TIMEOUT_MS, TimeUnit.MILLISECONDS)) {
+            return 500 to """{"error":"timeout"}"""
+        }
+        return 200 to "{}"
+    }
+
+    /**
+     * POST /read {} → {"title":"...","url":"...","text":"..."}
+     *
+     * Injects a script that extracts readable text from the page, preferring
+     * `<article>` or `<main>` and falling back to `body.innerText`. The result
+     * is truncated to 400 KB (matching the kernel's `maxReadText`); when
+     * truncated, a note is appended so the model knows the text was cut.
+     */
+    private fun handleRead(): Pair<Int, String> {
+        // The page the caller just asked for has not necessarily been visited
+        // yet: `/load` returns as soon as it has started the navigation. Waiting
+        // here, off the UI thread, is what makes this read answer about that
+        // page instead of the one before it.
+        awaitNavigation(NAV_SETTLE_MS)
+        val result = AtomicReference("")
+        val latch = CountDownLatch(1)
+        mainHandler.post {
+            val wv = ensureView()
+            // A page that did not load is not content. Whether the view is on
+            // the browser's own error page is read from the view itself rather
+            // than from a remembered failure: a failure recorded for the page
+            // before a new navigation would otherwise be handed back as this
+            // page's answer, long after the page the caller asked for had
+            // loaded. The remembered failure is still what names the address
+            // that failed and why, since the error page's own URL does not.
+            if ((wv.url ?: "").startsWith("chrome-error:")) {
+                val (url, reason) = loadFailure() ?: ((wv.url ?: "") to "ERR_FAILED")
+                result.set(JSONObject().apply {
+                    put("url", url)
+                    put("title", "")
+                    put("reason", reason)
+                    put("text", "")
+                }.toString())
+                latch.countDown()
+                return@post
+            }
+            // The extraction script: prefer article/main for content pages,
+            // fall back to body. innerText preserves visual line breaks. It
+            // also stamps a ref on every element a person could act on, so the
+            // kernel can name one in an act step the way the desktop backend
+            // names an accessibility node. A ref already on an element is kept,
+            // so it stays the same across snapshots of one document; a fresh
+            // document starts the numbering over, and the kernel only accepts a
+            // ref from the snapshot it last read.
+            val script = """
+                (function(){
+                    var seq = window.__rxRefSeq || 0;
+                    var used = {};
+                    var marked = document.querySelectorAll('[data-rx-ref]');
+                    for (var i = 0; i < marked.length; i++) { used[marked[i].getAttribute('data-rx-ref')] = true; }
+                    function roleOf(el) {
+                        var tag = el.tagName.toLowerCase();
+                        var role = (el.getAttribute('role') || '').toLowerCase();
+                        if (role) return role;
+                        if (tag === 'a') return 'link';
+                        if (tag === 'button') return 'button';
+                        if (tag === 'select') return 'combobox';
+                        if (tag === 'textarea') return 'textbox';
+                        if (tag === 'input') {
+                            var t = (el.getAttribute('type') || 'text').toLowerCase();
+                            if (t === 'checkbox' || t === 'radio' || t === 'submit' || t === 'button' || t === 'reset') return t;
+                            return 'textbox';
+                        }
+                        return 'generic';
+                    }
+                    function nameOf(el) {
+                        var n = el.getAttribute('aria-label') || el.getAttribute('placeholder') || el.getAttribute('name') || '';
+                        if (!n) { n = (el.innerText || el.textContent || '').trim(); }
+                        return n.replace(/\s+/g, ' ').slice(0, 160);
+                    }
+                    var sel = 'a[href],button,input,select,textarea,[role=button],[role=link],[role=checkbox],[role=radio],[role=tab],[role=menuitem],[contenteditable=true]';
+                    var els = document.querySelectorAll(sel);
+                    var elements = [];
+                    for (var j = 0; j < els.length; j++) {
+                        var el = els[j];
+                        var ref = el.getAttribute('data-rx-ref');
+                        if (!ref) {
+                            do { seq++; ref = 'e' + seq; } while (used[ref]);
+                            el.setAttribute('data-rx-ref', ref);
+                            used[ref] = true;
+                        }
+                        var raw = (el.value != null && String(el.value) !== '') ? String(el.value).slice(0, 160) : '';
+                        elements.push({ref: ref, role: roleOf(el), name: nameOf(el), value: raw});
+                    }
+                    window.__rxRefSeq = seq;
+                    var el2 = document.querySelector('article') || document.querySelector('main') || document.body;
+                    var text = el2 ? (el2.innerText || '') : '';
+                    var title = document.title || '';
+                    var url = location.href;
+                    return JSON.stringify({title: title, url: url, text: text, elements: elements});
+                })()
+            """.trimIndent()
+            wv.evaluateJavascript(script) { value ->
+                // evaluateJavascript returns a JSON-encoded string (the result
+                // is double-encoded). Strip the outer quotes.
+                val parsed = parseJsResult(value)
+                if (parsed != null) {
+                    try {
+                        val obj = JSONObject(parsed)
+                        var text = obj.optString("text", "")
+                        if (text.length > MAX_READ_TEXT) {
+                            text = text.substring(0, MAX_READ_TEXT) +
+                                "\n\n[text truncated at 400 KB]"
+                        }
+                        result.set(JSONObject().apply {
+                            put("title", obj.optString("title", ""))
+                            put("url", obj.optString("url", ""))
+                            put("text", text)
+                            put("elements", obj.optJSONArray("elements") ?: JSONArray())
+                        }.toString())
+                    } catch (e: Exception) {
+                        result.set(JSONObject().apply {
+                            put("title", "")
+                            put("url", wv.url ?: "")
+                            put("text", parsed.take(MAX_READ_TEXT))
+                        }.toString())
+                    }
+                } else {
+                    result.set(JSONObject().apply {
+                        put("title", "")
+                        put("url", wv.url ?: "")
+                        put("text", "")
+                    }.toString())
+                }
+                latch.countDown()
+            }
+        }
+        if (!latch.await(READ_SCRIPT_MS, TimeUnit.MILLISECONDS)) {
+            return 500 to """{"error":"timeout waiting for page script"}"""
+        }
+        return 200 to result.get()
+    }
+
+    /**
+     * POST /screenshot {} → {"data":"<base64>","mime":"image/png"}
+     *
+     * Draws the WebView into a bitmap, downsamples by SCREENSHOT_SCALE to keep
+     * memory bounded, and encodes as PNG → base64. For a 1080×2400 viewport the
+     * full bitmap is ~10 MB; the downsampled one is ~2.5 MB. The full bitmap is
+     * recycled immediately after scaling.
+     */
+    private fun handleScreenshot(): Pair<Int, String> {
+        val result = AtomicReference("")
+        val failed = AtomicBoolean(false)
+        val latch = CountDownLatch(1)
+        mainHandler.post {
+            val wv = ensureView()
+            try {
+                val width = wv.width.takeIf { it > 0 } ?: 1080
+                val height = wv.height.takeIf { it > 0 } ?: 1920
+                val bmp = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888)
+                val canvas = Canvas(bmp)
+                wv.draw(canvas)
+
+                // Downsample to bound the PNG size and the base64 string.
+                val scaled = Bitmap.createScaledBitmap(
+                    bmp,
+                    width / SCREENSHOT_SCALE,
+                    height / SCREENSHOT_SCALE,
+                    true,
+                )
+                if (scaled !== bmp) bmp.recycle()
+
+                val baos = ByteArrayOutputStream()
+                scaled.compress(Bitmap.CompressFormat.PNG, 85, baos)
+                scaled.recycle()
+                val b64 = Base64.encodeToString(baos.toByteArray(), Base64.NO_WRAP)
+                result.set(JSONObject().apply {
+                    put("data", b64)
+                    put("mime", "image/png")
+                }.toString())
+            } catch (e: Exception) {
+                // A 200 with an error body would be read by the kernel as a
+                // screenshot whose data is empty, and it would build a `data:`
+                // URI out of nothing. The status is what tells it this failed.
+                result.set("""{"error":"screenshot failed: ${e.message}"}""")
+                failed.set(true)
+            }
+            latch.countDown()
+        }
+        if (!latch.await(UI_TIMEOUT_MS, TimeUnit.MILLISECONDS)) {
+            return 500 to """{"error":"timeout"}"""
+        }
+        if (failed.get()) return 500 to result.get()
+        return 200 to result.get()
+    }
+
+    /** POST /click {"selector":"..."} → {"ok":true|false} */
+    private fun handleClick(body: String): Pair<Int, String> {
+        val json = runCatching { JSONObject(body) }.getOrNull()
+            ?: return 500 to """{"error":"invalid request body"}"""
+        val selector = json.optString("selector", "")
+        if (selector.isEmpty()) return 500 to """{"error":"missing selector"}"""
+
+        val result = AtomicReference("")
+        val latch = CountDownLatch(1)
+        mainHandler.post {
+            val wv = ensureView()
+            // Escape the selector for embedding in a JS string.
+            val escaped = selector.replace("\\", "\\\\").replace("'", "\\'")
+            val script = """
+                (function(){
+                    try {
+                        var el = document.querySelector('$escaped');
+                        if (!el) return JSON.stringify({ok: false});
+                        el.click();
+                        return JSON.stringify({ok: true});
+                    } catch(e) {
+                        return JSON.stringify({ok: false});
+                    }
+                })()
+            """.trimIndent()
+            wv.evaluateJavascript(script) { value ->
+                val parsed = parseJsResult(value)
+                result.set(parsed ?: """{"ok":false}""")
+                latch.countDown()
+            }
+        }
+        if (!latch.await(UI_TIMEOUT_MS, TimeUnit.MILLISECONDS)) {
+            return 500 to """{"error":"timeout"}"""
+        }
+        return 200 to result.get()
+    }
+
+    /** POST /eval {"script":"..."} → {"result":"..."} */
+    private fun handleEval(body: String): Pair<Int, String> {
+        val json = runCatching { JSONObject(body) }.getOrNull()
+            ?: return 500 to """{"error":"invalid request body"}"""
+        val script = json.optString("script", "")
+        if (script.isEmpty()) return 500 to """{"error":"missing script"}"""
+
+        val result = AtomicReference("")
+        val latch = CountDownLatch(1)
+        mainHandler.post {
+            val wv = ensureView()
+            wv.evaluateJavascript(script) { value ->
+                // The kernel expects a plain string in "result". The value from
+                // evaluateJavascript is JSON-encoded; unwrap it.
+                val unwrapped = parseJsResult(value) ?: ""
+                result.set(JSONObject().apply {
+                    put("result", unwrapped)
+                }.toString())
+                latch.countDown()
+            }
+        }
+        if (!latch.await(UI_TIMEOUT_MS, TimeUnit.MILLISECONDS)) {
+            return 500 to """{"error":"timeout waiting for eval"}"""
+        }
+        return 200 to result.get()
+    }
+
+    /** POST /back → 200 */
+    private fun handleBack(): Pair<Int, String> {
+        val latch = CountDownLatch(1)
+        mainHandler.post {
+            existingView()?.let { if (it.canGoBack()) it.goBack() }
+            latch.countDown()
+        }
+        if (!latch.await(UI_TIMEOUT_MS, TimeUnit.MILLISECONDS)) {
+            return 500 to """{"error":"timeout"}"""
+        }
+        return 200 to "{}"
+    }
+
+    /** POST /forward → 200 */
+    private fun handleForward(): Pair<Int, String> {
+        val latch = CountDownLatch(1)
+        mainHandler.post {
+            existingView()?.let { if (it.canGoForward()) it.goForward() }
+            latch.countDown()
+        }
+        if (!latch.await(UI_TIMEOUT_MS, TimeUnit.MILLISECONDS)) {
+            return 500 to """{"error":"timeout"}"""
+        }
+        return 200 to "{}"
+    }
+
+    /** POST /reload → 200 */
+    private fun handleReload(): Pair<Int, String> {
+        val latch = CountDownLatch(1)
+        mainHandler.post {
+            val wv = existingView()
+            // A view sitting on the browser's own error page is not on the site,
+            // and reloading it would retry the error page itself. The address
+            // that failed is loaded again instead — which is the page a caller
+            // means by "reload" — read before `startNavigation` clears it.
+            val failed = if (wv != null && (wv.url ?: "").startsWith("chrome-error:"))
+                loadFailure()?.first else null
+            startNavigation()
+            if (wv != null) {
+                if (failed != null) wv.loadUrl(failed) else wv.reload()
+            }
+            latch.countDown()
+        }
+        if (!latch.await(UI_TIMEOUT_MS, TimeUnit.MILLISECONDS)) {
+            return 500 to """{"error":"timeout"}"""
+        }
+        return 200 to "{}"
+    }
+
+    /** POST /requests {} → {"requests":[{"method","url","kind"},…]} */
+    private fun handleRequests(): Pair<Int, String> {
+        val arr = JSONArray()
+        for (r in requests()) {
+            arr.put(JSONObject().apply {
+                put("method", r.method)
+                put("url", r.url)
+                put("kind", r.kind)
+            })
+        }
+        return 200 to JSONObject().apply { put("requests", arr) }.toString()
+    }
+
+    // ---- helpers ----------------------------------------------------------------
+
+    /**
+     * Unwrap the result of `evaluateJavascript`. The callback receives a
+     * JSON-encoded string: a JS string "hello" arrives as `"\"hello\""`, a
+     * number 42 as `"42"`, null as `"null"`. Strip the outer JSON encoding to
+     * get the raw value.
+     */
+    private fun parseJsResult(value: String?): String? {
+        if (value == null || value == "null") return null
+        // The value is a JSON literal. If it is a JSON string, decode it.
+        return try {
+            if (value.startsWith("\"") && value.endsWith("\"")) {
+                JSONObject().apply { }.let {
+                    // Use JSONObject's string decoding: wrap in an object.
+                    JSONObject("""{"v":$value}""").optString("v", "")
+                }
+            } else {
+                value
+            }
+        } catch (_: Exception) {
+            value
+        }
+    }
+}
@@ -0,0 +1,119 @@
+package io.reasonix.mobile.app
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.net.LinkProperties
+import android.os.Build
+
+/**
+ * The phone's DNS servers, as the kernel needs them.
+ *
+ * The kernel is a CGO-free Go binary, and Go's own source explains why that
+ * matters:
+ *
+ * ```
+ * // DNS requests don't work on Android, so prefer the cgo resolver.
+ * // Issue #10714.
+ * case "android":
+ * ```
+ *
+ * A normal Android program resolves names through `getaddrinfo`, which reaches
+ * the `netd` daemon and gets the servers of the network that is actually up.
+ * A static binary has no cgo resolver, so Go reads `/etc/resolv.conf` instead —
+ * and Android has no such file. Go then falls back to `127.0.0.1:53`, where
+ * nothing listens, and every lookup fails: the setup screen reports
+ * "连接失败" for every provider, including the official ones, on a phone whose
+ * browser reaches them fine.
+ *
+ * So they are read here and handed to the kernel through `REASONIX_DNS`. This is
+ * the same source the system itself uses, so a VPN, a private DNS hostname, or a
+ * network that changed since boot is all reflected without this code knowing
+ * anything about them.
+ */
+object Dns {
+
+    /**
+     * The active network's servers, comma separated, or "" when there is none.
+     *
+     * Read from the *active* network rather than from every link, because a phone
+     * commonly has several at once — Wi-Fi, mobile data, a VPN — and the servers
+     * of a network that is not carrying traffic are the wrong ones to ask.
+     */
+    fun servers(context: Context): String {
+        val manager = context.getSystemService(Context.CONNECTIVITY_SERVICE) as? ConnectivityManager
+            ?: return ""
+        val properties: LinkProperties = runCatching { manager.activeNetwork }.getOrNull()
+            ?.let { network -> runCatching { manager.getLinkProperties(network) }.getOrNull() }
+            ?: return ""
+        return properties.dnsServers
+            .mapNotNull { address -> address.hostAddress }
+            .filter { it.isNotBlank() }
+            .filter { routable(it) }
+            .sortedBy { preference(it) }
+            .joinToString(",")
+    }
+
+    /**
+     * Whether an address can actually carry a query.
+     *
+     * A link-local address (fe80::/10) without its zone cannot: the packet has
+     * no interface to leave by, so it is dropped, nothing answers, and the
+     * lookup hangs until the kernel's own timeout expires — which is reported as
+     * a timeout rather than as a failure to resolve, and so reads like the
+     * network is slow instead of like the address is unusable.
+     *
+     * Android reports the zone as a `%wlan0` suffix on `hostAddress`, and the
+     * address is only usable with it kept. Nothing here trims it: an earlier
+     * version called `substringBefore('%')`, which turned a usable link-local
+     * server into an unroutable one.
+     */
+    private fun routable(host: String): Boolean =
+        !(host.startsWith("fe80:", ignoreCase = true) && !host.contains('%'))
+
+    /**
+     * IPv4 first, then IPv6.
+     *
+     * A phone commonly reports both, and its IPv6 entry is often a router's
+     * link-local address — reachable on one network and not the next. The
+     * kernel tries the servers in the order it is given them, and stops at the
+     * first that answers; putting the address family that shares the network's
+     * own numbering first means its timeout is spent on a server that works.
+     */
+    private fun preference(host: String): Int = if (host.contains(':')) 1 else 0
+
+    /**
+     * The private-DNS setting, for the one case the address list cannot answer.
+     *
+     * Since Android 9 a phone may use DNS-over-TLS, and then `dnsServers` holds a
+     * name rather than an address — a name this kernel cannot resolve *because*
+     * resolving it is the thing that is broken. There is no way for the shell to
+     * do that lookup for it, so this reports the situation instead of handing
+     * over an unusable value: the caller says so in the log, and the person can
+     * turn private DNS off or set it to automatic.
+     */
+    fun looksLikeDot(servers: String): Boolean =
+        servers.isNotBlank() && servers.split(',').any { part ->
+            val host = part.trim()
+            host.isNotEmpty() && host.none { it == ':' } && !host.all { it.isDigit() || it == '.' }
+        }
+
+    /** Whether the system requires a VPN or private DNS, which changes nothing
+     *  here but is worth saying in a bug report. */
+    fun describe(context: Context): String {
+        val manager = context.getSystemService(Context.CONNECTIVITY_SERVICE) as? ConnectivityManager
+            ?: return "no connectivity service"
+        val network = runCatching { manager.activeNetwork }.getOrNull() ?: return "no active network"
+        val properties = runCatching { manager.getLinkProperties(network) }.getOrNull()
+            ?: return "no link properties"
+        // The DHCP server arrived in API 30, not 23: asked for below that it is a
+        // NoSuchMethodError on a device this app supports (minSdk 26), and the
+        // answer is only ever read out of this string by a person debugging.
+        val dhcp = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            properties.dhcpServerAddress?.hostAddress
+        } else {
+            null
+        }
+        return "iface=${properties.interfaceName} dns=${properties.dnsServers.joinToString(",") { it.hostAddress ?: "?" }}" +
+            (dhcp?.let { " dhcp=$it" } ?: "")
+    }
+}
@@ -0,0 +1,87 @@
+package io.reasonix.mobile.app
+
+import android.content.Context
+import android.net.Uri
+import android.webkit.CookieManager
+import android.widget.Toast
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import java.io.FileNotFoundException
+import java.net.HttpURLConnection
+import java.net.URL
+
+/**
+ * Putting a file the page produced onto the phone's disk.
+ *
+ * A WebView has no downloads shelf and cannot write to the system's document
+ * picker itself, so the two halves are joined here: the page asks, the picker
+ * answers with a `content://` the app has been granted, and this copies the
+ * bytes across.
+ *
+ * The request carries the WebView's own cookie, read out of the jar the page
+ * authenticated in. That is the only reason this is not a plain `openStream`:
+ * the kernel's download route is behind the session the page established, and a
+ * shell that fetched without it would get a 403 and no explanation.
+ */
+object Downloader {
+
+    suspend fun run(
+        context: Context,
+        url: String,
+        userAgent: String,
+        mime: String,
+        name: String,
+        target: Uri,
+    ): Result<Unit> = withContext(Dispatchers.IO) {
+        runCatching {
+            val connection = (URL(url).openConnection() as HttpURLConnection).apply {
+                connectTimeout = 15_000
+                readTimeout = 60_000
+                requestMethod = "GET"
+                if (userAgent.isNotBlank()) setRequestProperty("User-Agent", userAgent)
+                // The download route answers with the same session cookie the
+                // page is using; without it the kernel refuses the request.
+                cookieFor(url)?.let { setRequestProperty("Cookie", it) }
+            }
+            try {
+                val code = connection.responseCode
+                if (code !in 200..299) {
+                    throw IllegalStateException(
+                        context.getString(R.string.download_failed_status, code),
+                    )
+                }
+                val resolver = context.contentResolver
+                val output = resolver.openOutputStream(target, "w")
+                    ?: throw FileNotFoundException(target.toString())
+                output.use { out ->
+                    connection.inputStream.use { input -> input.copyTo(out) }
+                }
+                // `copyTo` answers with a byte count; what the caller wants to
+                // know is that there were no bytes missing, not how many.
+                Unit
+            } finally {
+                connection.disconnect()
+            }
+        }
+    }
+
+    /**
+     * The cookie the page authenticated with, if any.
+     *
+     * `CookieManager` is the WebView's own store, so this asks the exact jar the
+     * request will be checked against rather than a copy this shell kept.
+     */
+    private fun cookieFor(url: String): String? =
+        runCatching { CookieManager.getInstance().getCookie(url) }.getOrNull()?.takeIf { it.isNotBlank() }
+
+    /** A short receipt for a tap that otherwise does nothing visible. */
+    fun report(context: Context, name: String, result: Result<Unit>) {
+        val message = result.fold(
+            onSuccess = { context.getString(R.string.download_saved, name) },
+            onFailure = { failure ->
+                context.getString(R.string.download_failed, failure.message ?: "")
+            },
+        )
+        Toast.makeText(context, message, Toast.LENGTH_LONG).show()
+    }
+}
@@ -0,0 +1,741 @@
+package io.reasonix.mobile.app
+
+import android.content.Context
+import android.content.res.AssetManager
+import org.json.JSONArray
+import org.json.JSONObject
+import android.util.Log
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.withContext
+import java.io.File
+import java.io.FileOutputStream
+import java.net.HttpURLConnection
+import java.net.URL
+import java.security.SecureRandom
+import java.util.Locale
+
+/**
+ * The Reasonix kernel, as this app runs it: one child process serving loopback,
+ * plus the two things it needs on disk to start — the page it serves and a
+ * credential for this launch.
+ *
+ * The shape is the desktop host's (`cmd/reasonix-studio-host`), narrowed to what
+ * a phone does not have. That host binds a socket, mints a credential, speaks a
+ * handshake down a pipe and holds a lease; here the credential goes through
+ * `--token-file` and the bound address through `--port-file`, because a phone's
+ * app process has no pipe to hand a child and no reason to care which port was
+ * free. Everything after that — the kernel's own gate, its auth middleware, its
+ * CSRF check — is untouched, so the security of the surface is the one upstream
+ * tested, not one this shell invented.
+ *
+ * One instance lives in the app process. The activity asks it for a URL; the
+ * foreground service asks it to stay alive. Both see the same process, so there
+ * is nothing to synchronise beyond a lock on start/stop.
+ */
+class Kernel(private val context: Context) {
+
+    /** Where everything the kernel owns lives. Nothing here is backed up. */
+    private val home = File(context.filesDir, "home")
+
+    /**
+     * The folder the agent works in, which is not the folder the kernel lives in.
+     *
+     * These used to be the same directory, and that is what made the workbench
+     * unreadable: the kernel's home holds `config.toml`, `projects/`, `cache/`,
+     * `stats/` and the rest of its own bookkeeping, and a workspace pointed at
+     * it shows all of that as if the person had put it there. Reported as "why
+     * does the default workspace have so many files, the desktop version does
+     * not generate these" — the desktop does generate them, in a different
+     * directory, because its workspace is whatever folder it was opened on.
+     *
+     * Split apart, the workbench shows what the agent produced and nothing else.
+     * `write_roots` follows the workspace, so the file tools stay confined to
+     * the folder the person actually works in rather than to the kernel's own
+     * home — which is the stricter answer, and the one the desktop already has.
+     */
+    private val workspaceDir = File(context.filesDir, "workspace")
+
+    /**
+     * The directory the kernel calls `REASONIX_HOME`, for the one caller that
+     * has to put a file where the kernel can read it — a private key the person
+     * picked from their Documents folder.
+     */
+    fun homeDir(): File = home
+
+    /** The folder the agent works in. */
+    fun workspaceDir(): File = workspaceDir
+
+    /** The built page, unpacked once per version. */
+    private val pageDir = File(context.filesDir, "page")
+
+    private val tokenFile = File(home, "remote/launch.token")
+    private val portFile = File(home, "remote/serve.port")
+    private val pidFile = File(home, "remote/serve.pid")
+
+    private val lock = Any()
+
+    @Volatile
+    private var process: Process? = null
+
+    /** The port the shell's browser HTTP server listens on, set by the
+     *  activity before `start()` is called. Zero means no server is up, and
+     *  the kernel leaves its browser tools suspended (the correct degradation
+     *  on a phone with no Chromium). */
+    @Volatile
+    var browserShellPort: Int = 0
+
+    /** The bearer credential for that server, set beside the port. Sent on
+     *  every browser call so the server can refuse anything that did not come
+     *  from the kernel this shell started — loopback on a phone is reachable
+     *  by every other app. Empty when there is no server. */
+    @Volatile
+    var browserShellToken: String = ""
+
+    /** What the WebView should load, once the kernel has bound a port. */
+    @Volatile
+    var origin: String? = null
+        private set
+
+    /**
+     * The launch credential, as the URL fragment the page trades for a cookie.
+     * Kept in memory only: the file on disk belongs to the kernel's own
+     * bookkeeping, and a phone's app data is not a place to leave a second copy.
+     */
+    @Volatile
+    private var token: String? = null
+
+    /**
+     * The URL the WebView loads first. It carries the credential in the
+     * fragment, which the page exchanges for an HttpOnly cookie before it makes
+     * any request — the same path a shared `reasonix web` link takes, so the
+     * token never enters a request line, a history entry or a log.
+     */
+    fun entryUrl(): String? {
+        val origin = origin ?: return null
+        val token = token ?: return null
+        return "$origin/#token=$token"
+    }
+
+    /** The plain origin, for reloads once the cookie is set. */
+    fun plainUrl(): String? = origin
+
+    fun isRunning(): Boolean = process?.isAlive == true
+
+    /**
+     * Bring the kernel up, or answer the URL of the one already up.
+     *
+     * Starting is idempotent by intent: the activity and the service both call
+     * this, and whichever arrives second joins the running kernel instead of
+     * racing it for the port.
+     */
+    suspend fun start(): Result<String> = withContext(Dispatchers.IO) {
+        synchronized(lock) {
+            origin?.let { return@withContext Result.success(it) }
+
+            runCatching {
+                val binary = kernelBinary()
+                publishPage()
+                prepareHome()
+                val launchToken = mintToken()
+                token = launchToken
+
+                val child = launch(binary, launchToken)
+
+                // The port is the kernel's answer, not this shell's guess. It
+                // writes the file after binding, so waiting on the file is
+                // waiting on the bind.
+                val bound = awaitPort(child)
+                val url = "http://$bound"
+
+                // A kernel that bound a port and then died would look healthy
+                // here and broken in the WebView; the two facts are checked
+                // together, and only a kernel that is answering is adopted.
+                awaitServing(child, url)
+                origin = url
+                process = child
+                url
+            }.onFailure { origin = null; process = null }
+        }
+    }
+
+    /**
+     * Stop the kernel.
+     *
+     * The graceful signal first: the kernel drains its listeners and closes the
+     * runtimes it opened, which is what lets a later launch adopt the sessions
+     * rather than find them locked. `destroyForcibly` is the second attempt, and
+     * only after a wait — a phone that is being shut down should not keep a
+     * half-killed agent.
+     */
+    fun stop() {
+        synchronized(lock) {
+            val p = process ?: return
+            process = null
+            origin = null
+            token = null
+            runCatching {
+                p.destroy()
+                if (!p.waitFor(3, java.util.concurrent.TimeUnit.SECONDS)) {
+                    p.destroyForcibly()
+                }
+            }
+            portFile.delete()
+            pidFile.delete()
+        }
+    }
+
+    // ---- the two inputs that ship inside the APK -------------------------
+
+    /**
+     * The kernel binary.
+     *
+     * It is packaged as a native library, so Android has already extracted it to
+     * a directory it allows execution from and given it the executable bit —
+     * which is the one thing a file under app storage does not get for free.
+     */
+    private fun kernelBinary(): File {
+        val dir = File(context.applicationInfo.nativeLibraryDir)
+        val binary = File(dir, "libreasonix.so")
+        if (!binary.exists()) {
+            throw IllegalStateException(
+                "内核未随 APK 安装：${binary.path}\n这是一次构建问题，请重新安装完整 APK。",
+            )
+        }
+        return binary
+    }
+
+    /**
+     * Write the bundled page where the kernel can serve it.
+     *
+     * It goes to app storage rather than being served out of the APK because the
+     * kernel's `--page` is a directory on a real filesystem; there is no
+     * archive-aware variant, and adding one would be a change to the kernel for
+     * this shell's convenience alone.
+     *
+     * Unpacking is versioned: the marker holds the app's version name, so an
+     * update replaces the page and a relaunch does not. A partially written
+     * directory — the app killed mid-copy — is caught by the same marker never
+     * having been written, so the next launch rewrites it.
+     */
+    private fun publishPage() {
+        val marker = File(pageDir, ".unpacked")
+        val stamp = "${BuildConfig.VERSION_NAME}:${BuildConfig.VERSION_CODE}"
+        if (marker.isFile && marker.readText().trim() == stamp) return
+
+        pageDir.deleteRecursively()
+        pageDir.mkdirs()
+        copyAssetTree(context.assets, "page", pageDir)
+
+        if (!File(pageDir, "index.html").isFile) {
+            throw IllegalStateException("随 APK 分发的页面不完整：缺少 index.html")
+        }
+        marker.writeText(stamp)
+    }
+
+    /**
+     * A directory tree out of assets.
+     *
+     * `AssetManager.list` on a file answers with an empty array, so a "file" is
+     * told from a directory by trying to open it — which is the only signal the
+     * API offers and the reason this is not a one-liner.
+     */
+    private fun copyAssetTree(assets: AssetManager, from: String, to: File) {
+        val children = assets.list(from).orEmpty()
+        if (children.isEmpty()) {
+            // A leaf: open it as a stream. A directory that happens to be empty
+            // is indistinguishable and harmless to skip.
+            runCatching {
+                assets.open(from).use { input ->
+                    FileOutputStream(to).use { output -> input.copyTo(output) }
+                }
+            }
+            return
+        }
+        to.mkdirs()
+        for (child in children) {
+            copyAssetTree(assets, "$from/$child", File(to, child))
+        }
+    }
+
+    /**
+     * Prepare the kernel's home.
+     *
+     * `REASONIX_HOME` is what every path in the kernel hangs off — config,
+     * sessions, the remote state directory its token file lands in — so pointing
+     * it at app storage is what keeps a phone's Reasonix separate from anything
+     * else and away from global storage entirely.
+     */
+    private fun prepareHome() {
+        File(home, "remote").mkdirs()
+        // The workspace directory not existing yet is what marks the first run
+        // after this build split it from the kernel's home. That is the one
+        // moment a migration is due, and doing it here means it happens before
+        // the kernel is asked for anything.
+        val firstSplit = !workspaceDir.exists()
+        workspaceDir.mkdirs()
+        if (firstSplit) {
+            adoptSessionsFromHome()
+        }
+        // Every launch, not only the first. The rewrite is cheap and
+        // idempotent, and an entry that survived the first pass would otherwise
+        // survive forever: `firstSplit` is spent the moment the directory
+        // exists, so a build that cleaned the list once and missed leaves the
+        // home on the sidebar for good. Running it unconditionally costs one
+        // small read and makes the whole thing self-correcting.
+        forgetHomeFromWorkspaceList()
+    }
+
+    /**
+     * Drop the kernel's own home from the sidebar's remembered projects.
+     *
+     * The list is written whenever a pane opens, and until this build the pane
+     * opened on the home itself — so an upgraded install carries a "project"
+     * that is really the kernel's own directory. Leaving it there would put the
+     * person back where they started: one tap on it and the workbench is full
+     * of `config.toml`, `cache/` and `projects/` again, which is the complaint
+     * this whole change answers. Only that one path is removed; every folder
+     * someone added on purpose stays.
+     *
+     * Parsed rather than pattern-matched, because the file's two shapes — a bare
+     * array of paths and an object with `paths` and `launch` — both have to keep
+     * whatever else they hold.
+     */
+    private fun forgetHomeFromWorkspaceList() {
+        val file = File(home, "serve-workspaces.json")
+        if (!file.isFile) return
+        val text = runCatching { file.readText() }.getOrNull() ?: return
+        val wrong = runCatching { homeNames() }.getOrNull() ?: return
+        val rewritten = runCatching { withoutHome(text, wrong) }.getOrNull() ?: return
+        if (!rewritten.dropped) return
+        runCatching { file.writeText(rewritten.text) }
+            .onSuccess { Log.i(TAG, "dropped the kernel home from the project list") }
+            .onFailure { Log.w(TAG, "could not rewrite the project list: ${it.message}") }
+    }
+
+    /**
+     * Every name of the kernel's home on this device — not just the one this
+     * process happens to write.
+     *
+     * Android shows one directory under two names: `/data/data/<pkg>` and
+     * `/data/user/0/<pkg>` are two mounts of the same tree, the same inode
+     * either way, and which name a path carries depends on how it was written
+     * rather than on where it points. The list is written by the kernel, whose
+     * working directory this shell set from a path it built itself; a lookup
+     * that compared against only one spelling would silently keep the entry
+     * this exists to remove. Both names are compared, so either spelling is
+     * recognised.
+     */
+    private fun homeNames(): Set<String> {
+        val path = home.absolutePath
+        val names = mutableSetOf(path)
+        val user = "/data/user/0/"
+        val data = "/data/data/"
+        when {
+            path.startsWith(user) -> names.add(data + path.removePrefix(user))
+            path.startsWith(data) -> names.add(user + path.removePrefix(data))
+        }
+        return names
+    }
+
+    /** What a rewrite produced, and whether it actually removed anything. */
+    private class Rewrite(val text: String, val dropped: Boolean)
+
+    /**
+     * The list without the home, in whichever shape it arrived, and whether
+     * anything was actually dropped from it.
+     *
+     * The flag matters because `JSONObject` re-serialises: it escapes every
+     * `/` and does not preserve key order, so a round trip never reproduces
+     * the original bytes. Deciding to write on "the text differs" alone would
+     * therefore rewrite the kernel's file on every single launch, log a drop
+     * that never happened, and race the kernel for a file it also writes.
+     */
+    private fun withoutHome(text: String, wrong: Set<String>): Rewrite {
+        if (text.trimStart().startsWith("[")) {
+            val paths = JSONArray(text)
+            val kept = JSONArray()
+            var dropped = false
+            for (i in 0 until paths.length()) {
+                val path = paths.optString(i)
+                if (path in wrong) {
+                    dropped = true
+                    continue
+                }
+                kept.put(path)
+            }
+            return if (dropped) Rewrite(kept.toString(), true) else Rewrite(text, false)
+        }
+        val list = JSONObject(text)
+        val kept = JSONArray()
+        var dropped = false
+        val paths = list.optJSONArray("paths")
+        if (paths != null) {
+            for (i in 0 until paths.length()) {
+                val path = paths.optString(i)
+                if (path in wrong) {
+                    dropped = true
+                    continue
+                }
+                kept.put(path)
+            }
+            if (dropped) list.put("paths", kept)
+        }
+        if (list.optString("launch") in wrong) {
+            list.remove("launch")
+            dropped = true
+        }
+        return if (dropped) Rewrite(list.toString(), true) else Rewrite(text, false)
+    }
+
+    /**
+     * Move the conversations that were filed under the kernel's own home.
+     *
+     * The transcript store is keyed by the workspace root — one directory per
+     * project, under `<state>/projects/<slug>/sessions` — and until this build
+     * the root was the home itself. Splitting the two therefore moves every
+     * existing conversation to a slug nothing looks under, which reads as "my
+     * history is gone" rather than as a reorganisation. So the old directory is
+     * renamed onto the new slug once.
+     *
+     * Renaming the project directory rather than just `sessions/` carries the
+     * rest of it too: `memory/` is filed the same way, and a project's memory
+     * lost while its transcripts were kept would be a stranger failure than
+     * either alone.
+     *
+     * The slug is the absolute path with its separators flattened, which is
+     * what `config.WorkspaceSlug` does on the kernel's side. Only the home's own
+     * slug is touched: a slug for some other folder is left exactly where it is,
+     * because those are projects someone added on purpose.
+     */
+    private fun adoptSessionsFromHome() {
+        val projects = File(home, "projects")
+        if (!projects.isDirectory) return
+        val from = projects.resolve(slugOf(home.absolutePath))
+        if (!from.isDirectory) return
+        val to = projects.resolve(slugOf(workspaceDir.absolutePath))
+        // A target already there means a previous run half-finished, or the
+        // person opened this folder before. Either way its contents win:
+        // merging two transcript directories is not a thing this can do safely,
+        // and the old one is still on disk to be looked at.
+        if (to.exists()) {
+            Log.i(TAG, "${to.name} already exists; leaving ${from.name} in place")
+            return
+        }
+        if (!from.renameTo(to)) {
+            Log.w(TAG, "could not move ${from.name} to ${to.name}; history stays under the old slug")
+        } else {
+            Log.i(TAG, "moved conversations from ${from.name} to ${to.name}")
+        }
+    }
+
+    /** The kernel's `config.WorkspaceSlug`, for the two paths that matter here. */
+    private fun slugOf(path: String): String = path.replace('/', '-').replace('\\', '-').replace(':', '-')
+
+    /**
+     * The launch credential.
+     *
+     * Minted here rather than read from configuration: a credential a person can
+     * set is one anything that can read their files can present. 32 bytes, hex,
+     * the same shape the desktop host mints.
+     */
+    private fun mintToken(): String {
+        val bytes = ByteArray(32)
+        SecureRandom().nextBytes(bytes)
+        val token = bytes.joinToString("") { "%02x".format(it) }
+        tokenFile.parentFile?.mkdirs()
+        tokenFile.writeText("$token\n")
+        // 0600 by intent, and the app's own private directory means it is
+        // already unreachable to every other app on the device.
+        runCatching {
+            tokenFile.setReadable(false, false)
+            tokenFile.setReadable(true, true)
+            tokenFile.setWritable(false, false)
+            tokenFile.setWritable(true, true)
+        }
+        return token
+    }
+
+    /**
+     * Start the child.
+     *
+     * `--addr 127.0.0.1:0` lets the kernel pick a free port; `--port-file`
+     * makes it announce which. `--auth token` is the mode a phone needs: the
+     * page authenticates, and a state-changing request without the credential
+     * is refused. `--no-open` is belt and braces — a serve never opens a
+     * browser, and a phone has no browser to open.
+     */
+    private fun launch(binary: File, token: String): Process {
+        portFile.delete()
+        pidFile.delete()
+        // The folder the agent works in, resolved before the command line is
+        // built so it can be named on it. See the note under the environment
+        // block for why naming it is not the same as setting the directory.
+        val workspace = launchWorkspaceDir()
+        val command = listOf(
+            binary.absolutePath,
+            "serve",
+            "--addr", "127.0.0.1:0",
+            "--auth", "token",
+            "--token-file", tokenFile.absolutePath,
+            "--port-file", portFile.absolutePath,
+            "--pid-file", pidFile.absolutePath,
+            "--no-open",
+            "-page", pageDir.absolutePath,
+            // The project root, said outright. Without this the kernel derives
+            // it from its working directory, and on this phone the two did not
+            // agree: the sidebar named the shared folder, `write_roots` confined
+            // the file tools to the app's own directory, and every write into the
+            // folder the person was looking at came back
+            // `workspace.write_outside_scope`. A flag is a fact the kernel was
+            // told rather than one it inferred from a mount it sees differently.
+            "--dir", workspace.absolutePath,
+        )
+        val builder = ProcessBuilder(command)
+        builder.environment().apply {
+            put("REASONIX_HOME", home.absolutePath)
+            put("HOME", home.absolutePath)
+            // The kernel's own language, for its tool failures, approval
+            // prompts and error sentences. Without this it detects from the
+            // POSIX locale variables, and Android sets none of them for an
+            // app: the kernel then answers in English while the page in front
+            // of the person is Chinese, and every sentence added for a Chinese
+            // reader was dead text. The tag, not the bare language, so a
+            // Traditional Chinese device resolves to zh-TW rather than zh.
+            // An explicit `language` in the kernel's config.toml still wins:
+            // DetectLanguage applies the configured value over this.
+            val languageTag = Locale.getDefault().toLanguageTag()
+            if (languageTag.isNotBlank() && languageTag != "und") {
+                put("REASONIX_LANG", languageTag)
+            }
+            // Android has no /tmp. Everything that wants a scratch directory —
+            // the shell tool, tool output spooling, sqlite journals — reads this.
+            put("TMPDIR", context.cacheDir.absolutePath)
+            // The phone's own DNS servers. A CGO-free Go binary cannot read them
+            // for itself — Android keeps them in `netd`, and Go looks for a
+            // `/etc/resolv.conf` that does not exist — so without this the kernel
+            // resolves nothing and every provider probe reports "连接失败" on a
+            // device whose browser reaches the same address fine.
+            val dns = Dns.servers(context)
+            if (dns.isNotBlank()) {
+                put("REASONIX_DNS", dns)
+                Log.i(TAG, "kernel DNS: $dns (${Dns.describe(context)})")
+                if (Dns.looksLikeDot(dns)) {
+                    // Private DNS (DNS-over-TLS) is on, and it hands back a
+                    // hostname this kernel cannot resolve by definition. Saying
+                    // so here is what turns "连不上" into something actionable.
+                    Log.w(TAG, "kernel DNS looks like a private-DNS hostname; turn private DNS off or set it to automatic")
+                }
+            } else {
+                Log.w(TAG, "kernel DNS: none reported by the system")
+            }
+            // The shell's browser server, when one is listening. The kernel
+            // reads this to bind its browser tools to the shell's WebView
+            // instead of looking for a Chromium binary that does not exist on
+            // a phone. When absent (zero), the variable is not set and the
+            // kernel keeps the browser tools suspended — the correct
+            // degradation for a phone with no engine to drive.
+            val shellPort = browserShellPort
+            if (shellPort > 0) {
+                put("REASONIX_SHELL_BROWSER_PORT", shellPort.toString())
+                // The credential the server checks. Set only alongside the
+                // port: a token with nothing listening would be a variable the
+                // kernel carries for no reason.
+                val shellToken = browserShellToken
+                if (shellToken.isNotBlank()) {
+                    put("REASONIX_SHELL_BROWSER_TOKEN", shellToken)
+                }
+            }
+        }
+        // The agent's folder, not the kernel's. `REASONIX_HOME` above is still
+        // where the config, the sessions and the transcripts live; this is what
+        // the workspace root resolves to, because the kernel reads the working
+        // directory for it.
+        //
+        // The folder the person last opened, when it is still usable — the same
+        // answer the desktop host gives (`launchWorkspace`), and the reason a
+        // phone session used to work in the app's own `files/workspace` while
+        // the sidebar said it was in the shared folder: the launch entry in
+        // `serve-workspaces.json` was written and then ignored, and `write_roots`
+        // is derived from the working directory, so the file tools were confined
+        // to the app's private folder and every write into the shared one was
+        // refused. `workspaceDir` is still the answer for a first run and for a
+        // folder since deleted, but the choice is never silent — see
+        // [launchWorkspaceDir]. `workspace` was resolved above so it could also
+        // be named on the command line.
+        builder.directory(workspace)
+        // `PWD` is what the kernel's own `os.Getwd` prefers: Go uses it whenever
+        // it names the same directory as `.`, which is exactly this case, and it
+        // is the only way to make the kernel resolve its root to the string this
+        // shell chose. Without it `os.Getwd` falls back to the kernel's view of
+        // the mount, and on Android `/storage/emulated/0/...` and the path the
+        // FUSE layer reports for it need not be spelled the same way. The kernel
+        // derives `write_roots` from that root, so the two spellings have to be
+        // the same one.
+        builder.environment().put("PWD", workspace.absolutePath)
+        builder.redirectErrorStream(true)
+        val process = builder.start()
+
+        // The kernel's own log is the only place a startup failure says why, and
+        // a phone has no terminal to read. It is drained on a thread and kept
+        // ring-buffered so the About screen can show the last of it.
+        Thread({ drain(process) }, "kernel-log").apply { isDaemon = true }.start()
+        return process
+    }
+
+    /**
+     * The folder the person last opened, or null when there is not one.
+     *
+     * `serve-workspaces.json` is the kernel's own record of the projects the
+     * sidebar lists, and its `launch` entry is which of them a session starts
+     * in. Both shapes the file has are read — a bare array of paths, and an
+     * object with `paths` and `launch` — because both are written in the wild
+     * and a reader that only knew one would silently fall back.
+     *
+     * The entry has to be one of the listed paths, which is the same rule the
+     * kernel applies when it reads this file (`workspacelist.Read` blanks a
+     * `launch` that is not in `paths`). It matters more here than there: the
+     * working directory decides `write_roots`, so whatever this answers is
+     * where the agent's file tools may write — and on a phone that permission
+     * reaches all of shared storage. A file with a `launch` outside its own
+     * list is one this shell did not write, and it gets the listed answer.
+     *
+     * Null for anything unusable: no file, unreadable JSON, a launch that is
+     * not among the listed folders, an entry that has since been deleted, or a
+     * path that is now a file. Every one of those means the same thing to the
+     * caller — start where this shell always started.
+     */
+    private fun rememberedLaunchDir(): File? {
+        val file = File(home, "serve-workspaces.json")
+        if (!file.isFile) return null
+        val text = runCatching { file.readText() }.getOrNull() ?: return null
+        val launch = runCatching {
+            // A bare array is the file's other shape — the one older kernels
+            // wrote, and therefore the one a person upgrading is most likely to
+            // have. Without this branch `JSONObject(text)` throws on it and the
+            // whole function falls back, which is the same mismatch (the
+            // sidebar naming one folder, the session working in another) this
+            // exists to fix. `withoutHome` below reads both shapes the same way.
+            if (text.trimStart().startsWith("[")) {
+                val arr = JSONArray(text)
+                if (arr.length() == 0) return@runCatching null
+                arr.optString(0)
+            } else {
+                val json = JSONObject(text)
+                val paths = json.optJSONArray("paths")
+                    ?.let { arr -> (0 until arr.length()).mapNotNull { arr.optString(it).takeIf(String::isNotBlank) } }
+                    .orEmpty()
+                if (paths.isEmpty()) return@runCatching null
+                json.optString("launch").takeIf { it.isNotBlank() && it in paths } ?: paths.first()
+            }
+        }.getOrNull()?.takeIf { it.isNotBlank() } ?: return null
+        val dir = runCatching { File(launch) }.getOrNull() ?: return null
+        if (!dir.isDirectory) {
+            // A launch entry this process cannot stat is exactly the failure the
+            // caller exists to avoid, and falling back silently is what made it
+            // take three releases to notice: the session opened in the app's own
+            // folder while the sidebar named the shared one. A phone has no
+            // terminal, so the log is the only place the reason can be said —
+            // and `exists`/`readable` tell apart "deleted" from "not permitted",
+            // which need different answers from the person.
+            Log.w(
+                TAG,
+                "launch entry $launch is not a usable directory " +
+                    "(exists=${dir.exists()}, readable=${dir.canRead()})",
+            )
+            return null
+        }
+        return dir
+    }
+
+    /**
+     * The folder the kernel should start in.
+     *
+     * Either the launch entry — the folder the person last opened, which is
+     * also the one the sidebar shows — or the app's own folder when there is
+     * none. Whichever it is, it is logged, because the two disagreeing is the
+     * bug this exists to fix and a silent choice is what let it survive.
+     */
+    private fun launchWorkspaceDir(): File {
+        val remembered = rememberedLaunchDir()
+        if (remembered != null) {
+            Log.i(TAG, "kernel workspace: ${remembered.absolutePath} (the remembered launch project)")
+            return remembered
+        }
+        Log.i(TAG, "kernel workspace: ${workspaceDir.absolutePath} (no remembered launch project)")
+        return workspaceDir
+    }
+
+    private val logLines = ArrayDeque<String>()
+
+    private fun drain(process: Process) {
+        runCatching {
+            process.inputStream.bufferedReader().useLines { lines ->
+                lines.forEach { line ->
+                    Log.i(TAG, line)
+                    synchronized(logLines) {
+                        logLines.addLast(line)
+                        while (logLines.size > LOG_KEEP) logLines.removeFirst()
+                    }
+                }
+            }
+        }
+    }
+
+    /** The kernel's tail, newest last, for a bug report or the About screen. */
+    fun recentLog(): String = synchronized(logLines) { logLines.joinToString("\n") }
+
+    private fun awaitPort(process: Process): String {
+        val deadline = System.currentTimeMillis() + START_TIMEOUT_MS
+        while (System.currentTimeMillis() < deadline) {
+            if (!process.isAlive) {
+                throw IllegalStateException("内核启动即退出。\n${recentLog().takeLast(2000)}")
+            }
+            val text = if (portFile.isFile) runCatching { portFile.readText().trim() }.getOrNull() else null
+            // The file is written by the kernel on the way to serving, and the
+            // kernel rewrites it with the real port when it was given :0.
+            if (!text.isNullOrBlank() && text.contains(":")) return text
+            Thread.sleep(POLL_MS)
+        }
+        throw IllegalStateException("内核在 ${START_TIMEOUT_MS / 1000}s 内没有报告监听地址。\n${recentLog().takeLast(2000)}")
+    }
+
+    /**
+     * Wait until the bound port answers.
+     *
+     * A port that is open but not yet serving is the normal first second of a
+     * kernel's life; a WebView pointed at it would show a connection error and
+     * cache the failure, so the wait belongs here rather than in the page.
+     */
+    private fun awaitServing(process: Process, origin: String) {
+        val deadline = System.currentTimeMillis() + START_TIMEOUT_MS
+        while (System.currentTimeMillis() < deadline) {
+            if (!process.isAlive) {
+                throw IllegalStateException("内核在开始服务前退出。\n${recentLog().takeLast(2000)}")
+            }
+            if (probe("$origin/")) return
+            Thread.sleep(POLL_MS)
+        }
+        throw IllegalStateException("内核已监听 $origin，但页面没有响应。\n${recentLog().takeLast(2000)}")
+    }
+
+    private fun probe(url: String): Boolean = runCatching {
+        (URL(url).openConnection() as HttpURLConnection).run {
+            connectTimeout = 1000
+            readTimeout = 1000
+            requestMethod = "GET"
+            try {
+                responseCode in 200..399
+            } finally {
+                disconnect()
+            }
+        }
+    }.getOrDefault(false)
+
+    private companion object {
+        const val TAG = "ReasonixKernel"
+        const val LOG_KEEP = 400
+        const val POLL_MS = 120L
+        const val START_TIMEOUT_MS = 30_000L
+    }
+}
@@ -0,0 +1,139 @@
+package io.reasonix.mobile.app
+
+import android.Manifest
+import android.app.Notification
+import android.app.PendingIntent
+import android.app.Service
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.content.pm.ServiceInfo
+import android.os.Build
+import android.os.IBinder
+import androidx.core.app.NotificationCompat
+import androidx.core.app.NotificationManagerCompat
+import androidx.core.app.ServiceCompat
+import androidx.core.content.ContextCompat
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.launch
+
+/**
+ * Keeps the kernel alive while the app is not on screen.
+ *
+ * The reason this exists at all: an agent turn that takes minutes is a normal
+ * turn, and Android reclaims a backgrounded app's child process within seconds
+ * of the screen going off. Without the service, pocketing the phone would kill
+ * a running task — the one failure mode that makes a phone a bad client for
+ * something that works on its own.
+ *
+ * A foreground service needs a notification the person can see, which is also
+ * the honest thing to show: the kernel is running and what it is doing lives on
+ * another machine.
+ */
+class KernelService : Service() {
+
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
+
+    override fun onBind(intent: Intent?): IBinder? = null
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        // Promoted before `start()`: a service that starts work first and
+        // notifies after has a window in which the system may kill it, and the
+        // work it would have been protecting is exactly what is being started.
+        startForegroundNotification()
+
+        val kernel = (application as App).kernel
+        scope.launch {
+            kernel.start().onFailure { failure ->
+                // A kernel that will not start is a fact the person needs, and a
+                // notification that only ever said "running" would be a lie.
+                notify(SERVICE_NOTICE, getString(R.string.notify_failed_title), failure.message.orEmpty())
+                stopSelf()
+            }
+        }
+        // Sticky, so a kernel killed under memory pressure comes back when there
+        // is room — which is what a person who left a task running expects.
+        return START_STICKY
+    }
+
+    override fun onDestroy() {
+        scope.cancel()
+        super.onDestroy()
+    }
+
+    private fun startForegroundNotification() {
+        val notification = buildNotification(
+            getString(R.string.notify_running_title),
+            getString(R.string.notify_running_body),
+        )
+        // `dataSync` matches the manifest's declaration. On 34+ the type is
+        // mandatory and a mismatch throws, so it is named in both places.
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+            ServiceCompat.startForeground(
+                this,
+                SERVICE_NOTICE,
+                notification,
+                ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC,
+            )
+        } else {
+            startForeground(SERVICE_NOTICE, notification)
+        }
+    }
+
+    private fun buildNotification(title: String, body: String): Notification {
+        val open = PendingIntent.getActivity(
+            this,
+            0,
+            Intent(this, MainActivity::class.java).apply {
+                flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP
+            },
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+        )
+        return NotificationCompat.Builder(this, App.CHANNEL_KERNEL)
+            .setSmallIcon(R.drawable.ic_notification)
+            .setContentTitle(title)
+            .setContentText(body)
+            .setContentIntent(open)
+            // The notification is a receipt, not an alarm; swiping it away
+            // leaves the kernel running, which is what the person meant by
+            // swiping it.
+            .setOngoing(false)
+            .setSilent(true)
+            .setPriority(NotificationCompat.PRIORITY_MIN)
+            .build()
+    }
+
+    private fun notify(id: Int, title: String, body: String) {
+        // The notification permission is granted at runtime from Android 13 and
+        // the person can refuse it. Without this check the call throws
+        // SecurityException and takes the service down with it — the opposite of
+        // what a notification that could not be shown should do. Below 13 the
+        // permission does not exist and posting always succeeds.
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU &&
+            ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) !=
+            PackageManager.PERMISSION_GRANTED
+        ) {
+            return
+        }
+        runCatching {
+            NotificationManagerCompat.from(this).notify(id, buildNotification(title, body))
+        }
+    }
+
+    companion object {
+        private const val SERVICE_NOTICE = 1
+
+        /** Idempotent: called on every start of the activity, and by the boot
+         *  path, and safe to repeat. */
+        fun start(context: Context) {
+            ContextCompat.startForegroundService(context, Intent(context, KernelService::class.java))
+        }
+
+        fun stop(context: Context) {
+            context.stopService(Intent(context, KernelService::class.java))
+        }
+    }
+}
@@ -0,0 +1,744 @@
+package io.reasonix.mobile.app
+
+import android.content.ClipData
+import android.content.ClipboardManager
+import android.content.ContentValues
+import android.content.Context
+import android.content.res.Configuration
+import android.net.Uri
+import android.os.Build
+import android.os.Environment
+import android.os.Handler
+import android.os.Looper
+import android.provider.MediaStore
+import android.webkit.JavascriptInterface
+import android.webkit.MimeTypeMap
+import java.io.File
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * What the page can ask the phone for.
+ *
+ * This is the whole surface, and it is deliberately tiny. Android's
+ * `@JavascriptInterface` is a bridge into the app's process from a WebView whose
+ * content is a web page: every method here is reachable by anything that can run
+ * script in that page, so each one is written as a verb with no address
+ * parameter it does not need, and none of them can name a path outside the
+ * kernel's own home.
+ *
+ * It is deliberately *not* the Electron preload bridge. That one exposes window
+ * management, a filesystem walker, an editor launcher and a browser view host —
+ * all of which are meaningless on a phone, and the two that were not (open a URL,
+ * save a file) already have a way to happen here: `WebViewClient` routes external
+ * links to the browser, and the page's own download reaches the WebView's
+ * `DownloadListener`.
+ *
+ * The one thing a phone must add is `importIntoHome`: the kernel runs on this
+ * device and can only read paths under its own home, so a private key the person
+ * has in their Documents folder has to be copied across. Nothing else the page
+ * wants is out of its reach.
+ */
+class NativeBridge(
+    private val context: Context,
+    private val kernel: Kernel,
+    private val onOpen: (String) -> Unit,
+) {
+
+    /**
+     * Whether the document calling may use this bridge.
+     *
+     * `addJavascriptInterface` makes the object reachable from whatever page the
+     * WebView holds, so a link the model produced — or a cleartext page on the
+     * LAN — would otherwise get `importIntoHome`, `pickFolder`, `hostCall` and
+     * the clipboard. The activity answers by comparing the main frame's origin
+     * against the kernel's and the one paired computer the person confirmed.
+     *
+     * Anything that reaches the device checks this first. The five methods that
+     * do not — version, systemTheme, safeArea, setLayerOpen, setRunning — report
+     * back what the page already knows about its own window and grant nothing.
+     */
+    var trusted: () -> Boolean = { false }
+
+    /** The version the page reads to decide whether this bridge is the one it
+     *  knows. Bumped when a method's contract changes, not when one is added. */
+    @JavascriptInterface
+    fun version(): String = BRIDGE_VERSION
+
+    /**
+     * Copy a file the person picks into the kernel's home, answering with its
+     * path there — or "" when they dismissed the picker.
+     *
+     * `kind` names the directory inside the home, because that is a fact about
+     * the kernel's layout and not about the file: an SSH private key belongs in
+     * `.ssh`, and a dotenv the kernel reads for passphrases belongs at the root
+     * of the home where `config.Load` looks for it.
+     *
+     * The path that comes back is *inside the home*, never the document
+     * provider's URI. That is the point: the kernel is a child process with no
+     * access to the provider, so a `content://` would be a path it cannot open.
+     */
+    @JavascriptInterface
+    fun importIntoHome(kind: String, name: String): String {
+        if (!trusted()) return ""
+        val dir = when (kind) {
+            "identity" -> File(kernel.homeDir(), ".ssh")
+            "env" -> kernel.homeDir()
+            else -> return ""
+        }
+        val safeName = sanitise(name)
+        if (safeName.isEmpty()) return ""
+
+        val picked = pickFile() ?: return ""
+        return try {
+            dir.mkdirs()
+            val target = File(dir, safeName)
+            context.contentResolver.openInputStream(picked)?.use { input ->
+                target.outputStream().use { output -> input.copyTo(output) }
+            } ?: return ""
+            // A private key with group or world read is one OpenSSH refuses to
+            // use, and the refusal reads as "bad permissions" from a long way
+            // away. Setting it here is what makes the file usable at all.
+            if (kind == "identity") {
+                runCatching {
+                    target.setReadable(false, false)
+                    target.setReadable(true, true)
+                    target.setWritable(false, false)
+                    target.setWritable(true, true)
+                }
+            }
+            target.absolutePath
+        } catch (_: Exception) {
+            // A copy that failed leaves nothing behind; the caller sees "" and
+            // the person can try again.
+            ""
+        }
+    }
+
+    /**
+     * Open a URL in the device's browser.
+     *
+     * The page asks for this when a link points somewhere outside the kernel —
+     * a provider's console, a documentation page — and loading it in place would
+     * strand the person in a window with no address bar and no way back.
+     */
+    @JavascriptInterface
+    fun openExternal(url: String) {
+        if (!trusted()) return
+        // Only what a browser can open. A `file://` or `content://` here would
+        // be the page reaching into the device through a method named for
+        // leaving it.
+        if (!url.startsWith("http://") && !url.startsWith("https://")) return
+        onOpen(url)
+    }
+
+    /** Put text on the clipboard. A WebView's own `navigator.clipboard` write is
+     *  gated behind a permission Android grants only to a focused document, so
+     *  the one thing the page actually offers to copy — a token, a command, a
+     *  path — has no other way out.
+     *
+     *  Answers whether the write landed. A platform that refuses it raises
+     *  rather than answering, and an exception must not cross
+     *  `@JavascriptInterface` as a silent success — the page would say 已复制
+     *  over an empty clipboard. Caught here, the answer is the one the caller
+     *  can act on: false, and the button says 复制失败 instead. */
+    @JavascriptInterface
+    fun copyText(text: String): Boolean = if (!trusted()) false else runCatching {
+        val clipboard = context.getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
+        clipboard.setPrimaryClip(ClipData.newPlainText("reasonix", text))
+    }.isSuccess
+
+    /**
+     * Write text where the person picks, and answer with the path it went to.
+     *
+     * The page's own route to a file — a blob URL on an `<a download>` — reaches
+     * nothing here: a WebView has no downloads shelf, and its `DownloadListener`
+     * fires only for a real navigation, not for a blob the page just built. So
+     * the text crosses the bridge and the shell opens the system's document
+     * picker, which is also the only way to reach a folder the person can find
+     * again afterwards.
+     *
+     * "" is a dismissal, the same answer `importIntoHome` gives, and the page
+     * reads the two the same way.
+     */
+    /**
+     * Put a copy of a file where a phone's own file manager will show it.
+     *
+     * `saveText` asks the person where to put it, which is the right question
+     * on a desktop and the wrong one here: the kernel's workspace is
+     * app-private storage, so the file someone wants is in a place no file
+     * manager can open, and a picker that starts at "recent" is another place
+     * to lose it. This answers the actual question — "where is it" — by
+     * putting it in Downloads, in a folder named after the app, under a name
+     * that is the file's own.
+     *
+     * The answer is the path relative to shared storage, so the page can say
+     * where the file went rather than only that it worked. "" means the write
+     * failed or the platform refused it.
+     *
+     * MediaStore on Android 10 and later, a plain file before that. The two
+     * are not interchangeable: from 10 the app may not write another app's
+     * files directly, and MediaStore is the only way in; before it there is no
+     * MediaStore collection for downloads and the public directory is writable
+     * with the storage permission this app does not ask for, so that branch is
+     * best-effort and says so by answering "".
+     */
+    @JavascriptInterface
+    fun exportToDownloads(name: String, content: String): String {
+        if (!trusted()) return ""
+        val safeName = sanitise(name).ifEmpty { "reasonix.txt" }
+        return exportFile(safeName, content).orEmpty()
+    }
+
+    @JavascriptInterface
+    fun saveText(name: String, content: String): String {
+        if (!trusted()) return ""
+        val safeName = sanitise(name).ifEmpty { "reasonix.txt" }
+        return saveFile(safeName, content) ?: ""
+    }
+
+    /**
+     * Hand text to whatever the device shares with — a chat app, the mail
+     * client, a note app.
+     *
+     * The share sheet rather than a second save dialog: "where is that file"
+     * is the question this answers, and on a phone a document someone wants to
+     * keep or send usually goes through one of those apps rather than a folder.
+     *
+     * Shared as text with the filename as its subject, which is what every
+     * target understands. A file attachment would need a `FileProvider` and a
+     * cache copy for the same words to arrive.
+     */
+    @JavascriptInterface
+    fun shareText(name: String, content: String): Boolean {
+        if (!trusted()) return false
+        val safeName = sanitise(name).ifEmpty { "reasonix.txt" }
+        val posted = java.util.concurrent.CountDownLatch(1)
+        var ok = false
+        main.post {
+            ok = runCatching { askForShare(safeName, content) }.getOrDefault(false)
+            posted.countDown()
+        }
+        runCatching { posted.await(SHARE_TIMEOUT_SECONDS, TimeUnit.SECONDS) }
+        return ok
+    }
+
+    /**
+     * The device's own light/dark answer.
+     *
+     * The page resolves its theme from `localStorage` first and only asks the
+     * system when nothing is saved, so this is what makes a fresh install match
+     * the phone instead of defaulting to light.
+     */
+    @JavascriptInterface
+    fun systemTheme(): String {
+        val night = context.resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK
+        return if (night == Configuration.UI_MODE_NIGHT_YES) "dark" else "light"
+    }
+
+    /**
+     * The window's real safe-area insets, in CSS pixels, as
+     * `top,right,bottom,left`.
+     *
+     * A WebView does not implement `env(safe-area-inset-*)`: those are an iOS
+     * Safari feature, and on Android every one of them resolves to `0`. So a
+     * page that pads itself with them — which `mobile.css` does — is un-padded
+     * on exactly the platform this shell exists for, and the first line of the
+     * interface sits under the status bar.
+     *
+     * The values have to come from here for a second reason too: from Android 15
+     * the window is edge-to-edge whether the app asks for it or not, so the bars
+     * really are drawn over the page and there is no window-manager switch that
+     * could move the content back down.
+     *
+     * Answered as a string because that is what crosses the bridge; the page
+     * sets it as a CSS custom property and `mobile.css` reads it.
+     */
+    @JavascriptInterface
+    fun safeArea(): String {
+        val insets = onInsets?.invoke() ?: return "0,0,0,0"
+        return "${insets.left},${insets.top},${insets.right},${insets.bottom}"
+    }
+
+    /**
+     * Read the pairing code a computer is showing.
+     *
+     * A phone cannot type what a computer renders as a QR code — it is a
+     * one-time code inside a URL, and the whole reason it is a picture is that
+     * nobody reads one aloud. So the page asks for the camera and gets the text
+     * back, which is the same direction the computer's own dialog describes.
+     *
+     * The answer is the code's own text, not a parsed result: what a pairing
+     * fragment means is the page's to decide, and it already knows how — the
+     * `#pair=` handling ships with the interface.
+     */
+    @JavascriptInterface
+    fun scanPairingCode(): String = if (!trusted()) "" else scanWithCamera()
+
+    /**
+     * Load a URL in this window instead of handing it to the browser.
+     *
+     * The page asks for this once, right after a scan: the code it read points at
+     * the computer's own Studio, and the whole point of scanning is to end up
+     * looking at that computer. Going out to a browser would leave the app on one
+     * screen and the paired machine on another, with the back gesture an exit
+     * rather than a return.
+     *
+     * Only http and https are accepted. The page is this repository's own build
+     * and is trusted, but a scanner reads whatever is held in front of it, so the
+     * one value that arrives here from outside is checked: a `file://` or
+     * `javascript:` that happened to be on a printed code must not become a
+     * navigation.
+     */
+    @JavascriptInterface
+    fun openInApp(url: String) {
+        if (!trusted()) return
+        val trimmed = url.trim()
+        if (!trimmed.startsWith("http://") && !trimmed.startsWith("https://")) return
+        main.post { onOpenInApp?.invoke(trimmed) }
+    }
+
+    /** How the activity loads a URL in the window it owns. Set by the activity. */
+    var onOpenInApp: ((String) -> Unit)? = null
+
+    // ---- the native browser view host bridge ----
+    //
+    // The page's `host.ts` looks for `window.reasonixHost` with Promise-based
+    // methods (showBrowserView, hideBrowserView, etc.). `@JavascriptInterface`
+    // is synchronous, so the round trip is: JS generates an id, calls
+    // `hostCall(id, method, args)`, Kotlin does the work asynchronously, then
+    // pushes the result back via `evaluateJavascript` calling
+    // `window.__reasonixHostReply(id, json)`. The injected script (in
+    // MainActivity) wires each Promise to that reply channel.
+
+    /** How the activity handles an async host call. Set by the activity. */
+    var onHostCall: ((id: String, method: String, args: String) -> Unit)? = null
+
+    /**
+     * Entry point for the page's `window.reasonixHost` Promise methods.
+     *
+     * `id` is a unique call identifier the JS side generated; `method` is the
+     * method name (e.g. "showBrowserView"); `args` is the JSON-encoded argument
+     * array. The activity handles the call asynchronously and replies through
+     * `evaluateJavascript` with `window.__reasonixHostReply(id, resultJson)`.
+     */
+    @JavascriptInterface
+    fun hostCall(id: String, method: String, args: String) {
+        if (!trusted()) return
+        onHostCall?.invoke(id, method, args)
+    }
+
+    /**
+     * Whether the page has a panel up that the back gesture should close first.
+     *
+     * Written by the page, read by the activity's back handler. The page owns the
+     * answer — it is the only thing that knows what is open, and a second
+     * implementation of that question in the shell would be one that drifts — so
+     * the page reports the fact and the shell keeps the action.
+     *
+     * Volatile because the two ends are on different threads: the page sets it
+     * from the WebView's JavaScript thread, the back gesture reads it on the main
+     * one, and a stale read here is a panel that does not close.
+     */
+    @Volatile
+    var layerOpen: Boolean = false
+        private set
+
+    @JavascriptInterface
+    fun setLayerOpen(open: Boolean) {
+        layerOpen = open
+    }
+
+    // ---- the picker, which is an Activity result in a synchronous world ----
+
+    private val pending = AtomicReference<Uri?>(null)
+    private val latch = AtomicReference<CountDownLatch?>(null)
+
+    /** The code the camera read, held between the activity's answer and the
+     *  wait below — the same round trip the file picker takes. */
+    private val scanned = AtomicReference<String?>(null)
+    private val scanLatch = AtomicReference<CountDownLatch?>(null)
+
+    /** The main thread, because starting an Activity result must happen there. */
+    private val main = Handler(Looper.getMainLooper())
+
+    /**
+     * How to ask for a file. Set by the activity, which owns the Activity Result
+     * API; it answers whether the ask was dispatched, not whether the person
+     * picked anything — that arrives through `deliver`.
+     */
+    var askForFile: () -> Boolean = { false }
+
+    /**
+     * How the activity reports the window's insets. Set by the activity, which is
+     * the only thing that can see them, and asked on every call rather than
+     * cached — a rotation, a fold, or the keyboard opening all change them, and a
+     * stale answer here is a stripe of interface under the status bar.
+     */
+    var onInsets: (() -> Insets?)? = null
+
+    /**
+     * How to open the camera. Set by the activity, which owns the Activity
+     * Result API; like `askForFile` it answers whether the ask was dispatched,
+     * and the code itself arrives through `deliverScan`.
+     */
+    var askForScan: () -> Boolean = { false }
+
+    /**
+     * How to put a file where the person picks. Set by the activity, which owns
+     * the Activity Result API; it answers whether the ask was dispatched, and
+     * the chosen place arrives through `deliverSave`.
+     */
+    var askForSave: (name: String, content: String) -> Boolean = { _, _ -> false }
+
+    /**
+     * How to open the share sheet. Set by the activity, which is the only thing
+     * that can start an Intent; it answers whether anything on the device took
+     * the text.
+     */
+    var askForShare: (name: String, content: String) -> Boolean = { _, _ -> false }
+
+    /** The place the save dialog answered with, held between the two halves. */
+    private val saveTarget = AtomicReference<Uri?>(null)
+    private val saveLatch = AtomicReference<CountDownLatch?>(null)
+
+    /**
+     * Ask where to put a file and write it there.
+     *
+     * The same latch round trip as `pickFile`, and for the same reason:
+     * `@JavascriptInterface` cannot suspend, so the WebView's thread waits while
+     * the picker is open — a modal panel the person is looking at.
+     */
+    private fun saveFile(name: String, content: String): String? {
+        val gate = CountDownLatch(1)
+        saveLatch.set(gate)
+        saveTarget.set(null)
+
+        val posted = CountDownLatch(1)
+        var dispatched = false
+        main.post {
+            dispatched = runCatching { askForSave(name, content) }.getOrDefault(false)
+            posted.countDown()
+        }
+        val ready = runCatching { posted.await(PICK_TIMEOUT_SECONDS, TimeUnit.SECONDS) }.getOrDefault(false)
+        if (!ready || !dispatched) {
+            saveLatch.set(null)
+            return null
+        }
+        return try {
+            if (!gate.await(PICK_TIMEOUT_SECONDS, TimeUnit.SECONDS)) null
+            else saveTarget.get()?.toString()
+        } catch (_: InterruptedException) {
+            null
+        } finally {
+            saveLatch.set(null)
+        }
+    }
+
+    /** Called by the activity once the bytes are written. A null uri is a dismissal. */
+    fun deliverSave(uri: Uri?) {
+        saveTarget.set(uri)
+        saveLatch.get()?.countDown()
+    }
+
+    /**
+     * Read the pairing code a computer is showing, and return it.
+     *
+     * The same shape as `pickFile` and for the same reason: a
+     * `@JavascriptInterface` method is called on the WebView's thread and must
+     * return a value, so the camera is opened on the main thread and this one
+     * waits. The block lasts as long as the person is aiming, which is why the
+     * timeout is generous — a scan that gave up after a few seconds would be
+     * one nobody could complete.
+     *
+     * An empty string is "no code", which is what a refusal, a cancellation and
+     * a timeout all are. The caller acts on the text, so a distinct error would
+     * only be a fourth way to say the same thing.
+     */
+    private fun scanWithCamera(): String {
+        val gate = CountDownLatch(1)
+        scanLatch.set(gate)
+        scanned.set(null)
+
+        val posted = CountDownLatch(1)
+        var dispatched = false
+        main.post {
+            dispatched = runCatching { askForScan() }.getOrDefault(false)
+            posted.countDown()
+        }
+        val ready = runCatching { posted.await(SCAN_TIMEOUT_SECONDS, TimeUnit.SECONDS) }.getOrDefault(false)
+        if (!ready || !dispatched) {
+            scanLatch.set(null)
+            return ""
+        }
+        return try {
+            if (!gate.await(SCAN_TIMEOUT_SECONDS, TimeUnit.SECONDS)) "" else scanned.get().orEmpty()
+        } catch (_: InterruptedException) {
+            ""
+        } finally {
+            scanLatch.set(null)
+        }
+    }
+
+    /** Called by the activity when the scanner answers. Null is a dismissal. */
+    fun deliverScan(text: String?) {
+        scanned.set(text)
+        scanLatch.get()?.countDown()
+    }
+
+    /**
+     * Ask for one file and wait for the answer.
+     *
+     * `@JavascriptInterface` methods cannot suspend: the WebView calls them on
+     * its own thread and expects a value back. So the ask is posted to the main
+     * thread and this one waits on a latch. The cost is a blocked JS thread for
+     * as long as the picker is open — which is a modal panel the person is
+     * looking at, with nothing else in the page running.
+     *
+     * A timeout is set rather than waiting forever: a picker that never answers
+     * (the activity destroyed underneath it) would otherwise pin a WebView
+     * thread until the process died.
+     */
+    private fun pickFile(): Uri? {
+        val gate = CountDownLatch(1)
+        latch.set(gate)
+        pending.set(null)
+
+        val posted = CountDownLatch(1)
+        var dispatched = false
+        main.post {
+            dispatched = runCatching { askForFile() }.getOrDefault(false)
+            posted.countDown()
+        }
+        val ready = runCatching { posted.await(PICK_TIMEOUT_SECONDS, TimeUnit.SECONDS) }.getOrDefault(false)
+        if (!ready || !dispatched) {
+            latch.set(null)
+            return null
+        }
+
+        return try {
+            if (!gate.await(PICK_TIMEOUT_SECONDS, TimeUnit.SECONDS)) null else pending.get()
+        } catch (_: InterruptedException) {
+            null
+        } finally {
+            latch.set(null)
+        }
+    }
+
+    /** Called by the activity when the picker answers. A null uri is a dismissal. */
+    fun deliver(uri: Uri?) {
+        pending.set(uri)
+        latch.get()?.countDown()
+    }
+
+    /** The folder under Downloads that this app's exports land in. */
+    private fun exportFolder(): String = "Reasonix"
+
+    /** The MIME type this name declares, or null when the platform does not know
+     *  it.
+     *
+     * Where the type is written, the name and the type agree, and that agreement
+     * is the whole fix: `.md` is answered `text/markdown` here, so MediaStore
+     * has nothing to correct and the export stays `报告.md` instead of being
+     * renamed `报告.md.txt` by the `text/plain` it used to be given. Where the
+     * type is unknown the field is left off, which leaves MediaStore to derive
+     * the same `application/octet-stream` it would have been told — the name
+     * still stands on its own, which is all this is for. */
+    private fun mimeFor(name: String): String? {
+        val ext = name.substringAfterLast('.', "").lowercase()
+        if (ext.isEmpty() || ext == name.lowercase()) return null
+        return runCatching { MimeTypeMap.getSingleton().getMimeTypeFromExtension(ext) }.getOrNull()
+    }
+
+    private fun exportFile(name: String, content: String): String? = runCatching {
+        val bytes = content.toByteArray(Charsets.UTF_8)
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+            val resolver = context.contentResolver
+            val values = ContentValues().apply {
+                put(MediaStore.Downloads.DISPLAY_NAME, name)
+                // The type is derived here rather than declared, and it is
+                // written only when the name really has an extension that maps
+                // to one.
+                //
+                // It used to be `text/plain` for everything, and MediaStore
+                // answers a name whose extension disagrees with the declared
+                // type by appending its own: exporting `报告.md` landed in
+                // Downloads as `报告.md.txt`, and any source file came out with
+                // the wrong second extension. Deriving the type from the name
+                // instead keeps the two in agreement — which is what stops the
+                // rename — and a name the platform has no type for is left off
+                // entirely rather than declared as `application/octet-stream`,
+                // so nothing is corrected there either.
+                mimeFor(name)?.let { put(MediaStore.Downloads.MIME_TYPE, it) }
+                put(
+                    MediaStore.Downloads.RELATIVE_PATH,
+                    Environment.DIRECTORY_DOWNLOADS + "/" + exportFolder(),
+                )
+                // Hidden until the bytes are all there, so a file manager that
+                // reads the folder mid-write cannot show half a document.
+                put(MediaStore.Downloads.IS_PENDING, 1)
+            }
+            val uri = resolver.insert(MediaStore.Downloads.EXTERNAL_CONTENT_URI, values)
+                ?: return@runCatching null
+            resolver.openOutputStream(uri)?.use { it.write(bytes) } ?: return@runCatching null
+            values.clear()
+            values.put(MediaStore.Downloads.IS_PENDING, 0)
+            resolver.update(uri, values, null, null)
+            "${Environment.DIRECTORY_DOWNLOADS}/${exportFolder()}/$name"
+        } else {
+            val dir = File(
+                Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOWNLOADS),
+                exportFolder(),
+            )
+            if (!dir.exists() && !dir.mkdirs()) return@runCatching null
+            val target = File(dir, name)
+            target.writeBytes(bytes)
+            target.absolutePath
+        }
+    }.getOrNull()
+
+    private fun sanitise(name: String): String {
+        // A name from the page is used as a filename, so it is reduced to one:
+        // no separators, no traversal, and nothing a filesystem treats as
+        // special. The default is the name the field it came from suggests.
+        val trimmed = name.trim().substringAfterLast('/').substringAfterLast('\\')
+        if (trimmed.isEmpty() || trimmed == "." || trimmed == "..") return ""
+        return trimmed.filter { it.isLetterOrDigit() || it in "._-" }.take(64)
+    }
+
+    /**
+     * Whether a turn is running, so the screen can be kept awake for one.
+     *
+     * The page owns the answer — it is the only thing that knows if the kernel
+     * is working — and the shell owns the flag, because a window flag is not
+     * something a page can set. Nothing is asked at launch: a window that is
+     * merely open is one the person may be reading, and holding the screen on
+     * for that is holding it on for nothing.
+     */
+    @JavascriptInterface
+    fun setRunning(running: Boolean) {
+        onRunning?.invoke(running)
+    }
+
+    /** How the activity applies that flag. Set by the activity. */
+    var onRunning: ((Boolean) -> Unit)? = null
+
+    /**
+     * Whether the app may read every file, which is what lets the kernel open a
+     * folder on this phone as a workspace.
+     *
+     * Asked rather than assumed: the permission is granted by hand in system
+     * settings, so the page has to be able to say "not yet" rather than fail on
+     * the first `stat`. Answered `true` below API 30, where ordinary read
+     * permission is enough and the concept does not exist.
+     */
+    @JavascriptInterface
+    fun hasAllFilesAccess(): Boolean = filesAccess?.invoke() ?: true
+
+    var filesAccess: (() -> Boolean)? = null
+
+    /** Open the system page where that permission is granted. The only place
+     *  Android offers it — there is no dialog for this one. */
+    @JavascriptInterface
+    fun requestAllFilesAccess() {
+        if (!trusted()) return
+        askForFilesAccess?.invoke()
+    }
+
+    var askForFilesAccess: (() -> Unit)? = null
+
+    /**
+     * Whether this app is exempt from the system's battery optimisation.
+     *
+     * A turn runs in a child process under a foreground service. Under doze the
+     * whole app group is frozen anyway, so the turn stops making progress while
+     * the screen is off — which is the state the person left it in on purpose.
+     * Unrestricted is the answer, and it is a question Android answers.
+     */
+    @JavascriptInterface
+    fun batteryUnrestricted(): Boolean = if (!trusted()) false else (batteryFree?.invoke() ?: true)
+
+    var batteryFree: (() -> Boolean)? = null
+
+    /** Ask for that exemption. Unlike the storage one, this has a real dialog. */
+    @JavascriptInterface
+    fun requestBatteryUnrestricted() {
+        if (!trusted()) return
+        askForBattery?.invoke()
+    }
+
+    var askForBattery: (() -> Unit)? = null
+
+    /**
+     * Ask for a folder on this phone and answer with its real filesystem path.
+     *
+     * "" is a dismissal, the same answer `importIntoHome` gives — and, unlike
+     * that one, an empty string is a normal outcome here rather than a failure.
+     * The `startIn` hint is a path the kernel knows; the picker may ignore it,
+     * which is the picker's business.
+     *
+     * The round trip is the same latch as `pickFile`, for the same reason: a
+     * document-tree picker is another activity, and this call cannot suspend.
+     */
+    @JavascriptInterface
+    fun pickFolder(startIn: String): String {
+        if (!trusted()) return ""
+        val gate = CountDownLatch(1)
+        folderLatch.set(gate)
+        folderPending.set(null)
+
+        val posted = CountDownLatch(1)
+        var dispatched = false
+        main.post {
+            dispatched = runCatching { askForFolder(startIn) }.getOrDefault(false)
+            posted.countDown()
+        }
+        val ready = runCatching { posted.await(PICK_TIMEOUT_SECONDS, TimeUnit.SECONDS) }.getOrDefault(false)
+        if (!ready || !dispatched) {
+            folderLatch.set(null)
+            return ""
+        }
+        return try {
+            if (!gate.await(PICK_TIMEOUT_SECONDS, TimeUnit.SECONDS)) "" else folderPending.get().orEmpty()
+        } catch (_: InterruptedException) {
+            ""
+        } finally {
+            folderLatch.set(null)
+        }
+    }
+
+    var askForFolder: (String) -> Boolean = { false }
+
+    private val folderPending = AtomicReference<String?>(null)
+    private val folderLatch = AtomicReference<CountDownLatch?>(null)
+
+    /** Called by the activity with the folder's real path, or null on dismissal. */
+    fun deliverFolder(path: String?) {
+        folderPending.set(path ?: "")
+        folderLatch.get()?.countDown()
+    }
+
+    companion object {
+        const val BRIDGE_VERSION = "4"
+        private const val PICK_TIMEOUT_SECONDS = 5L * 60
+
+        /** Long, because this is however long someone takes to aim. A shorter
+         *  one would turn "still lining it up" into a failed scan. */
+        private const val SCAN_TIMEOUT_SECONDS = 5L * 60
+
+        /** Only as long as the sheet takes to appear: the answer is "something
+         *  took it", which is known the moment the Intent resolves. */
+        private const val SHARE_TIMEOUT_SECONDS = 15L
+    }
+}
+
+/**
+ * The window's insets, in CSS pixels.
+ *
+ * A named type rather than four numbers because the page reads them as one
+ * thing: half an inset is a layout that is wrong in one direction, and a caller
+ * that passed the wrong pair would be indistinguishable from a device with no
+ * cutout at all.
+ */
+data class Insets(val left: Int, val top: Int, val right: Int, val bottom: Int)
@@ -0,0 +1,66 @@
+package io.reasonix.mobile.app
+
+import androidx.camera.core.ImageProxy
+import com.google.zxing.BarcodeFormat
+import com.google.zxing.BinaryBitmap
+import com.google.zxing.DecodeHintType
+import com.google.zxing.MultiFormatReader
+import com.google.zxing.PlanarYUVLuminanceSource
+import com.google.zxing.common.HybridBinarizer
+
+/**
+ * Reading a QR code out of one camera frame.
+ *
+ * ZXing core and nothing else: it is pure Java, so it runs identically on a
+ * phone with Google Play Services and on one whose HarmonyOS compatibility
+ * layer has none. A decoder that leaned on ML Kit would work on the machine it
+ * was written on and fail on the one that needs it.
+ *
+ * The frame arrives as YUV_420_888, whose Y plane is already the greyscale
+ * bitmap ZXing wants — no conversion, no colour maths, just the bytes. That is
+ * the whole reason a phone can decode 30 frames a second without warming up.
+ */
+object Qr {
+
+    private val reader = MultiFormatReader().apply {
+        setHints(
+            mapOf(
+                // Only the form the computer actually renders. Leaving the
+                // reader open to every 1D barcode makes each frame slower for
+                // a case that cannot occur, and a slower frame is a code that
+                // has already left the viewfinder.
+                DecodeHintType.POSSIBLE_FORMATS to listOf(BarcodeFormat.QR_CODE),
+                DecodeHintType.TRY_HARDER to true,
+            ),
+        )
+    }
+
+    /** The code's text, or null when this frame holds none. */
+    fun decode(image: ImageProxy): String? {
+        val plane = image.planes.firstOrNull() ?: return null
+        val buffer = plane.buffer
+        val data = ByteArray(buffer.remaining())
+        buffer.get(data)
+        // `rowStride` is padded to a hardware alignment and is usually wider
+        // than the picture. Passing the width as the row length is what tells
+        // ZXing where each row actually ends; getting it wrong shears the image
+        // and every code reads as garbage.
+        val source = PlanarYUVLuminanceSource(
+            data,
+            plane.rowStride,
+            image.height,
+            0,
+            0,
+            image.width,
+            image.height,
+            false,
+        )
+        return runCatching {
+            reader.decodeWithState(BinaryBitmap(HybridBinarizer(source))).text
+        }.getOrNull().also {
+            // The reader keeps per-frame state between calls; resetting is what
+            // stops a partial match in one frame from corrupting the next.
+            reader.reset()
+        }
+    }
+}
@@ -0,0 +1,146 @@
+package io.reasonix.mobile.app
+
+import android.Manifest
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.os.Bundle
+import android.view.Gravity
+import android.view.ViewGroup
+import android.widget.FrameLayout
+import android.widget.TextView
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.appcompat.app.AppCompatActivity
+import androidx.camera.core.CameraSelector
+import androidx.camera.core.ImageAnalysis
+import androidx.camera.core.ImageProxy
+import androidx.camera.core.Preview
+import androidx.camera.lifecycle.ProcessCameraProvider
+import androidx.camera.view.PreviewView
+import androidx.core.content.ContextCompat
+import java.util.concurrent.Executors
+
+/**
+ * The camera, held open just long enough to read one pairing code.
+ *
+ * A phone that wants to drive a computer cannot type the code that computer
+ * shows: it is a base64 fragment inside a URL, and the whole point of showing it
+ * as a QR code is that nobody reads one aloud. So this is the way in — the same
+ * gesture the computer's own dialog asks for, from the other side.
+ *
+ * The decode is ZXing rather than ML Kit on purpose. ML Kit needs Google Play
+ * Services, and this app installs on phones whose HarmonyOS compatibility layer
+ * has none: a GMS-backed scanner would work on a developer's phone and fail on
+ * the device that needs it. ZXing core is pure Java, so the scanner behaves the
+ * same on both.
+ *
+ * It returns the first code it reads and finishes. A pairing code is
+ * single-use and short-lived, so "keep scanning after a hit" is not a feature —
+ * it is a way to spend a code that a later frame would have discarded.
+ */
+class ScanActivity : AppCompatActivity() {
+
+    private lateinit var preview: PreviewView
+    private lateinit var hint: TextView
+    private val executor = Executors.newSingleThreadExecutor()
+
+    /** Set once a code is found, so the frames in flight behind it do not each
+     *  try to finish the activity. */
+    @Volatile
+    private var settled = false
+
+    private val requestCamera = registerForActivityResult(ActivityResultContracts.RequestPermission()) { granted ->
+        if (granted) start() else refuse()
+    }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        val root = FrameLayout(this)
+        preview = PreviewView(this).apply {
+            layoutParams = FrameLayout.LayoutParams(
+                ViewGroup.LayoutParams.MATCH_PARENT,
+                ViewGroup.LayoutParams.MATCH_PARENT,
+            )
+            // The frames are analysed, not composed: filling the view and
+            // cropping is right here and would be wrong for a camera app.
+            scaleType = PreviewView.ScaleType.FILL_CENTER
+        }
+        hint = TextView(this).apply {
+            text = getString(R.string.scan_hint)
+            setTextColor(0xFFFFFFFF.toInt())
+            textSize = 14f
+            gravity = Gravity.CENTER
+            val pad = (16 * resources.displayMetrics.density).toInt()
+            setPadding(pad, pad, pad, pad)
+            // Readable over whatever the camera is pointing at, which is the
+            // one background a design system cannot choose.
+            setBackgroundColor(0x99000000.toInt())
+            layoutParams = FrameLayout.LayoutParams(
+                ViewGroup.LayoutParams.MATCH_PARENT,
+                ViewGroup.LayoutParams.WRAP_CONTENT,
+                Gravity.BOTTOM,
+            )
+        }
+        root.addView(preview)
+        root.addView(hint)
+        setContentView(root)
+
+        if (ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA) ==
+            PackageManager.PERMISSION_GRANTED
+        ) {
+            start()
+        } else {
+            requestCamera.launch(Manifest.permission.CAMERA)
+        }
+    }
+
+    private fun refuse() {
+        // No dialog of our own: the permission prompt already said no, and a
+        // second window repeating it is one more tap to dismiss. The caller
+        // gets the same answer as a cancelled scan.
+        setResult(RESULT_CANCELED)
+        finish()
+    }
+
+    private fun start() {
+        val providerFuture = ProcessCameraProvider.getInstance(this)
+        providerFuture.addListener({
+            val provider = runCatching { providerFuture.get() }.getOrNull() ?: return@addListener refuse()
+            val previewUseCase = Preview.Builder().build().also { it.setSurfaceProvider(preview.surfaceProvider) }
+            val analysis = ImageAnalysis.Builder()
+                // Only the newest frame matters: a stale one describes where the
+                // camera was, and a code that has already left the viewfinder
+                // must not win over one that is in it now.
+                .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST)
+                .build()
+                .also { it.setAnalyzer(executor, ::analyse) }
+            runCatching {
+                provider.unbindAll()
+                provider.bindToLifecycle(this, CameraSelector.DEFAULT_BACK_CAMERA, previewUseCase, analysis)
+            }.onFailure { refuse() }
+        }, ContextCompat.getMainExecutor(this))
+    }
+
+    private fun analyse(image: ImageProxy) {
+        try {
+            if (settled) return
+            val text = Qr.decode(image) ?: return
+            if (settled) return
+            settled = true
+            setResult(RESULT_OK, Intent().putExtra(EXTRA_TEXT, text))
+            // Finishing from the analysis thread is the whole reason `settled`
+            // exists; the activity teardown has to happen on the main one.
+            runOnUiThread { finish() }
+        } finally {
+            image.close()
+        }
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        executor.shutdown()
+    }
+
+    companion object {
+        const val EXTRA_TEXT = "text"
+    }
+}
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- The mark, drawn rather than shipped as a bitmap: one R in the app's own ink
+     on the palette's ground, which scales to every launcher's mask without a
+     density bucket per size. The hole in the R is the glyph's own counter, cut
+     with evenOdd rather than painted over. -->
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <path
+        android:fillColor="#F4F1EA"
+        android:fillType="evenOdd"
+        android:pathData="M39,30 L39,78 L47,78 L47,60 L54.5,60 L65,78 L74.5,78 L62.5,58 C68.6,55.8 72.6,50.6 72.6,43.6 C72.6,35.4 66.8,30 57.6,30 Z M47,37 L56.4,37 C61.2,37 64.4,39.4 64.4,43.8 C64.4,48.2 61.2,50.9 56.4,50.9 L47,50.9 Z" />
+    <path
+        android:fillColor="#A6680C"
+        android:pathData="M62,66 L74,66 L74,78 L62,78 Z" />
+</vector>
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- The status-bar glyph, not the launcher icon: Android renders a notification
+     icon as a mask, so anything that is not a solid silhouette on transparency
+     comes out as a grey blob. -->
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24"
+    android:tint="#FFFFFF">
+    <path
+        android:fillColor="#FFFFFF"
+        android:pathData="M3,4h18v2H3zM3,9h18v2H3zM3,14h12v2H3zM3,19h12v2H3zM17.5,13.2l1.6,2.6 1.6,-2.6h2.3l-2.8,4.3V21h-2.2v-3.5L15.2,13.2z" />
+</vector>
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  The screen between the tap and the page.
+
+  It exists for a reason that is not cosmetic: the kernel has to be unpacked and
+  started before there is a page to show, and on a cold start that is about a
+  second. A blank window for a second reads as a broken app; a line of text that
+  says what is happening does not.
+
+  The progress bar is indeterminate and driven by nothing: the WebView's own
+  progress is mirrored onto it while the page loads, and before that it simply
+  turns, which is the honest description of "we do not know how long".
+-->
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    android:background="@color/page"
+    android:orientation="vertical"
+    android:gravity="center"
+    android:paddingStart="32dp"
+    android:paddingEnd="32dp">
+
+    <TextView
+        android:id="@+id/splash_wordmark"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:text="@string/app_name"
+        android:textColor="#8A857B"
+        android:textSize="22sp"
+        android:letterSpacing="0.08"
+        android:fontFamily="sans-serif-medium" />
+
+    <ProgressBar
+        android:id="@+id/splash_bar"
+        style="?android:attr/progressBarStyleHorizontal"
+        android:layout_width="132dp"
+        android:layout_height="wrap_content"
+        android:layout_marginTop="26dp"
+        android:indeterminate="true" />
+
+    <TextView
+        android:id="@+id/splash_text"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:layout_marginTop="18dp"
+        android:gravity="center"
+        android:text="@string/splash_connecting"
+        android:textColor="#8A857B"
+        android:textSize="13sp"
+        android:lineSpacingMultiplier="1.5" />
+
+    <Button
+        android:id="@+id/splash_retry"
+        style="?android:attr/borderlessButtonStyle"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:layout_marginTop="14dp"
+        android:minHeight="44dp"
+        android:text="@string/splash_retry"
+        android:textColor="#A6680C"
+        android:visibility="gone" />
+</LinearLayout>
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- The adaptive launcher icon.
+
+     minSdk is 26, which is the release that introduced adaptive icons, so this
+     is the only launcher asset the app needs: there is no device running it
+     that would ask for a bitmap fallback. -->
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@color/ic_launcher_background" />
+    <!-- The safe zone is the middle 66dp of 108dp; the glyph is drawn inside it
+         so no launcher's mask can clip it. -->
+    <foreground android:drawable="@drawable/ic_launcher_foreground" />
+    <monochrome android:drawable="@drawable/ic_launcher_foreground" />
+</adaptive-icon>
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">Reasonix</string>
+
+    <string name="channel_kernel">Kernel running</string>
+    <string name="channel_kernel_desc">Shown while the Reasonix kernel runs in the background. Can be muted on its own in system settings.</string>
+
+    <string name="notify_running_title">Reasonix is running</string>
+    <string name="notify_running_body">A task is still going. Switch back to see it.</string>
+    <string name="notify_failed_title">Reasonix could not start</string>
+
+    <string name="err_kernel_unreachable">Could not reach the kernel. Reopen the app from your home screen.</string>
+
+    <string name="download_default_name">reasonix-download</string>
+    <string name="download_saved">Saved: %1$s</string>
+    <string name="download_failed">Save failed: %1$s</string>
+    <string name="download_failed_status">Save failed: the server answered %1$d</string>
+
+    <string name="splash_connecting">Starting the kernel…</string>
+    <string name="splash_retry">Retry</string>
+
+    <string name="scan_title">Scan the code on the computer</string>
+    <string name="scan_hint">Point at the QR code in the computer\'s device panel to connect to it.</string>
+    <string name="scan_button">Scan to connect</string>
+    <string name="scan_denied">No camera permission, so scanning is unavailable. Allow it in system settings.</string>
+</resources>
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- The dark palette's page colour. `DayNight` on the theme picks this up when
+     the system is dark, which is what keeps the frame before the WebView from
+     flashing light at someone using a dark phone at night. -->
+<resources>
+    <color name="page">#0E1014</color>
+</resources>
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- The light palette's page colour, and only what the window needs before the
+     WebView paints. The interface's own colours are `tokens.css`'s and are the
+     page's business; these two exist so the first frame is the app's ground
+     rather than the platform default white. -->
+<resources>
+    <color name="page">#F4F1EA</color>
+    <color name="boot">#07080C</color>
+</resources>
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- The launcher ground: the interface's dark page colour. It is the same in
+     both themes because a launcher icon is not themed by the app. -->
+<resources>
+    <color name="ic_launcher_background">#14161C</color>
+</resources>
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Every string the shell itself shows. The interface's own text belongs to
+     the page and lives in its i18n bundle; these are only the few lines that
+     exist before it, or when it cannot load. -->
+<resources>
+    <string name="app_name">Reasonix</string>
+
+    <string name="channel_kernel">内核运行中</string>
+    <string name="channel_kernel_desc">Reasonix 内核在后台运行时显示，可在系统设置中单独关闭。</string>
+
+    <string name="notify_running_title">Reasonix 正在运行</string>
+    <string name="notify_running_body">任务继续进行，切回应用即可查看。</string>
+    <string name="notify_failed_title">Reasonix 无法启动</string>
+
+    <string name="err_kernel_unreachable">连接内核失败。请返回桌面重新打开应用。</string>
+
+    <string name="download_default_name">reasonix-download</string>
+    <string name="download_saved">已保存：%1$s</string>
+    <string name="download_failed">保存失败：%1$s</string>
+    <string name="download_failed_status">保存失败：服务器返回 %1$d</string>
+
+    <string name="splash_connecting">正在启动内核…</string>
+    <string name="splash_retry">重试</string>
+
+    <string name="wsperm_title">需要「所有文件访问」权限</string>
+    <string name="wsperm_body">要打开手机上的文件夹作为工作区，需要先允许本应用访问所有文件。点「去设置」，在列表里打开 Reasonix 的开关，然后返回这里。</string>
+    <string name="wsperm_go">去设置</string>
+    <string name="wsperm_later">以后再说</string>
+
+    <string name="scan_title">扫描电脑上的二维码</string>
+    <string name="scan_hint">对准电脑上「设备访问」里的二维码，识别后即可连接这台电脑。</string>
+    <string name="scan_button">扫码连接电脑</string>
+    <string name="scan_denied">没有相机权限，无法扫码。请在系统设置里允许。</string>
+    <string name="share_title">分享文件</string>
+</resources>
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- The shell's own furniture: a window background matching the page's light
+     palette before the WebView paints, and a transparent system bar so the
+     page's own safe-area padding is what the notch meets. The page themes
+     itself; this exists only so the first frame is not a white flash. -->
+<resources xmlns:tools="http://schemas.android.com/tools">
+
+    <style name="Theme.Reasonix" parent="Theme.AppCompat.DayNight.NoActionBar">
+        <item name="android:windowBackground">@color/page</item>
+        <item name="android:statusBarColor">@android:color/transparent</item>
+        <item name="android:navigationBarColor">@android:color/transparent</item>
+        <!-- The page draws its own edge-to-edge layout and pads itself with the
+             safe-area insets from mobile.css. Laying the window out edge to edge
+             while leaving the bars transparent is what makes those insets real
+             numbers instead of zero. -->
+        <item name="android:windowLayoutInDisplayCutoutMode" tools:targetApi="p">shortEdges</item>
+        <item name="android:enforceStatusBarContrast" tools:targetApi="q">false</item>
+        <item name="android:enforceNavigationBarContrast" tools:targetApi="q">false</item>
+    </style>
+
+    <!-- The camera. A black ground because the preview has not drawn yet and a
+         light window behind a dark viewfinder is a flash in the dark; the bars
+         stay transparent so the preview reaches the edges, which is what makes
+         a code near the top of the screen scannable. -->
+    <style name="Theme.Reasonix.Scan" parent="Theme.Reasonix">
+        <item name="android:windowBackground">@android:color/black</item>
+    </style>
+</resources>
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Backups are off, and this file says why rather than leaving it implicit.
+
+  A Reasonix home holds provider keys, an account token and every session
+  transcript. Android's auto-backup would copy all of it to the person's cloud
+  drive and, on a device-to-device transfer, to a new phone — which is a
+  credential leaving the device by a route nobody chose. `allowBackup="false"`
+  in the manifest turns that off; these two stanzas are the belt to its braces,
+  excluding everything explicitly so that a later change to `allowBackup` cannot
+  quietly start copying credentials.
+
+  What a person wants to move between phones, the kernel already moves: its own
+  export writes a file the person hands to the system's picker.
+-->
+<data-extraction-rules>
+    <cloud-backup>
+        <exclude domain="root" />
+        <exclude domain="file" />
+        <exclude domain="database" />
+        <exclude domain="sharedpref" />
+        <exclude domain="external" />
+    </cloud-backup>
+    <device-transfer>
+        <exclude domain="root" />
+        <exclude domain="file" />
+        <exclude domain="database" />
+        <exclude domain="sharedpref" />
+        <exclude domain="external" />
+    </device-transfer>
+</data-extraction-rules>
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Cleartext HTTP is permitted, and the platform has no way to permit less.
+
+  Two kinds of page load over plain HTTP: the kernel's own page on
+  `127.0.0.1:<port>`, and the same page served by a paired computer on whatever
+  address its router handed out. The port is chosen when the kernel starts and
+  the LAN address when a code is scanned, so neither can be written here — and a
+  `domain-config` matches literals and domains, never a subnet.
+
+  So the boundary is not this file. `MainActivity` decides which cleartext origin
+  may become the window: `shouldOverrideUrlLoading` sends every http(s) origin
+  that is not the kernel's or the one just paired out to the browser, and the
+  native bridge answers only those two. A plaintext page on the LAN therefore
+  cannot become the document holding the bridge, which is what the reviewer's
+  "deliberate path for LAN pairing" asks for.
+
+  HTTPS is untouched: nothing here downgrades a request, and `trust-anchors`
+  keeps the system roots for every TLS connection that is made.
+-->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="true">
+        <trust-anchors>
+            <certificates src="system" />
+        </trust-anchors>
+    </base-config>
+</network-security-config>
@@ -0,0 +1,15 @@
+// The build itself lives in app/build.gradle; this file declares the plugin
+// versions once so the app module can be read on its own.
+//
+// AGP 8.11.1 is the pairing for the Gradle 8.14 toolchain this machine has:
+// AGP 8.7 and older refuse a Gradle that new, and AGP 8.13+ wants a Gradle this
+// one does not have. Both numbers are pinned rather than ranged, because a
+// build that silently moved either one would be a different build.
+plugins {
+    id "com.android.application" version "8.11.1" apply false
+    id "org.jetbrains.kotlin.android" version "2.1.20" apply false
+}
+
+tasks.register("clean", Delete) {
+    delete rootProject.layout.buildDirectory
+}
@@ -0,0 +1,15 @@
+# AndroidX is the only copy of the support libraries this project uses; the
+# non-transitive R class keeps the app's own resources from aliasing library
+# ones, which is what makes `R.string.*` unambiguous here.
+android.useAndroidX=true
+android.nonTransitiveRClass=true
+
+# The daemon is what keeps a second `gradle assembleDebug` from re-reading the
+# whole SDK, and the heap is sized for the R8 pass over the WebView and the
+# packaged page rather than for this handful of Kotlin files.
+org.gradle.jvmargs=-Xmx3g -Dfile.encoding=UTF-8
+org.gradle.daemon=true
+org.gradle.parallel=true
+org.gradle.caching=true
+
+kotlin.code.style=official
@@ -0,0 +1,12 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-bin.zip
+# Pinning the distribution's checksum is what makes the download verifiable: a
+# mirror that served a different zip would fail here instead of being unpacked
+# and run. The value is Gradle's own, from
+# https://services.gradle.org/distributions/gradle-8.14.3-bin.zip.sha256
+distributionSha256Sum=bd71102213493060956ec229d946beee57158dbd89d0e62b91bca0fa2c5f3531
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
@@ -0,0 +1,251 @@
+#!/bin/sh
+
+#
+# Copyright © 2015-2021 the original authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+##############################################################################
+#
+#   Gradle start up script for POSIX generated by Gradle.
+#
+#   Important for running:
+#
+#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
+#       noncompliant, but you have some other compliant shell such as ksh or
+#       bash, then to run this script, type that shell name before the whole
+#       command line, like:
+#
+#           ksh Gradle
+#
+#       Busybox and similar reduced shells will NOT work, because this script
+#       requires all of these POSIX shell features:
+#         * functions;
+#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
+#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;
+#         * compound commands having a testable exit status, especially «case»;
+#         * various built-in commands including «command», «set», and «ulimit».
+#
+#   Important for patching:
+#
+#   (2) This script targets any POSIX shell, so it avoids extensions provided
+#       by Bash, Ksh, etc; in particular arrays are avoided.
+#
+#       The "traditional" practice of packing multiple parameters into a
+#       space-separated string is a well documented source of bugs and security
+#       problems, so this is (mostly) avoided, by progressively accumulating
+#       options in "$@", and eventually passing that to Java.
+#
+#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
+#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
+#       see the in-line comments for details.
+#
+#       There are tweaks for specific operating systems such as AIX, CygWin,
+#       Darwin, MinGW, and NonStop.
+#
+#   (3) This script is generated from the Groovy template
+#       https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       within the Gradle project.
+#
+#       You can find Gradle at https://github.com/gradle/gradle/.
+#
+##############################################################################
+
+# Attempt to set APP_HOME
+
+# Resolve links: $0 may be a link
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path
+    [ -h "$app_path" ]
+do
+    ls=$( ls -ld "$app_path" )
+    link=${ls#*' -> '}
+    case $link in             #(
+      /*)   app_path=$link ;; #(
+      *)    app_path=$APP_HOME$link ;;
+    esac
+done
+
+# This is normally unused
+# shellcheck disable=SC2034
+APP_BASE_NAME=${0##*/}
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s\n' "$PWD" ) || exit
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD=maximum
+
+warn () {
+    echo "$*"
+} >&2
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+} >&2
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "$( uname )" in                #(
+  CYGWIN* )         cygwin=true  ;; #(
+  Darwin* )         darwin=true  ;; #(
+  MSYS* | MINGW* )  msys=true    ;; #(
+  NONSTOP* )        nonstop=true ;;
+esac
+
+CLASSPATH="\\\"\\\""
+
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD=$JAVA_HOME/jre/sh/java
+    else
+        JAVACMD=$JAVA_HOME/bin/java
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD=java
+    if ! command -v java >/dev/null 2>&1
+    then
+        die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+fi
+
+# Increase the maximum file descriptors if we can.
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+    case $MAX_FD in #(
+      max*)
+        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        MAX_FD=$( ulimit -H -n ) ||
+            warn "Could not query maximum file descriptor limit"
+    esac
+    case $MAX_FD in  #(
+      '' | soft) :;; #(
+      *)
+        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        ulimit -n "$MAX_FD" ||
+            warn "Could not set maximum file descriptor limit to $MAX_FD"
+    esac
+fi
+
+# Collect all arguments for the java command, stacking in reverse order:
+#   * args from the command line
+#   * the main class name
+#   * -classpath
+#   * -D...appname settings
+#   * --module-path (only if needed)
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
+
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+    CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" )
+
+    JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    for arg do
+        if
+            case $arg in                                #(
+              -*)   false ;;                            # don't mess with options #(
+              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath
+                    [ -e "$t" ] ;;                      #(
+              *)    false ;;
+            esac
+        then
+            arg=$( cygpath --path --ignore --mixed "$arg" )
+        fi
+        # Roll the args list around exactly as many times as the number of
+        # args, so each arg winds up back in the position where it started, but
+        # possibly modified.
+        #
+        # NB: a `for` loop captures its iteration list before it begins, so
+        # changing the positional parameters here affects neither the number of
+        # iterations, nor the values presented in `arg`.
+        shift                   # remove old arg
+        set -- "$@" "$arg"      # push replacement arg
+    done
+fi
+
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+#     and any embedded shellness will be escaped.
+#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+#     treated as '${Hostname}' itself on the command line.
+
+set -- \
+        "-Dorg.gradle.appname=$APP_BASE_NAME" \
+        -classpath "$CLASSPATH" \
+        -jar "$APP_HOME/gradle/wrapper/gradle-wrapper.jar" \
+        "$@"
+
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+    die "xargs is not available"
+fi
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+#   set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+        xargs -n1 |
+        sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
+        tr '\n' ' '
+    )" '"$@"'
+
+exec "$JAVACMD" "$@"
@@ -0,0 +1,94 @@
+@rem
+@rem Copyright 2015 the original author or authors.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      https://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+@rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
+
+@if "%DEBUG%"=="" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables with windows NT shell
+if "%OS%"=="Windows_NT" setlocal
+
+set DIRNAME=%~dp0
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if %ERRORLEVEL% equ 0 goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:execute
+@rem Setup the command line
+
+set CLASSPATH=
+
+
+@rem Execute Gradle
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" -jar "%APP_HOME%\gradle\wrapper\gradle-wrapper.jar" %*
+
+:end
+@rem End local scope for the variables with windows NT shell
+if %ERRORLEVEL% equ 0 goto mainEnd
+
+:fail
+rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
+rem the _cmd.exe /c_ return code!
+set EXIT_CODE=%ERRORLEVEL%
+if %EXIT_CODE% equ 0 set EXIT_CODE=1
+if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
+exit /b %EXIT_CODE%
+
+:mainEnd
+if "%OS%"=="Windows_NT" endlocal
+
+:omega
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+#
+# Build the Reasonix kernel for Android and place it where the APK packager
+# expects a native library.
+#
+# Why a shell script and not a Gradle task: the kernel is a Go module that lives
+# outside this Gradle build, with its own toolchain version pinned in go.mod. A
+# Gradle task that invoked `go build` would make the Android build depend on a Go
+# toolchain being configured for it, and would rebuild a 21MB binary on every
+# `assembleDebug` even when nothing in the kernel changed. This runs when you
+# mean it to, and the APK task only checks that the result is there.
+#
+# Output: app/src/main/jniLibs/arm64-v8a/libreasonix.so
+#   The name is not cosmetic. Android extracts files under `jniLibs/` to
+#   `nativeLibraryDir` and permits execution *there*; a binary shipped in
+#   `assets/` would have to be copied to app storage and chmod'd, which fails on
+#   a device whose data partition is mounted noexec. `lib*.so` is the shape the
+#   packager recognises as a native library, so the kernel wears it.
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+android="$here/.."
+upstream="$android/.."
+out="$android/app/src/main/jniLibs/arm64-v8a/libreasonix.so"
+
+if [ ! -d "$upstream" ]; then
+  echo "kernel source not found: $upstream" >&2
+  echo "run this from a checkout: the parent of android/ must be the kernel source." >&2
+  exit 1
+fi
+
+# GOOS=android needs nothing else: the kernel is CGO-free, which is what makes a
+# single static binary possible in the first place. `-s -w` drops the symbol and
+# DWARF tables — about a third of the file — and nothing on a phone reads them.
+export GOOS=android
+export GOARCH=arm64
+export CGO_ENABLED=0
+
+# The app version, read from the module's own build.gradle so the two cannot
+# drift. The official build stamps these through `-X` (see upstream's Makefile);
+# without them the kernel reports `version=dev revision=unknown`, which a phone
+# then shows next to the documentation it was built with and makes a bug report
+# from that build impossible to place. There is no `.git` here, so the revision
+# names the package the corpus shipped in rather than a commit hash — the honest
+# answer when there is no commit to name.
+app_gradle="$android/app/build.gradle"
+version_field() {
+  sed -n "s/^def $1 *= *\([0-9]*\).*/\1/p" "$app_gradle" | head -n1
+}
+app_version="$(version_field versionMajor).$(version_field versionMinor).$(version_field versionPatch)"
+build_time_utc="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+ldflags="-s -w"
+ldflags="$ldflags -X main.version=v$app_version"
+ldflags="$ldflags -X main.buildTimeUTC=$build_time_utc"
+ldflags="$ldflags -X reasonix/internal/tools/productdocs.linkedVersion=v$app_version"
+ldflags="$ldflags -X reasonix/internal/tools/productdocs.linkedRevision=apk-v$app_version"
+
+echo "building the kernel (android/arm64, v$app_version) ..."
+mkdir -p "$(dirname "$out")"
+cd "$upstream"
+go build -trimpath -ldflags="$ldflags" -o "$out" ./cmd/reasonix
+
+size=$(wc -c < "$out")
+echo "kernel ready: $out ($((size / 1024 / 1024)) MiB)"
@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+#
+# One command from a clean checkout to an installable APK.
+#
+# The order matters and is the whole content of this script: the kernel and the
+# page are inputs to packaging, not build steps inside it, so they are produced
+# first and the Gradle task only assembles what is already there. Running
+# `gradle assembleRelease` directly on a fresh checkout fails on purpose (see
+# `requireBuildInputs` in app/build.gradle) rather than producing an APK with no
+# kernel in it.
+#
+# Usage: ./scripts/build.sh [debug|release]     (default: release)
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+android="$here/.."
+variant="${1:-release}"
+
+case "$variant" in
+  debug|release) ;;
+  *) echo "usage: $0 [debug|release]" >&2; exit 2 ;;
+esac
+
+"$here/build-kernel.sh"
+"$here/sync-page.sh"
+
+cd "$android"
+
+# The wrapper is committed, jar and all, and it is the only thing that runs the
+# build. Generating one here would tie the dependency versions to whichever
+# `gradle` happened to be on PATH, which is the opposite of a pinned build.
+if [ ! -f gradlew ]; then
+  echo "gradlew is missing: this repository commits the Gradle wrapper, so the checkout is incomplete" >&2
+  echo "(a release build does not use `gradle` from PATH: that would tie dependency versions to the machine)" >&2
+  exit 1
+fi
+
+task="assemble$([ "$variant" = release ] && echo Release || echo Debug)"
+echo "packaging the APK ($variant) ..."
+./gradlew "$task" --no-daemon
+
+apk_dir="$android/app/build/outputs/apk/$variant"
+echo
+echo "done. Installable artifacts:"
+find "$apk_dir" -name '*.apk' -maxdepth 1 -print -exec ls -lh {} \;
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+#
+# Install the built APK on a connected phone and show its log.
+#
+# `adb` comes from the Android SDK rather than this project, because the SDK is
+# already how the app is built. Point ANDROID_HOME at it, or have `adb` on PATH.
+#
+# Usage: ./scripts/run.sh [debug|release]
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+android="$here/.."
+variant="${1:-release}"
+
+adb="${ADB:-${ANDROID_HOME:-$HOME/AndroidSDK}/platform-tools/adb}"
+if ! command -v "$adb" >/dev/null 2>&1; then
+  adb="adb"
+fi
+
+apk_dir="$android/app/build/outputs/apk/$variant"
+apk=$(find "$apk_dir" -name '*.apk' -maxdepth 1 2>/dev/null | head -n1)
+if [ -z "$apk" ]; then
+  echo "no $variant APK found; run ./scripts/build.sh $variant first" >&2
+  exit 1
+fi
+
+echo "installing $apk ..."
+"$adb" install -r "$apk"
+
+# The device count is checked before the app is started so an emulator-less
+# machine gets "no devices" rather than a launch failure that reads like a bug.
+if [ "$("$adb" devices | grep -c 'device$')" -eq 0 ]; then
+  echo "no device attached; skipping the launch." >&2
+  exit 0
+fi
+
+package="io.reasonix.mobile.app"
+[ "$variant" = debug ] && package="io.reasonix.mobile.app.debug"
+"$adb" shell monkey -p "$package" -c android.intent.category.LAUNCHER 1 >/dev/null
+
+echo
+echo "following the log (Ctrl-C to stop) ..."
+"$adb" logcat -v color "ReasonixKernel:V" "AndroidRuntime:E" "*:S"
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+#
+# Build the interface and copy it where the APK will carry it.
+#
+# The page that ships is the same build the desktop Studio serves — that is the
+# whole reason the mobile layout lives in `desktop/frontend-next` rather than in
+# an Android project's own web root. Nothing is edited on the way through: the
+# only thing this script does that `pnpm build` does not is copy `dist/` into the
+# app's assets.
+#
+# Output: app/src/main/assets/page/
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+android="$here/.."
+frontend="$android/../desktop/frontend-next"
+dest="$android/app/src/main/assets/page"
+
+if [ ! -d "$frontend" ]; then
+  echo "frontend project not found: $frontend" >&2
+  exit 1
+fi
+
+cd "$frontend"
+
+# pnpm is the package manager the lockfile is written for; npm would resolve a
+# different tree than the one that was tested.
+if ! command -v pnpm >/dev/null 2>&1; then
+  echo "pnpm 10 is required: npm install -g pnpm@10" >&2
+  exit 1
+fi
+
+if [ ! -d node_modules ]; then
+  echo "installing frontend dependencies ..."
+  pnpm install --frozen-lockfile
+fi
+
+echo "building the frontend ..."
+pnpm build
+
+rm -rf "$dest"
+mkdir -p "$dest"
+cp -R dist/. "$dest/"
+
+if [ ! -f "$dest/index.html" ]; then
+  echo "the build produced no index.html; the frontend build probably failed." >&2
+  exit 1
+fi
+
+count=$(find "$dest" -type f | wc -l)
+size=$(du -sk "$dest" | cut -f1)
+echo "page ready: $dest ($count files, $((size / 1024)) MiB)"
+
+# MIT requires the copyright notice and the licence text to travel with a binary
+# distribution, so the APK carries it. Generated from the repository's own
+# `LICENSE` rather than committed a second time: a checked-in copy is one more
+# thing that drifts when the root file is updated.
+root_license="$android/../LICENSE"
+if [ ! -f "$root_license" ]; then
+  echo "LICENSE not found: $root_license" >&2
+  exit 1
+fi
+cp "$root_license" "$android/app/src/main/assets/LICENSE"
+echo "licence: app/src/main/assets/LICENSE (copied from the repository's LICENSE)"
@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+#
+# Reproduce what `Kernel.kt` does, on this machine, against the page that is
+# actually packaged into the APK.
+#
+# This is the closest thing to an end-to-end test that runs without a phone: the
+# launch flags, the token file, the port file and the `--page` directory are the
+# same ones the Kotlin shell passes, and the page is read out of
+# `app/src/main/assets/page` rather than the frontend's own `dist/`. If this
+# serves a working interface, the only untested part is Android itself.
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+android="$here/.."
+page="$android/app/src/main/assets/page"
+kernel="${KERNEL_BIN:-$android/../reasonix-verify.exe}"
+
+work="${VERIFY_DIR:-/tmp/reasonix-verify}"
+rm -rf "$work"
+mkdir -p "$work/home/remote"
+
+if [ ! -f "$kernel" ]; then
+  echo "no runnable kernel; build one first:" >&2
+  echo "  (cd .. && go build -o reasonix-verify.exe ./cmd/reasonix)" >&2
+  exit 1
+fi
+
+if [ ! -f "$page/index.html" ]; then
+  echo "no packaged page: $page/index.html" >&2
+  exit 1
+fi
+
+# 32 random bytes as hex — the same shape `Kernel.mintToken` writes.
+token=$(od -An -tx1 -N32 /dev/urandom | tr -d ' \n')
+printf '%s\n' "$token" > "$work/home/remote/launch.token"
+
+export REASONIX_HOME="$work/home"
+export HOME="$work/home"
+export TMPDIR="$work"
+
+echo "kernel: $kernel"
+echo "page: $page"
+echo "token: ${token:0:8}... (${#token} chars)"
+
+"$kernel" serve \
+  --addr 127.0.0.1:0 \
+  --auth token \
+  --token-file "$work/home/remote/launch.token" \
+  --port-file "$work/home/remote/serve.port" \
+  --pid-file "$work/home/remote/serve.pid" \
+  --no-open \
+  -page "$page" \
+  > "$work/kernel.log" 2>&1 &
+echo $! > "$work/kernel.pid"
+
+# Wait for the port file the kernel writes after binding, which is exactly the
+# wait `Kernel.awaitPort` performs.
+for _ in $(seq 1 150); do
+  if [ -s "$work/home/remote/serve.port" ]; then break; fi
+  if ! kill -0 "$(cat "$work/kernel.pid")" 2>/dev/null; then
+    echo "the kernel exited; log:" >&2
+    cat "$work/kernel.log" >&2
+    exit 1
+  fi
+  sleep 0.2
+done
+
+if [ ! -s "$work/home/remote/serve.port" ]; then
+  echo "the kernel reported no listening address; log:" >&2
+  cat "$work/kernel.log" >&2
+  exit 1
+fi
+
+port=$(cat "$work/home/remote/serve.port")
+echo "listening on: $port"
+
+# The two things the WebView will do: fetch the page, and exist on the origin.
+probe=$(curl -s -o /dev/null -w '%{http_code}' "http://$port/")
+echo "GET /  -> $probe"
+if [ "$probe" != "200" ]; then
+  echo "the page did not answer; log:" >&2
+  cat "$work/kernel.log" >&2
+  exit 1
+fi
+
+cat > "$work/entry.txt" <<EOF
+origin=http://$port
+entry=http://$port/#token=$token
+token=$token
+EOF
+
+echo "entry written: $work/entry.txt"
+echo "kernel log (first 10 lines):"
+head -10 "$work/kernel.log"
@@ -0,0 +1,31 @@
+// Reasonix Mobile — the Android shell around the Reasonix kernel.
+//
+// The shell is deliberately thin: it unpacks the kernel and the built page that
+// ship inside the APK, starts `reasonix serve` on a loopback port, and points a
+// WebView at it. Everything the person sees and does is the same page the
+// desktop Studio and `reasonix web` serve, because it is literally the same
+// build of `desktop/frontend-next` — which is what keeps one interface honest
+// across the three surfaces, and why the page is packaged rather than fetched.
+
+pluginManagement {
+    repositories {
+        // The official repositories only. A mirror listed here would be an
+        // unverified trust anchor for anything that ends up in a signed build:
+        // the artifact it serves is whichever copy landed there. A machine that
+        // needs a mirror belongs on a user-level init script, where the choice
+        // stays with the person building rather than travelling with the source.
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+
+dependencyResolutionManagement {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+rootProject.name = "ReasonixMobile"
+include(":app")
@@ -1,6 +1,6 @@
 # Reasonix Benchmarks

-Five harnesses live under `benchmarks/`; `cmd/e2ebench` also exposes a
+Six harnesses live under `benchmarks/`; `cmd/e2ebench` also exposes a
 SWE-bench Verified mode:

 - `e2e/` — the committed end-to-end task suite, driven by
@@ -19,6 +19,10 @@ SWE-bench Verified mode:
 - `fanout-width/` — a shape-instructed fleet whose members share nothing, for
  pricing what running them at the same time is worth. See
  [Pricing the run graph](#pricing-the-run-graph) below.
+- `realrepo/` — long tasks over a pinned snapshot of this repository, for
+  measuring changes that cut model round trips (13–31 requests per task on
+  `deepseek-flash`). See
+  [its README](realrepo/README.md).

 ## Directory layout

@@ -0,0 +1,131 @@
+# realrepo
+
+Long tasks over a pinned snapshot of this repository, for measuring changes
+that aim to cut model round trips. The `benchmarks/e2e` tasks finish in about
+5–15 requests and ten seconds; a real task in this tree took a flash-class
+model 38 requests, most of them after a single read. A suite of short fixtures
+cannot show that gap moving, so these tasks are shaped like the real one:
+explore several packages, edit several files, verify, and recover from the
+verifier.
+
+```sh
+go build -o bin/reasonix ./cmd/reasonix
+go run ./cmd/e2ebench -suite benchmarks/realrepo -bin "$PWD/bin/reasonix" -model deepseek-flash \
+  -budget 0 -trials 2 -trajectories traj -json realrepo.json
+go run ./cmd/e2ebench -suite benchmarks/realrepo -bin "$PWD/bin/reasonix" -task rt-stale-skills
+```
+
+The agent reads its provider config from `REASONIX_HOME` (default
+`~/.reasonix`); point it at a disposable one to keep benchmark sessions out of
+your own.
+
+The default `-budget` (800k tokens) can stop the suite partway through, hence
+`-budget 0`. Under `-trials`, each trial keeps its own
+`<task>.trial-N.trajectory.jsonl`.
+
+## The snapshot
+
+Every `workdir/` is the same Go module (`module reasonix`, stdlib only, no
+network needed to build or test):
+
+- **Pinned code.** `git archive` of commit `42636ddcb425` for
+  `internal/contract/{pricing,ablation,agentgraph}` and
+  `internal/base/{retrieval,rulelist,tokencount,neterr,nilutil}` — about 5k
+  lines of real kernel code with its real tests and doc comments.
+- **Fixture-authored files** in `base/`: `go.mod`, a trimmed `REASONIX.md` (the
+  project's own conventions, so the agent loads standing instructions the way
+  it does here), a `Makefile` with `check`, a module `README.md`, the
+  `cmd/benchctl` command that consumes `pricing` and `ablation` from outside
+  their package, and one project skill.
+- **One pinned test anchored to the snapshot day.**
+  `TestCatalogPricesHaveBeenCheckedRecently` compares each row's `CheckedOn`
+  with the wall clock, which would fail every workdir 90 days after the oldest
+  pinned date (2026-11-20). `base/` replaces that file with one that reads
+  staleness at 2026-10-19 instead; nothing else in the pin is edited.
+- **Per-task overlay** in `overlay/<task-id>/`, applied last. Only
+  `rt-stale-skills` has one.
+
+`snapshot.sh` rebuilds every workdir from those three sources and
+`snapshot.sh --check` fails if a committed workdir has drifted from them. Edit
+`base/` or `overlay/`, never a workdir, then rerun the script. Moving the pin is
+a new suite version: results from two pins do not compare.
+
+## Tasks
+
+| Task | Kind | What it exercises |
+| --- | --- | --- |
+| `rt-cache-write-rate` | multi-file Go change, test, README | Adds a `CacheWrite` rate to `RateCard` and threads it through cost, fingerprint, card identity and the catalog, then prices Anthropic's `claude-sonnet-4-5` with it: a new `officialRates` row, documentation and checked-on constants, an endpoint host, and `benchctl rate`/`cost` output. The fingerprint has to stay byte-identical for every existing card, so the change to `PricingFingerprint` cannot be the obvious one. |
+| `rt-stale-skills` | documentation only, no recognised verifier | Three project skills name paths, functions, `make` targets and `benchctl` subcommands and flags that do not exist, and one contradicts the append-only rule in `REASONIX.md`. Fixing them takes reading `rates.go`, `ablation.go`, both `benchctl` files and the `Makefile`, then editing only Markdown — the shape behind #13293, where `stale_verification` stays owed after a skill edit because no check covers it. |
+| `rt-rate-lookup-signatures` | API migration with a likely compile-error loop | Changes `CurrentRate` to `(RateCard, bool)`, `LookupCatalog` to a `CatalogKey` struct, and `IsOfficialCard`, `MatchesCatalog` and `LiveTariff` to a `ModelRef`: about 20 call sites across 11 files. Most are in `_test.go` files and dereference the old pointer, so `go build ./...` can pass while `go vet` and `go test` fail. |
+| `rt-plan-ablation-module` | plan-mode with `complete_step` | Five numbered steps adding a `memory` ablation module, summaries, `ModuleHelp` and `benchctl arm -list`. The prompt opens with the host's own plan-first marker (`control.PlannerRouteMarker`), which routes the turn through the planner, and asks for each step to be signed off before the next. An existing test pins the `all` arm name and has to be updated, which adds a red-test step. |
+
+Every grader stages hidden tests and checks after the run: `gofmt -l`, `go vet
+./...` and `go test ./...` for the Go tasks; for `rt-stale-skills`, every
+backticked path, identifier, `make` target and `benchctl` command line in each
+skill must resolve against the tree, and a SHA-256 manifest proves no Go source, `go.mod`,
+`Makefile` or `REASONIX.md` changed. Each task fails its pristine seed and
+passes its `solution/`, both checked by `cmd/e2ebench`'s corpus tests.
+
+## Reading the numbers
+
+```text
+Metric:        requests per task
+Anchor:        the trajectory digest's requests_by_source, summed over sources
+Population:    every graded trial of a task that ran to its own stop
+Excludes:      tasks the token budget skipped, and runs that hit timeout_sec
+```
+
+Requests is the headline because round trips are what these tasks exist to
+move. Read it beside the solve rate and the report's round outcomes: a change
+that drops requests by giving up on verification has not cut a round trip, it
+has cut a check. `rt-stale-skills` is read for whether the run finishes at all
+and how many rounds go to re-verifying after its last write.
+
+## Baseline
+
+`deepseek-flash`, 2 trials per task, at studio `0b8de9e63`. Requests are the
+trajectory's executor requests; all 8 runs ran to their own stop.
+
+| Task | Solved | Requests | `edit_file` calls | Edit rounds |
+| --- | --- | --- | --- | --- |
+| `rt-cache-write-rate` | 2/2 | 31, 28 | 21, 20 | 8, 8 |
+| `rt-plan-ablation-module` | 2/2 | 24, 30 | 10, 13 | 9, 7 |
+| `rt-rate-lookup-signatures` | 2/2 | 13, 15 | 10, 17 | 2, 6 |
+| `rt-stale-skills` | 2/2* | 20, 26 | 3, 2 | 3, 3 |
+
+\* One run first graded as failed, on a glob (`*_rates_test.go`) and a
+placeholder (`benchctl <subcommand>`) that were both correct. The grader now
+resolves globs against the tree and skips placeholders, and that run counts
+as solved. The same task's first version failed a run for naming
+`CatalogEntry.EffectiveFrom` in order to warn against it; that check went too.
+
+Reads and edits already batch: 20 edit calls fit into 8 rounds, and several
+`edit_file` calls to one file often share a round. Rounds that edit a file the
+previous round also edited are rare (0–2 per run), so steering same-file edits
+to `multi_edit` has little to save. On this suite's first version, a
+`ToolBatchPolicy` sentence asking for it drew no `multi_edit` call and 167
+requests against 158.
+
+`rt-plan-ablation-module` spends five rounds per run on `complete_step` alone.
+A description change inviting the sign-off to share the next step's reply was
+taken up in 2 of 4 trials (4 of 5 sign-offs shared each time, against 0 of 20
+in control), and requests did not move: 30, 25, 21, 28 against 27, 23, 24, 30.
+At this spread, four trials per arm cannot show a saving of a few rounds.
+
+## Gaps
+
+- **Below the intended size, in places.** The tasks were designed for 25–50
+  requests. After widening, the median is 25, but `rt-rate-lookup-signatures`
+  still runs 13–15: the model greps every call site first and batches the edits,
+  so even about 20 call sites cost few rounds, and no run hit a compile-error
+  loop.
+- **Lexical grader.** `rt-stale-skills` judges Markdown by resolving what it
+  names. It has misjudged correct text twice (see the baseline note); a new
+  failure there should be read before it is counted.
+- **No git history.** The workdir is a plain directory: `git diff`, `git log`
+  and `git status` have nothing to read, so runs that lean on them in this tree
+  behave differently here.
+- **Plan marker and `-force-planner`.** `rt-plan-ablation-module` carries the
+  plan-first marker in its prompt, so it engages the planner in every arm,
+  including runs without `-force-planner`. Exclude it when comparing planner
+  arms.
@@ -0,0 +1,18 @@
+---
+name: price-change
+description: Record a vendor's announced price change in the official price book without losing the rate it replaces.
+---
+
+# Recording a price change
+
+1. Find the vendor's rows in `officialRates` in
+   `internal/contract/pricing/rates.go`. Each row is one model in one currency.
+2. **Append** a `rateGeneration` to the row's `Rates`; never edit an existing
+   one. Set `From` to the first billed day (`YYYY-MM-DD`, UTC) when the change
+   is announced ahead of time.
+3. Leave the earlier generation where it is: `SupersededRates` reads it so a
+   stored price that matches it is recognised as ours and refreshed.
+4. Update the row's `CheckedOn` constant to the day you confirmed the page.
+5. Add a test beside `rates_test.go` that pins `CurrentRate` before and after
+   the `From` day by replacing `today`.
+6. Run `make check`. `make pricecheck` needs the network and is run by hand.
@@ -0,0 +1,17 @@
+.PHONY: check test vet fmt pricecheck
+
+check: fmt vet test
+
+fmt:
+	@out="$$(gofmt -l .)"; if [ -n "$$out" ]; then echo "gofmt needed:"; echo "$$out"; exit 1; fi
+
+vet:
+	go vet ./...
+
+test:
+	go test ./...
+
+# Reads each vendor's pricing page; this snapshot carries no network client.
+pricecheck:
+	@echo "pricecheck: reaches each vendor's pricing page and needs the network; not available in this snapshot" >&2
+	@exit 2
@@ -0,0 +1,69 @@
+# Reasonix kernel snapshot
+
+A trimmed slice of the Reasonix Go kernel: the contracts a benchmark report is
+priced and labelled with, a few leaf utilities, and `benchctl`, a small command
+that prints what those contracts answer.
+
+```bash
+make check                                   # gofmt, vet, test
+go run ./cmd/benchctl rate -model deepseek-flash -currency USD
+go run ./cmd/benchctl cost -provider mimo -model mimo-v2.5 -miss 1000000
+go run ./cmd/benchctl tariff -currency CNY -at 2026-10-12T02:00:00Z
+go run ./cmd/benchctl arm -ablate planner,evidence
+```
+
+## Packages
+
+| Package | Owns |
+| --- | --- |
+| `internal/contract/pricing` | the official price book, cost quotes, the spend ledger |
+| `internal/contract/ablation` | which subsystems a benchmark arm switches off, and the arm's name |
+| `internal/contract/agentgraph` | the vocabulary of one run's execution graph |
+| `internal/base/retrieval` | BM25 ranking over CJK-aware tokens |
+| `internal/base/rulelist` | splitting a one-line permission rule list |
+| `internal/base/tokencount` | a cheap token estimate |
+| `internal/base/neterr` | classifying transport errors |
+| `internal/base/nilutil` | typed-nil detection |
+| `cmd/benchctl` | prints rates, costs, peak schedules and arm names |
+
+## Pricing
+
+A `RateCard` is a price per million tokens in one currency:
+
+| Field | Charges |
+| --- | --- |
+| `CacheHit` | prompt tokens served from the provider's cache |
+| `Input` | prompt tokens that missed the cache, including tokens written to it |
+| `Output` | completion tokens |
+
+`OriginalCostAmount` turns a card and a `UsageTokens` breakdown into a
+fixed-point `Amount`; `PricingFingerprint` keys a card in the ledger, so a
+stored ledger entry stays attached to the card it was priced with.
+`CurrentRate` and `SupersededRates` answer from `officialRates`, which only
+ever grows: a price change appends a generation.
+
+## Ablation
+
+`ablation.Parse` reads a comma-separated list of modules to switch off, and
+`Set.Arm` names the result (`full` for the control). The switchable modules,
+in the order arm names use:
+
+| Module | Off means |
+| --- | --- |
+| `evidence` | no evidence gate on completion claims |
+| `planner` | no two-model planning turn |
+| `subagent` | no delegation to workers |
+| `retrieval` | no retrieval over the folded transcript |
+| `compaction` | no context folding |
+| `upstream` | a dependency edge orders its endpoints without delivering the answer |
+| `recall-search` | recall can read a given address but cannot search for one |
+
+The fold-index scale is a separate axis (`-fold-index`), not a module.
+
+## Skills
+
+Project skills live under `.reasonix/skills/<name>/SKILL.md`.
+
+| Skill | Use it to |
+| --- | --- |
+| `price-change` | record a vendor's price change in the price book |
@@ -0,0 +1,51 @@
+# Reasonix project memory
+
+This checkout is a trimmed snapshot of the Reasonix kernel: the billing,
+ablation and graph contracts and a handful of leaf utilities, plus one small
+command that drives them. The conventions below are the project's own.
+
+## Conventions
+
+- Go kernel under `internal/`; each package owns one concern. A package's long
+  explanation belongs in its `doc.go`, not spread across implementation files.
+- Judgements read structure, never wording: types, contracts, schemas. An
+  error a caller must tell apart carries an identity — a sentinel, a typed
+  code — never a sentence.
+- A metric is its definition, not its name. Before a number becomes a finding,
+  state what it counts, from which anchor, over which population, and what it
+  excludes.
+
+## Comments
+
+Default is none — the code is the truth. Write one only when the **why** is
+non-obvious: a hidden constraint, an invariant the type system cannot express,
+or an external-protocol quirk. A comment states the constraint that holds now;
+it does not narrate how the code got here. English, always.
+
+- Declaration doc: ≤5 lines. Package comment: ≤8 lines, or ≤40 in a `doc.go`.
+- Every other comment: ≤3 lines. Struct-field and trailing `//`: 1 line.
+- One responsibility per file; 800 lines is the ceiling.
+
+## Vendor rates
+
+Official list prices live in one place: `officialRates` in
+`internal/contract/pricing/rates.go`, oldest generation first, the last being
+what a model charges today. A price change is an **append, never an edit** —
+the superseded rate is what lets an installed config be recognised as holding
+one of ours and brought forward. Callers read these through
+`pricing.CurrentRate` and `pricing.SupersededRates` and restate none of them.
+
+`make pricecheck` compares that table against each vendor's own page. It needs
+the network, so it is not part of `make check`.
+
+## Before every commit
+
+```bash
+make check    # gofmt -l, go vet ./..., go test ./...
+```
+
+## Change discipline
+
+List callers, consumers of the same state and sibling features before editing.
+Fix at the owning layer; a fix that breaks a neighbouring behaviour is a failed
+fix. Write tests first; they must fail without the change.
@@ -0,0 +1,115 @@
+// Command benchctl prints what the pricing and ablation contracts answer for
+// one model or one benchmark arm, so a reviewer can check a rate or an arm name
+// without writing a test.
+package main
+
+import (
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+
+	"reasonix/internal/contract/ablation"
+	"reasonix/internal/contract/pricing"
+)
+
+var errUsage = errors.New("usage: benchctl rate|cost|tariff|arm [flags]")
+
+func main() {
+	if err := run(os.Args[1:], os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "benchctl:", err)
+		os.Exit(2)
+	}
+}
+
+func run(args []string, out io.Writer) error {
+	if len(args) == 0 {
+		return errUsage
+	}
+	switch args[0] {
+	case "rate":
+		return runRate(args[1:], out)
+	case "cost":
+		return runCost(args[1:], out)
+	case "tariff":
+		return runTariff(args[1:], out)
+	case "arm":
+		return runArm(args[1:], out)
+	default:
+		return fmt.Errorf("%w: unknown subcommand %q", errUsage, args[0])
+	}
+}
+
+func runRate(args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("rate", flag.ContinueOnError)
+	fs.SetOutput(out)
+	provider := fs.String("provider", "deepseek", "vendor")
+	model := fs.String("model", "deepseek-flash", "model id")
+	currency := fs.String("currency", "", "currency; empty reads the vendor's default")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	cur := *currency
+	if cur == "" {
+		cur = pricing.DefaultCurrency(*provider)
+	}
+	card := pricing.CurrentRate(*provider, *model, cur)
+	if card == nil {
+		return fmt.Errorf("no official rate for %s/%s in %s", *provider, *model, cur)
+	}
+	fmt.Fprintf(out, "%s/%s %s: cache-hit %g input %g output %g per 1M\n",
+		*provider, *model, card.Currency, card.CacheHit, card.Input, card.Output)
+	if entry, ok := pricing.LookupCatalog(*provider, *model, cur, ""); ok && entry.DocURL != "" {
+		fmt.Fprintf(out, "source: %s\n", entry.DocURL)
+	}
+	fmt.Fprintf(out, "superseded generations: %d\n", len(pricing.SupersededRates(*provider, *model, cur)))
+	return nil
+}
+
+func runCost(args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("cost", flag.ContinueOnError)
+	fs.SetOutput(out)
+	provider := fs.String("provider", "deepseek", "vendor")
+	model := fs.String("model", "deepseek-flash", "model id")
+	currency := fs.String("currency", "", "currency; empty reads the vendor's default")
+	hit := fs.Int("hit", 0, "cached prompt tokens")
+	miss := fs.Int("miss", 0, "uncached prompt tokens")
+	completion := fs.Int("completion", 0, "completion tokens")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	cur := *currency
+	if cur == "" {
+		cur = pricing.DefaultCurrency(*provider)
+	}
+	card := pricing.CurrentRate(*provider, *model, cur)
+	if card == nil {
+		return fmt.Errorf("no official rate for %s/%s in %s", *provider, *model, cur)
+	}
+	usage := pricing.UsageTokens{CacheHitTokens: *hit, CacheMissTokens: *miss, CompletionTokens: *completion}
+	amount := pricing.OriginalCostAmount(*card, usage)
+	fmt.Fprintf(out, "%s %s\n", amount, pricing.NormalizeCurrency(card.Currency))
+	return nil
+}
+
+func runArm(args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("arm", flag.ContinueOnError)
+	fs.SetOutput(out)
+	spec := fs.String("ablate", "", "comma-separated modules to switch off: "+ablation.ModuleList())
+	foldIndex := fs.String("fold-index", "", "fold-index scale: default, half, quarter or off")
+	list := fs.Bool("list", false, "list the switchable modules")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	if *list {
+		fmt.Fprintln(out, ablation.ModuleList())
+		return nil
+	}
+	set, err := ablation.ParseArm(*spec, *foldIndex)
+	if err != nil {
+		return err
+	}
+	fmt.Fprintln(out, set.Arm())
+	return nil
+}
@@ -0,0 +1,65 @@
+package main
+
+import (
+	"bytes"
+	"errors"
+	"strings"
+	"testing"
+)
+
+func runOut(t *testing.T, args ...string) string {
+	t.Helper()
+	var out bytes.Buffer
+	if err := run(args, &out); err != nil {
+		t.Fatalf("run %v: %v", args, err)
+	}
+	return out.String()
+}
+
+func TestRateNamesTheCurrentCard(t *testing.T) {
+	got := runOut(t, "rate", "-provider", "mimo", "-model", "mimo-v2.5")
+	if !strings.Contains(got, "mimo/mimo-v2.5 CNY: cache-hit 0.02 input 1 output 2 per 1M") {
+		t.Fatalf("rate output = %q", got)
+	}
+}
+
+func TestRateRefusesAnUnpricedModel(t *testing.T) {
+	var out bytes.Buffer
+	if err := run([]string{"rate", "-provider", "nobody", "-model", "x"}, &out); err == nil {
+		t.Fatal("an unpriced model must fail")
+	}
+}
+
+func TestCostChargesTheCurrentCard(t *testing.T) {
+	got := runOut(t, "cost", "-provider", "mimo", "-model", "mimo-v2.5", "-miss", "1000000", "-completion", "1000000")
+	if strings.TrimSpace(got) != "3 CNY" {
+		t.Fatalf("cost output = %q", got)
+	}
+}
+
+func TestArmNamesTheConfiguration(t *testing.T) {
+	if got := strings.TrimSpace(runOut(t, "arm")); got != "full" {
+		t.Fatalf("control arm = %q", got)
+	}
+	if got := strings.TrimSpace(runOut(t, "arm", "-ablate", "planner,evidence", "-fold-index", "half")); got != "no-evidence+no-planner+index-half" {
+		t.Fatalf("arm = %q", got)
+	}
+}
+
+func TestUnknownSubcommandIsAUsageError(t *testing.T) {
+	var out bytes.Buffer
+	if err := run([]string{"nope"}, &out); !errors.Is(err, errUsage) {
+		t.Fatalf("err = %v, want errUsage", err)
+	}
+}
+
+func TestTariffReadsTheVendorsSchedule(t *testing.T) {
+	got := runOut(t, "tariff", "-provider", "mimo", "-model", "mimo-v2.5")
+	if !strings.Contains(got, "official card: true") || !strings.Contains(got, "one rate around the clock") {
+		t.Fatalf("tariff output = %q", got)
+	}
+	peak := runOut(t, "tariff", "-currency", "CNY", "-at", "2026-10-12T02:00:00Z")
+	if !strings.Contains(peak, "peak=true until 2026-10-12T04:00:00Z") {
+		t.Fatalf("deepseek tariff at a weekday peak = %q", peak)
+	}
+}
@@ -0,0 +1,49 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"io"
+	"time"
+
+	"reasonix/internal/contract/pricing"
+)
+
+func runTariff(args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("tariff", flag.ContinueOnError)
+	fs.SetOutput(out)
+	provider := fs.String("provider", "deepseek", "vendor")
+	model := fs.String("model", "deepseek-flash", "model id")
+	currency := fs.String("currency", "", "currency; empty reads the vendor's default")
+	at := fs.String("at", "", "instant to read the schedule at, RFC 3339; empty is now")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	when := time.Now()
+	if *at != "" {
+		t, err := time.Parse(time.RFC3339, *at)
+		if err != nil {
+			return fmt.Errorf("-at: %w", err)
+		}
+		when = t
+	}
+	cur := *currency
+	if cur == "" {
+		cur = pricing.DefaultCurrency(*provider)
+	}
+	card := pricing.CurrentRate(*provider, *model, cur)
+	if card == nil {
+		return fmt.Errorf("no official rate for %s/%s in %s", *provider, *model, cur)
+	}
+	fmt.Fprintf(out, "official card: %v\n", pricing.IsOfficialCard(*provider, *model, *card))
+	tariff, ok := pricing.LiveTariff(*provider, *model, *card, when)
+	switch {
+	case !ok:
+		fmt.Fprintln(out, "schedule: one rate around the clock")
+	case !tariff.Changes:
+		fmt.Fprintf(out, "schedule: peak=%v, no change ahead\n", tariff.Peak)
+	default:
+		fmt.Fprintf(out, "schedule: peak=%v until %s\n", tariff.Peak, tariff.ChangesAt.UTC().Format(time.RFC3339))
+	}
+	return nil
+}
@@ -0,0 +1,3 @@
+module reasonix
+
+go 1.26.0
@@ -0,0 +1,95 @@
+package pricing
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+// Every catalog provider must declare at least one official endpoint, or its
+// rows become unreachable: a rate card is only matched against the catalog
+// after the entry's host identifies the vendor.
+func TestEveryCatalogProviderHasAnOfficialEndpoint(t *testing.T) {
+	declared := map[string]bool{}
+	for _, host := range officialEndpointHosts {
+		declared[host] = true
+	}
+	for _, entry := range OfficialCatalog() {
+		if !declared[entry.Provider] {
+			t.Errorf("catalog provider %q has no official endpoint host; its prices can never match", entry.Provider)
+		}
+	}
+}
+
+func TestOfficialProviderForEndpoint(t *testing.T) {
+	cases := []struct {
+		name    string
+		baseURL string
+		want    string
+	}{
+		{"official deepseek", "https://api.deepseek.com", "deepseek"},
+		{"official deepseek anthropic path", "https://api.deepseek.com/anthropic", "deepseek"},
+		{"official longcat", "https://api.longcat.chat/openai/v1", "longcat"},
+		{"official mimo region", "https://token-plan-sgp.xiaomimimo.com/v1", "mimo"},
+		{"uppercase host", "https://API.DeepSeek.com/v1", "deepseek"},
+		{"proxy that resells the model", "https://my-deepseek-proxy.internal/v1", ""},
+		{"vendor name in the path only", "https://gateway.example.com/deepseek/v1", ""},
+		{"lookalike registrable domain", "https://api.deepseek.com.evil.test/v1", ""},
+		{"empty", "", ""},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := OfficialProviderForEndpoint(tc.baseURL); got != tc.want {
+				t.Fatalf("OfficialProviderForEndpoint(%q) = %q, want %q", tc.baseURL, got, tc.want)
+			}
+		})
+	}
+}
+
+// pricesGoStaleAfter is how long a hand-copied rate is trusted before someone
+// reads the vendor's page again. No vendor here serves prices over an API, so
+// the alternative to this going red on a quiet day is learning about a change
+// from a user whose cost was wrong for months. Bumping CheckedOn without
+// opening DocURL defeats it; what this buys is that the question gets asked.
+const pricesGoStaleAfter = 90 * 24 * time.Hour
+
+func TestCatalogPricesHaveBeenCheckedRecently(t *testing.T) {
+	var undated, stale []string
+	// This snapshot never sees a vendor page again, so staleness is read at the
+	// day it was taken rather than the day the suite runs.
+	cutoff := time.Date(2026, 10, 19, 0, 0, 0, 0, time.UTC).Add(-pricesGoStaleAfter)
+	for _, e := range OfficialCatalog() {
+		where := e.Provider + "/" + e.Model + " " + e.Currency + " (" + e.DocURL + ")"
+		if e.CheckedOn == "" {
+			undated = append(undated, where)
+			continue
+		}
+		on, err := time.Parse("2006-01-02", e.CheckedOn)
+		if err != nil {
+			t.Fatalf("%s: CheckedOn %q is not YYYY-MM-DD", where, e.CheckedOn)
+		}
+		if on.Before(cutoff) {
+			stale = append(stale, where+" last checked "+e.CheckedOn)
+		}
+	}
+	if len(undated) > 0 {
+		t.Errorf("catalog rows with no CheckedOn — read the vendor's page and date them:\n  %s",
+			strings.Join(undated, "\n  "))
+	}
+	if len(stale) > 0 {
+		t.Errorf("catalog rows older than %d days. Open each DocURL, confirm or correct the rate, then set CheckedOn to today:\n  %s",
+			int(pricesGoStaleAfter.Hours()/24), strings.Join(stale, "\n  "))
+	}
+}
+
+// A row that names a peak card must say when it applies, and one that names a
+// window must have a card to charge inside it. Half of the pair silently prices
+// every hour the same, which is the bug the pair exists to prevent.
+func TestPeakRatesAndWindowsComeInPairs(t *testing.T) {
+	for _, e := range OfficialCatalog() {
+		where := e.Provider + "/" + e.Model + " " + e.Currency
+		if (e.Peak == nil) != (e.Window == nil) {
+			t.Errorf("%s: Peak and Window must be set together (peak=%v window=%v)", where, e.Peak != nil, e.Window != nil)
+		}
+	}
+}
@@ -0,0 +1,12 @@
+---
+name: ablation-arm
+description: Add a new switchable subsystem to the benchmark's ablation arms.
+---
+
+# Adding an ablation module
+
+1. Declare the module in `internal/ablation/modules.go` beside the others.
+2. Register it in `AllModules()` so `ParseSpec` accepts it.
+3. Arm names come from `Set.Name()`; check that yours reads `without-<module>`.
+4. Add the module to the flag help text in `cmd/bench/flags.go`.
+5. Run `make test`.
@@ -0,0 +1,15 @@
+---
+name: benchctl
+description: Check a rate, a cost, a peak schedule or an arm name from the command line instead of writing a test.
+---
+
+# Using benchctl
+
+1. Price a request with `benchctl quote -provider mimo -model mimo-v2.5 -tokens 1000000`;
+   it prints the amount and the currency.
+2. Read today's card with `benchctl rate -vendor deepseek -model deepseek-flash`.
+3. Ask whether a vendor is in its peak window with
+   `benchctl peak -currency CNY -at 1791770400` (Unix seconds).
+4. List the ablation modules with `benchctl arms`, and name an arm with
+   `benchctl arm -ablate planner,evidence -index half`.
+5. Every subcommand prints its flags with `-h`.
@@ -0,0 +1,13 @@
+---
+name: price-change
+description: Record a vendor's announced price change in the official price book.
+---
+
+# Recording a price change
+
+1. Open `internal/pricing/rates.go` and find the vendor's entry in
+   `officialPrices`.
+2. Edit the entry's `Input`, `Output` and `CacheHit` to the new values.
+3. If the change is announced ahead of time, set `EffectiveFrom` on the entry.
+4. Confirm `pricing.LatestRate` now returns the new card.
+5. Run `make test` and `make price-check`.
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Builds every task's workdir/ from one pinned commit of this repository plus
+# the fixture-authored files in base/ and overlay/<task-id>/. With --check it
+# rebuilds into a scratch directory and fails if any committed workdir differs.
+set -euo pipefail
+
+PIN=42636ddcb425b7af07abd88397d02c1cfe3adcf5
+PATHS=(
+	internal/contract/pricing
+	internal/contract/ablation
+	internal/contract/agentgraph
+	internal/base/retrieval
+	internal/base/rulelist
+	internal/base/tokencount
+	internal/base/neterr
+	internal/base/nilutil
+)
+
+here="$(cd "$(dirname "$0")" && pwd)"
+repo="$(git -C "$here" rev-parse --show-toplevel)"
+
+build() {
+	local id="$1" dest="$2"
+	rm -rf "$dest"
+	mkdir -p "$dest"
+	git -C "$repo" archive "$PIN" -- "${PATHS[@]}" | tar -x -C "$dest"
+	cp -R "$here/base/." "$dest/"
+	if [ -d "$here/overlay/$id" ]; then
+		cp -R "$here/overlay/$id/." "$dest/"
+	fi
+}
+
+check=0
+[ "${1:-}" = "--check" ] && check=1
+
+status=0
+for task in "$here"/tasks/*/; do
+	id="$(basename "$task")"
+	if [ "$check" = 1 ]; then
+		scratch="$(mktemp -d)"
+		build "$id" "$scratch/workdir"
+		if ! diff -r "$scratch/workdir" "$task/workdir" >/dev/null; then
+			echo "$id: workdir/ differs from the pinned snapshot; run $0" >&2
+			diff -rq "$scratch/workdir" "$task/workdir" >&2 || true
+			status=1
+		fi
+		rm -rf "$scratch"
+	else
+		build "$id" "$task/workdir"
+	fi
+done
+exit "$status"
@@ -0,0 +1,73 @@
+# Reasonix kernel snapshot
+
+A trimmed slice of the Reasonix Go kernel: the contracts a benchmark report is
+priced and labelled with, a few leaf utilities, and `benchctl`, a small command
+that prints what those contracts answer.
+
+```bash
+make check                                   # gofmt, vet, test
+go run ./cmd/benchctl rate -model deepseek-flash -currency USD
+go run ./cmd/benchctl cost -provider mimo -model mimo-v2.5 -miss 1000000
+go run ./cmd/benchctl tariff -currency CNY -at 2026-10-12T02:00:00Z
+go run ./cmd/benchctl arm -ablate planner,evidence
+```
+
+## Packages
+
+| Package | Owns |
+| --- | --- |
+| `internal/contract/pricing` | the official price book, cost quotes, the spend ledger |
+| `internal/contract/ablation` | which subsystems a benchmark arm switches off, and the arm's name |
+| `internal/contract/agentgraph` | the vocabulary of one run's execution graph |
+| `internal/base/retrieval` | BM25 ranking over CJK-aware tokens |
+| `internal/base/rulelist` | splitting a one-line permission rule list |
+| `internal/base/tokencount` | a cheap token estimate |
+| `internal/base/neterr` | classifying transport errors |
+| `internal/base/nilutil` | typed-nil detection |
+| `cmd/benchctl` | prints rates, costs, peak schedules and arm names |
+
+## Pricing
+
+A `RateCard` is a price per million tokens in one currency:
+
+| Field | Charges |
+| --- | --- |
+| `CacheHit` | prompt tokens served from the provider's cache |
+| `Input` | prompt tokens that missed the cache, and tokens written to it when `CacheWrite` is zero |
+| `Output` | completion tokens |
+| `CacheWrite` | tokens written to the cache, for a vendor that prices them separately (Anthropic) |
+
+A card without `CacheWrite` keeps the fingerprint it had before the field
+existed, so ledgers stored against it stay attached.
+
+`OriginalCostAmount` turns a card and a `UsageTokens` breakdown into a
+fixed-point `Amount`; `PricingFingerprint` keys a card in the ledger, so a
+stored ledger entry stays attached to the card it was priced with.
+`CurrentRate` and `SupersededRates` answer from `officialRates`, which only
+ever grows: a price change appends a generation.
+
+## Ablation
+
+`ablation.Parse` reads a comma-separated list of modules to switch off, and
+`Set.Arm` names the result (`full` for the control). The switchable modules,
+in the order arm names use:
+
+| Module | Off means |
+| --- | --- |
+| `evidence` | no evidence gate on completion claims |
+| `planner` | no two-model planning turn |
+| `subagent` | no delegation to workers |
+| `retrieval` | no retrieval over the folded transcript |
+| `compaction` | no context folding |
+| `upstream` | a dependency edge orders its endpoints without delivering the answer |
+| `recall-search` | recall can read a given address but cannot search for one |
+
+The fold-index scale is a separate axis (`-fold-index`), not a module.
+
+## Skills
+
+Project skills live under `.reasonix/skills/<name>/SKILL.md`.
+
+| Skill | Use it to |
+| --- | --- |
+| `price-change` | record a vendor's price change in the price book |
@@ -0,0 +1,119 @@
+// Command benchctl prints what the pricing and ablation contracts answer for
+// one model or one benchmark arm, so a reviewer can check a rate or an arm name
+// without writing a test.
+package main
+
+import (
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+
+	"reasonix/internal/contract/ablation"
+	"reasonix/internal/contract/pricing"
+)
+
+var errUsage = errors.New("usage: benchctl rate|cost|tariff|arm [flags]")
+
+func main() {
+	if err := run(os.Args[1:], os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "benchctl:", err)
+		os.Exit(2)
+	}
+}
+
+func run(args []string, out io.Writer) error {
+	if len(args) == 0 {
+		return errUsage
+	}
+	switch args[0] {
+	case "rate":
+		return runRate(args[1:], out)
+	case "cost":
+		return runCost(args[1:], out)
+	case "tariff":
+		return runTariff(args[1:], out)
+	case "arm":
+		return runArm(args[1:], out)
+	default:
+		return fmt.Errorf("%w: unknown subcommand %q", errUsage, args[0])
+	}
+}
+
+func runRate(args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("rate", flag.ContinueOnError)
+	fs.SetOutput(out)
+	provider := fs.String("provider", "deepseek", "vendor")
+	model := fs.String("model", "deepseek-flash", "model id")
+	currency := fs.String("currency", "", "currency; empty reads the vendor's default")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	cur := *currency
+	if cur == "" {
+		cur = pricing.DefaultCurrency(*provider)
+	}
+	card := pricing.CurrentRate(*provider, *model, cur)
+	if card == nil {
+		return fmt.Errorf("no official rate for %s/%s in %s", *provider, *model, cur)
+	}
+	fmt.Fprintf(out, "%s/%s %s: cache-hit %g input %g output %g", *provider, *model, card.Currency, card.CacheHit, card.Input, card.Output)
+	if card.CacheWrite != 0 {
+		fmt.Fprintf(out, " cache-write %g", card.CacheWrite)
+	}
+	fmt.Fprintln(out, " per 1M")
+	if entry, ok := pricing.LookupCatalog(*provider, *model, cur, ""); ok && entry.DocURL != "" {
+		fmt.Fprintf(out, "source: %s\n", entry.DocURL)
+	}
+	fmt.Fprintf(out, "superseded generations: %d\n", len(pricing.SupersededRates(*provider, *model, cur)))
+	return nil
+}
+
+func runCost(args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("cost", flag.ContinueOnError)
+	fs.SetOutput(out)
+	provider := fs.String("provider", "deepseek", "vendor")
+	model := fs.String("model", "deepseek-flash", "model id")
+	currency := fs.String("currency", "", "currency; empty reads the vendor's default")
+	hit := fs.Int("hit", 0, "cached prompt tokens")
+	miss := fs.Int("miss", 0, "uncached prompt tokens")
+	completion := fs.Int("completion", 0, "completion tokens")
+	write := fs.Int("write", 0, "uncached prompt tokens that were written to the cache")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	cur := *currency
+	if cur == "" {
+		cur = pricing.DefaultCurrency(*provider)
+	}
+	card := pricing.CurrentRate(*provider, *model, cur)
+	if card == nil {
+		return fmt.Errorf("no official rate for %s/%s in %s", *provider, *model, cur)
+	}
+	usage := pricing.UsageTokens{CacheHitTokens: *hit, CacheMissTokens: *miss, CompletionTokens: *completion, CacheWriteTokens: *write}
+	amount := pricing.OriginalCostAmount(*card, usage)
+	fmt.Fprintf(out, "%s %s\n", amount, pricing.NormalizeCurrency(card.Currency))
+	return nil
+}
+
+func runArm(args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("arm", flag.ContinueOnError)
+	fs.SetOutput(out)
+	spec := fs.String("ablate", "", "comma-separated modules to switch off: "+ablation.ModuleList())
+	foldIndex := fs.String("fold-index", "", "fold-index scale: default, half, quarter or off")
+	list := fs.Bool("list", false, "list the switchable modules")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	if *list {
+		fmt.Fprintln(out, ablation.ModuleList())
+		return nil
+	}
+	set, err := ablation.ParseArm(*spec, *foldIndex)
+	if err != nil {
+		return err
+	}
+	fmt.Fprintln(out, set.Arm())
+	return nil
+}
@@ -0,0 +1,3 @@
+module reasonix
+
+go 1.26.0
@@ -0,0 +1,37 @@
+package pricing
+
+import "testing"
+
+func TestCacheWriteRateChargesWrittenTokens(t *testing.T) {
+	card := RateCard{Input: 3, CacheWrite: 3.75, Currency: "USD"}
+	usage := UsageTokens{CacheMissTokens: 1000000, CacheWriteTokens: 400000}
+	if got := OriginalCostAmount(card, usage).String(); got != "3.3" {
+		t.Fatalf("cost = %s, want 3.3", got)
+	}
+	card.CacheWrite = 0
+	if got := OriginalCostAmount(card, usage).String(); got != "3" {
+		t.Fatalf("cost without a cache-write rate = %s, want 3", got)
+	}
+}
+
+func TestCacheWriteSeparatesFingerprintsAndCards(t *testing.T) {
+	base := RateCard{CacheHit: 0.02, Input: 1, Output: 2, Currency: "CNY"}
+	withWrite := base
+	withWrite.CacheWrite = 1.25
+	if PricingFingerprint(base) == PricingFingerprint(withWrite) {
+		t.Fatal("cache-write rate does not reach the fingerprint")
+	}
+	if sameCard(base, withWrite) {
+		t.Fatal("cards differing in CacheWrite compare equal")
+	}
+}
+
+func TestAnthropicPricesCacheWrites(t *testing.T) {
+	got := CurrentRate("anthropic", "claude-sonnet-4-5", "USD")
+	if got == nil || got.CacheWrite != 3.75 {
+		t.Fatalf("claude-sonnet-4-5 = %+v", got)
+	}
+	if OfficialProviderForEndpoint("https://api.anthropic.com/v1/messages") != "anthropic" {
+		t.Fatal("api.anthropic.com is not recognised as Anthropic's endpoint")
+	}
+}
@@ -0,0 +1,222 @@
+package pricing
+
+import (
+	"net/url"
+	"strings"
+	"time"
+)
+
+// Official catalog metadata: currency, model, effective dates, documentation
+// sources, and price fingerprints. User-custom prices always win over catalog.
+
+// CatalogEntry is one official list price for a model in a billing currency.
+type CatalogEntry struct {
+	Provider      string // deepseek | longcat | mimo | google
+	Model         string
+	Currency      string // ISO billing currency for this row
+	CacheHit      float64
+	Input         float64
+	Output        float64
+	CacheWrite    float64 // zero when the vendor bills cache writes at Input
+	EffectiveFrom string  // YYYY-MM-DD inclusive, empty = unbounded
+	EffectiveTo   string  // YYYY-MM-DD exclusive, empty = unbounded
+	DocURL        string
+	BillingMode   string // payg | subscription_equivalent
+	Notes         string
+	Fingerprint   string // filled by Register
+	// Peak is what the same tokens cost inside Window. Nil when the vendor
+	// bills one rate around the clock, and then the fields above are the rate.
+	Peak   *RateCard
+	Window *PeakWindow
+	// CheckedOn is when a person last read DocURL and confirmed these numbers.
+	// No vendor here serves prices over an API, so this date is all that stands
+	// between a price change and a readout that is quietly wrong.
+	CheckedOn string
+}
+
+// deepseekPeak is the schedule DeepSeek publishes: peak on weekday mornings and
+// afternoons, and — since 2026-08-23 — never at a weekend. Chinese public
+// holidays bill off-peak in full, per the same page.
+var deepseekPeak = &PeakWindow{
+	OffsetSeconds:  beijing,
+	Hours:          [][2]int{{9, 12}, {14, 18}},
+	WeekendOffPeak: "2026-08-23",
+	HolidayOffPeak: chineseStatutoryHolidays,
+}
+
+// chineseStatutoryHolidays are the State Council's 2026 public holidays, which
+// DeepSeek bills off-peak in full; extend it when the next notice is out. Make-up
+// workdays are absent: they fall on weekends, which are off-peak anyway.
+var chineseStatutoryHolidays = []string{
+	// New Year's Day: Jan 1-3.
+	"2026-01-01", "2026-01-02", "2026-01-03",
+	// Spring Festival: Feb 15-23.
+	"2026-02-15", "2026-02-16", "2026-02-17", "2026-02-18", "2026-02-19",
+	"2026-02-20", "2026-02-21", "2026-02-22", "2026-02-23",
+	// Qingming Festival: Apr 4-6.
+	"2026-04-04", "2026-04-05", "2026-04-06",
+	// Labor Day: May 1-5.
+	"2026-05-01", "2026-05-02", "2026-05-03", "2026-05-04", "2026-05-05",
+	// Dragon Boat Festival: Jun 19-21.
+	"2026-06-19", "2026-06-20", "2026-06-21",
+	// Mid-Autumn Festival: Sep 25-27.
+	"2026-09-25", "2026-09-26", "2026-09-27",
+	// National Day: Oct 1-7.
+	"2026-10-01", "2026-10-02", "2026-10-03", "2026-10-04",
+	"2026-10-05", "2026-10-06", "2026-10-07",
+}
+
+// checkedOn is when the tables below were last read off the vendors' pages.
+const checkedOn = "2026-08-22"
+
+// deepseekCheckedOn is when the DeepSeek rows were last read off that vendor's
+// page. Separate from checkedOn, because confirming one vendor's prices says
+// nothing about another's and a shared date would claim that it did.
+const deepseekCheckedOn = "2026-09-13"
+
+// mimoCheckedOn is when the V2.6 rows were read off the vendor's own docs.
+const mimoCheckedOn = "2026-10-06"
+
+// googleCheckedOn is when the Gemini rows were read off Google's pricing page.
+const googleCheckedOn = "2026-10-17"
+
+// anthropicCheckedOn is when the Claude rows were read off Anthropic's pricing page.
+const anthropicCheckedOn = "2026-10-19"
+
+// CatalogSourceURLs document public pricing pages.
+const (
+	DocDeepSeekPricing    = "https://api-docs.deepseek.com/quick_start/pricing"
+	DocDeepSeekPricingCNY = "https://api-docs.deepseek.com/zh-cn/quick_start/pricing"
+	DocLongCatPricingUSD  = "https://longcat.chat/platform/docs/Pricing/LongCat-2.0.html"
+	DocLongCatPricingCNY  = "https://longcat.chat/platform/docs/zh/pricing/long-cat-2.0"
+	DocMiMoPAYG           = "https://mimo.mi.com/docs/price/pay-as-you-go"
+	DocMiMoTokenPlan      = "https://platform.xiaomimimo.com/token-plan"
+	DocGeminiPricing      = "https://ai.google.dev/gemini-api/docs/pricing"
+	DocAnthropicPricing   = "https://www.anthropic.com/pricing"
+)
+
+// officialEndpointHosts maps a vendor's own API hostnames to the catalog
+// provider whose list prices apply there. Host equality is the test: a reseller
+// or proxy bills on its own terms even when it serves the same model, and an
+// entry merely named after a vendor is not evidence of the vendor's endpoint.
+var officialEndpointHosts = map[string]string{
+	"api.anthropic.com":                 "anthropic",
+	"api.deepseek.com":                  "deepseek",
+	"api.longcat.chat":                  "longcat",
+	"api.xiaomimimo.com":                "mimo",
+	"generativelanguage.googleapis.com": "google",
+	"token-plan-cn.xiaomimimo.com":      "mimo",
+	"token-plan-sgp.xiaomimimo.com":     "mimo",
+	"token-plan-ams.xiaomimimo.com":     "mimo",
+}
+
+// OfficialProviderForEndpoint returns the catalog provider whose official
+// prices apply to baseURL, or "" when the address is not a vendor's own API.
+func OfficialProviderForEndpoint(baseURL string) string {
+	u, err := url.Parse(strings.TrimSpace(baseURL))
+	if err != nil {
+		return ""
+	}
+	return officialEndpointHosts[strings.ToLower(u.Hostname())]
+}
+
+// OfficialCatalog is the built-in price book: the current generation of every
+// rate in officialRates, fingerprinted so a stored price can be recognised as
+// one of ours. User-custom prices always win over it.
+func OfficialCatalog() []CatalogEntry {
+	entries := officialCatalogRows()
+	for i := range entries {
+		entries[i].Fingerprint = PricingFingerprint(RateCardFromCatalog(entries[i]))
+	}
+	return entries
+}
+
+// LookupCatalog finds an official entry. billingMode empty matches payg first.
+func LookupCatalog(provider, model, currency, billingMode string) (CatalogEntry, bool) {
+	provider = strings.ToLower(strings.TrimSpace(provider))
+	model = strings.TrimSpace(model)
+	currency = NormalizeCurrency(currency)
+	billingMode = strings.TrimSpace(billingMode)
+	if billingMode == "" {
+		billingMode = BillingModePAYG
+	}
+	var fallback CatalogEntry
+	foundFallback := false
+	for _, e := range OfficialCatalog() {
+		if e.Provider != provider || e.Model != model {
+			continue
+		}
+		if NormalizeCurrency(e.Currency) != currency {
+			continue
+		}
+		if e.BillingMode == billingMode {
+			return e, true
+		}
+		if e.BillingMode == BillingModePAYG {
+			fallback = e
+			foundFallback = true
+		}
+	}
+	if foundFallback {
+		return fallback, true
+	}
+	return CatalogEntry{}, false
+}
+
+// RateCardFromCatalog builds a RateCard from a catalog entry's base rate.
+func RateCardFromCatalog(e CatalogEntry) RateCard {
+	return RateCard{
+		CacheHit:   e.CacheHit,
+		Input:      e.Input,
+		Output:     e.Output,
+		CacheWrite: e.CacheWrite,
+		Currency:   e.Currency,
+	}
+}
+
+// RatesAt is what this entry charges at t: the peak card inside its window, the
+// base card everywhere else. An entry without a window charges one rate, and
+// then t does not matter.
+func (e CatalogEntry) RatesAt(t time.Time) RateCard {
+	if e.Peak == nil || !e.Window.IsPeak(t) {
+		return RateCardFromCatalog(e)
+	}
+	peak := *e.Peak
+	peak.Currency = e.Currency
+	return peak
+}
+
+// InEffect reports whether this entry's dates cover the day t falls on.
+func (e CatalogEntry) InEffect(t time.Time) bool {
+	day := t.UTC().Format("2006-01-02")
+	if e.EffectiveFrom != "" && day < e.EffectiveFrom {
+		return false
+	}
+	return e.EffectiveTo == "" || day < e.EffectiveTo
+}
+
+// MatchesCatalog reports whether rates equal a known official entry.
+func MatchesCatalog(provider, model string, rates RateCard) (CatalogEntry, bool) {
+	cur := NormalizeCurrency(rates.Currency)
+	for _, e := range OfficialCatalog() {
+		if e.Provider != strings.ToLower(strings.TrimSpace(provider)) {
+			continue
+		}
+		if e.Model != strings.TrimSpace(model) {
+			continue
+		}
+		if NormalizeCurrency(e.Currency) != cur {
+			continue
+		}
+		// Either card identifies the vendor's own price. Which one a user
+		// happens to have configured says nothing about when they are billing:
+		// the hour decides that, and RatesAt is what reads it.
+		if sameCard(RateCardFromCatalog(e), rates) {
+			return e, true
+		}
+		if p := e.Peak; p != nil && sameCard(*p, rates) {
+			return e, true
+		}
+	}
+	return CatalogEntry{}, false
+}
@@ -0,0 +1,799 @@
+package pricing
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"slices"
+	"strings"
+	"time"
+)
+
+// Billing modes.
+const (
+	BillingModePAYG                   = "payg"
+	BillingModeSubscriptionEquivalent = "subscription_equivalent"
+)
+
+// Valuation basis values.
+const (
+	BasisIdentity      = "identity"
+	BasisOfficialTable = "official_table"
+	// BasisFX is retained for decoding pre-v6 persisted quotes only. New
+	// quotes never create FX valuations.
+	BasisFX = "fx"
+)
+
+// DisplayStatus describes whether a quote can satisfy its requested display.
+// It is deliberately separate from CostComplete: a known price-book amount
+// can exist even when no requested regional valuation is available.
+const (
+	DisplayStatusMatched          = "matched"
+	DisplayStatusFallbackOriginal = "fallback_original"
+	DisplayStatusBucketed         = "bucketed"
+	DisplayStatusUnavailable      = "unavailable"
+)
+
+// Aggregate modes describe how a session/run total was formed.
+const (
+	AggregateModeSingleCurrency  = "single_currency"
+	AggregateModeCommonValuation = "common_valuation"
+	AggregateModeCurrencyBuckets = "currency_buckets"
+)
+
+// Rate bands name which side of a vendor's peak window a call was billed on.
+// An aggregate is mixed when its calls fell on both sides.
+const (
+	RateBandPeak    = "peak"
+	RateBandOffPeak = "off_peak"
+	RateBandMixed   = "mixed"
+)
+
+// DisplayRequest identifies how a caller selected the requested presentation
+// currency. The source is runtime context only; it is never persisted as a
+// provider price or wallet fact.
+type DisplayRequest struct {
+	Currency string `json:"currency,omitempty"`
+	Source   string `json:"source,omitempty"`
+}
+
+const (
+	DisplaySourceExplicit = "explicit"
+	DisplaySourceWallet   = "wallet"
+	DisplaySourceAuto     = "auto"
+)
+
+func (r DisplayRequest) NormalizedCurrency() string {
+	return NormalizeCurrency(r.Currency)
+}
+
+// CostQuote is the host-side quoted cost for one model call (or an aggregate).
+// Original is the pricing-table currency fact; valuations hold identity or
+// official regional rate-card estimates. Selected is the display pick for the
+// current preference.
+type CostQuote struct {
+	Original Money `json:"original"`
+	// OriginalTotals is populated for mixed-currency aggregates. Individual
+	// quotes and single-currency totals may omit it.
+	OriginalTotals []Money              `json:"originalTotals,omitempty"`
+	Valuations     map[string]Valuation `json:"valuations,omitempty"`
+	Selected       *Money               `json:"selected,omitempty"`
+	BillingMode    string               `json:"billingMode,omitempty"`
+	Estimated      bool                 `json:"estimated"`
+	// CostComplete means usage and the price-book amount are known. It does not
+	// imply that a requested display currency is available.
+	CostComplete bool `json:"costComplete"`
+	// Coverage is the same fact with the states a boolean cannot hold: an
+	// aggregate that priced only some of its calls, and one that billed nothing.
+	Coverage string `json:"coverage,omitempty"`
+	// DisplayComplete means a single selected amount satisfies the display
+	// request. Complete is retained as the old wire alias.
+	DisplayComplete bool   `json:"displayComplete"`
+	Complete        bool   `json:"complete"`
+	DisplayStatus   string `json:"displayStatus,omitempty"`
+	AggregateMode   string `json:"aggregateMode,omitempty"`
+	// ModelRef / UsageSource / PricingFingerprint identify the ledger key.
+	ModelRef           string `json:"modelRef,omitempty"`
+	UsageSource        string `json:"usageSource,omitempty"`
+	PricingFingerprint string `json:"pricingFingerprint,omitempty"`
+	RateDate           string `json:"rateDate,omitempty"` // YYYY-MM-DD of FX used, if any
+	IncompleteReason   string `json:"incompleteReason,omitempty"`
+	LegacyEstimate     bool   `json:"legacyEstimate,omitempty"`
+	CatalogSource      string `json:"catalogSource,omitempty"`
+	// RateBand is set only for a rate confirmed as a vendor's own schedule; an
+	// aggregate that includes any call without one carries none.
+	RateBand string `json:"rateBand,omitempty"`
+}
+
+// Valuation is one currency view of a cost fact.
+type Valuation struct {
+	Money  Money         `json:"money"`
+	Basis  string        `json:"basis"`
+	Source string        `json:"source"`
+	AsOf   string        `json:"asOf"` // YYYY-MM-DD
+	Rate   *RateSnapshot `json:"rateSnapshot,omitempty"`
+	Stale  bool          `json:"stale,omitempty"`
+}
+
+// RateSnapshot records the FX observation used for a valuation.
+type RateSnapshot struct {
+	Base   string  `json:"base"`
+	Quote  string  `json:"quote"`
+	Rate   float64 `json:"rate"`
+	Source string  `json:"source"`
+	AsOf   string  `json:"asOf"`
+	Stale  bool    `json:"stale,omitempty"`
+}
+
+// RateCard is the per-1M-token price used to compute original cost. It mirrors
+// provider.Pricing without importing that package (billing is a leaf).
+type RateCard struct {
+	CacheHit float64 // per 1M cached prompt tokens
+	Input    float64 // per 1M uncached prompt tokens
+	Output   float64 // per 1M completion tokens
+	// CacheWrite is per 1M tokens written to the cache; zero bills them at Input.
+	CacheWrite float64
+	Currency   string // ISO or symbol; normalized on quote
+}
+
+// UsageTokens is the token breakdown needed for cost. Mirrors provider.Usage
+// fields without importing provider.
+type UsageTokens struct {
+	PromptTokens           int
+	CompletionTokens       int
+	CacheHitTokens         int
+	CacheMissTokens        int
+	CacheWriteTokens       int
+	CacheWriteBilledTokens float64
+	Estimated              bool
+}
+
+// QuoteInput drives a single CostQuote computation.
+type QuoteInput struct {
+	Usage              UsageTokens
+	Rates              RateCard
+	OccurredAt         time.Time
+	DisplayCurrency    string         // compatibility alias for Display.Currency
+	Display            DisplayRequest // runtime display request; empty means auto
+	BillingMode        string
+	ModelRef           string
+	UsageSource        string
+	CatalogSource      string
+	PricingFingerprint string
+	// ProviderKind is deepseek|longcat|mimo|… for official dual-table lookup.
+	// When empty, ModelRef and Rates are used to infer a catalog match.
+	ProviderKind string
+	// ModelID is the bare model id (e.g. deepseek-v4-flash). Empty → parse ModelRef.
+	ModelID string
+}
+
+// OriginalCostAmount computes the fixed-point original cost from rates + tokens.
+// Mirrors the historic provider.Pricing.Cost semantics.
+func OriginalCostAmount(rates RateCard, u UsageTokens) Amount {
+	hit := u.CacheHitTokens
+	miss := u.CacheMissTokens
+	if hit+miss == 0 && u.PromptTokens > 0 {
+		miss = u.PromptTokens
+	} else if miss == 0 && hit > 0 && u.PromptTokens > hit {
+		miss = u.PromptTokens - hit
+	}
+	write := u.CacheWriteTokens
+	write = max(write, 0)
+	write = min(write, miss)
+	billedWrite := 0.0
+	if write > 0 {
+		billedWrite = u.CacheWriteBilledTokens
+		if billedWrite <= 0 {
+			billedWrite = float64(write)
+		}
+	}
+	writeRate := rates.Input
+	if rates.CacheWrite > 0 {
+		writeRate = rates.CacheWrite
+	}
+	total := (float64(hit)*rates.CacheHit +
+		float64(miss-write)*rates.Input +
+		billedWrite*writeRate +
+		float64(u.CompletionTokens)*rates.Output) / 1e6
+	return NewAmountFromFloat(total)
+}
+
+// PricingFingerprint hashes a rate card for ledger keys.
+func PricingFingerprint(rates RateCard) string {
+	cur := NormalizeCurrency(rates.Currency)
+	raw := fmt.Sprintf("%s|%.12g|%.12g|%.12g", cur, rates.CacheHit, rates.Input, rates.Output)
+	if rates.CacheWrite != 0 {
+		// Appended only when set, so every card stored before the field keeps its key.
+		raw += fmt.Sprintf("|w%.12g", rates.CacheWrite)
+	}
+	sum := sha256.Sum256([]byte(raw))
+	return hex.EncodeToString(sum[:8])
+}
+
+// BuildQuote computes original cost and CNY/USD valuations.
+func BuildQuote(in QuoteInput) CostQuote {
+	state := newQuoteBuildState(in)
+	for _, target := range []string{"CNY", "USD"} {
+		state.addTargetValuation(target)
+	}
+	state.selectDisplay()
+	return state.quote
+}
+
+type quoteBuildState struct {
+	input             QuoteInput
+	currency          string
+	amount            Amount
+	occurred          time.Time
+	official          CatalogEntry
+	isOfficial        bool
+	valuationFailures map[string]string
+	quote             CostQuote
+}
+
+func newQuoteBuildState(in QuoteInput) *quoteBuildState {
+	currency := NormalizeCurrency(in.Rates.Currency)
+	if currency == "" {
+		currency = "CNY"
+	}
+	mode := strings.TrimSpace(in.BillingMode)
+	if mode == "" {
+		mode = BillingModePAYG
+	}
+	occurred := in.OccurredAt
+	if occurred.IsZero() {
+		occurred = time.Now().UTC()
+	}
+	fingerprint := strings.TrimSpace(in.PricingFingerprint)
+	if fingerprint == "" {
+		fingerprint = PricingFingerprint(in.Rates)
+	}
+	amount := OriginalCostAmount(in.Rates, in.Usage)
+	q := CostQuote{
+		Original:           MoneyOf(amount, currency),
+		Valuations:         map[string]Valuation{},
+		BillingMode:        mode,
+		Estimated:          true,
+		CostComplete:       true,
+		Coverage:           CoverageComplete,
+		DisplayComplete:    true,
+		Complete:           true,
+		DisplayStatus:      DisplayStatusMatched,
+		AggregateMode:      AggregateModeSingleCurrency,
+		ModelRef:           strings.TrimSpace(in.ModelRef),
+		UsageSource:        strings.TrimSpace(in.UsageSource),
+		PricingFingerprint: fingerprint,
+		CatalogSource:      strings.TrimSpace(in.CatalogSource),
+	}
+	q.Valuations[currency] = Valuation{
+		Money: q.Original, Basis: BasisIdentity,
+		Source: firstNonEmpty(in.CatalogSource, "rate_card"),
+		AsOf:   occurred.UTC().Format("2006-01-02"),
+	}
+	state := &quoteBuildState{
+		input: in, currency: currency, amount: amount, occurred: occurred,
+		valuationFailures: map[string]string{}, quote: q,
+	}
+	if !usageHasFacts(in.Usage) {
+		state.markIncomplete("missing_price_or_usage")
+	}
+	state.matchOfficialCatalog()
+	state.applyOfficialSchedule()
+	return state
+}
+
+// applyOfficialSchedule re-prices the turn at the vendor's rate for the hour it
+// actually happened. Only a rate confirmed as the vendor's own earns this: a
+// custom price is the user's own arrangement, and projecting someone else's
+// peak schedule onto it would invent a number nobody published.
+func (s *quoteBuildState) applyOfficialSchedule() {
+	if !s.isOfficial || s.official.Peak == nil {
+		return
+	}
+	s.quote.RateBand = RateBandOffPeak
+	if s.official.Window.IsPeak(s.occurred) {
+		s.quote.RateBand = RateBandPeak
+	}
+	rates := s.official.RatesAt(s.occurred)
+	if rates.CacheHit == s.input.Rates.CacheHit && rates.Input == s.input.Rates.Input && rates.Output == s.input.Rates.Output {
+		return
+	}
+	s.amount = OriginalCostAmount(rates, s.input.Usage)
+	s.quote.Original = MoneyOf(s.amount, s.currency)
+	s.quote.PricingFingerprint = PricingFingerprint(rates)
+	s.quote.Valuations[s.currency] = Valuation{
+		Money: s.quote.Original, Basis: BasisOfficialTable,
+		Source: s.official.DocURL,
+		AsOf:   s.occurred.UTC().Format("2006-01-02"),
+	}
+}
+
+func quoteDisplayRequest(in QuoteInput) DisplayRequest {
+	request := in.Display
+	if request.Currency == "" && in.DisplayCurrency != "" {
+		request.Currency = in.DisplayCurrency
+		if request.Source == "" {
+			request.Source = DisplaySourceExplicit
+		}
+	}
+	if request.Source == "" {
+		request.Source = DisplaySourceAuto
+	}
+	return request
+}
+
+func usageHasFacts(u UsageTokens) bool {
+	return u.PromptTokens > 0 || u.CompletionTokens > 0 || u.CacheHitTokens > 0 ||
+		u.CacheMissTokens > 0 || u.CacheWriteTokens > 0 || u.CacheWriteBilledTokens > 0
+}
+
+func (s *quoteBuildState) matchOfficialCatalog() {
+	providerKind, modelID := resolveCatalogIdentity(s.input)
+	s.official, s.isOfficial = MatchesCatalog(providerKind, modelID, s.input.Rates)
+	if !s.isOfficial && providerKind != "" && modelID != "" {
+		rates := s.input.Rates
+		rates.Currency = s.currency
+		s.official, s.isOfficial = MatchesCatalog(providerKind, modelID, rates)
+	}
+	if s.isOfficial && s.quote.CatalogSource == "" {
+		s.quote.CatalogSource = s.official.DocURL
+	}
+}
+
+func (s *quoteBuildState) addTargetValuation(target string) {
+	if target == s.currency {
+		return
+	}
+	if s.addOfficialValuation(target) {
+		return
+	}
+	// Runtime FX has intentionally been removed. A custom price that does not
+	// match the official catalog remains in its original currency.
+	s.valuationFailures[target] = "display_unavailable"
+}
+
+func (s *quoteBuildState) addOfficialValuation(target string) bool {
+	if !s.isOfficial {
+		return false
+	}
+	peer, ok := LookupCatalog(
+		s.official.Provider, s.official.Model, target, s.official.BillingMode,
+	)
+	if !ok {
+		return false
+	}
+	s.quote.Valuations[target] = Valuation{
+		Money: MoneyOf(OriginalCostAmount(peer.RatesAt(s.occurred), s.input.Usage), target),
+		Basis: BasisOfficialTable, Source: peer.DocURL,
+		AsOf: s.occurred.UTC().Format("2006-01-02"),
+	}
+	return true
+}
+
+func (s *quoteBuildState) selectDisplay() {
+	if !s.quote.CostComplete {
+		s.quote.Selected = nil
+		s.quote.DisplayComplete = false
+		s.quote.Complete = false
+		s.quote.DisplayStatus = DisplayStatusUnavailable
+		return
+	}
+	display := quoteDisplayRequest(s.input).NormalizedCurrency()
+	if display == "" {
+		selected := s.quote.Original
+		s.quote.Selected = &selected
+		return
+	}
+	if valuation, ok := s.quote.Valuations[display]; ok {
+		selected := valuation.Money
+		s.quote.Selected = &selected
+		return
+	}
+	// The original price-book amount is still a valid cost fact. Keep it as a
+	// visible fallback and distinguish the display mismatch from no pricing.
+	selected := s.quote.Original
+	s.quote.Selected = &selected
+	s.quote.DisplayComplete = false
+	s.quote.Complete = false
+	s.quote.DisplayStatus = DisplayStatusFallbackOriginal
+	s.quote.IncompleteReason = firstNonEmpty(s.valuationFailures[display], "display_unavailable")
+}
+
+func (s *quoteBuildState) markIncomplete(reason string) {
+	s.quote.CostComplete = false
+	s.quote.Coverage = CoverageIncomplete
+	s.quote.DisplayComplete = false
+	s.quote.Complete = false
+	s.quote.DisplayStatus = DisplayStatusUnavailable
+	if s.quote.IncompleteReason == "" {
+		s.quote.IncompleteReason = reason
+	}
+}
+
+// SelectForDisplay returns the money for a display currency preference without
+// recomputing rates. Empty display returns original.
+func (q CostQuote) SelectForDisplay(display string) (Money, bool) {
+	display = NormalizeCurrency(display)
+	if display == "" {
+		return q.Original, true
+	}
+	if v, ok := q.Valuations[display]; ok {
+		return v.Money, true
+	}
+	if NormalizeCurrency(q.Original.Currency) == display {
+		return q.Original, true
+	}
+	return Money{}, false
+}
+
+// WithSelected returns a copy with Selected set for display.
+func (q CostQuote) WithSelected(display string) CostQuote {
+	out := q
+	if m, ok := q.SelectForDisplay(display); ok {
+		out.Selected = &m
+		if quoteHasCompleteCostFact(q) {
+			out.Complete = true
+			out.IncompleteReason = ""
+		}
+	} else {
+		out.Selected = nil
+		out.Complete = false
+		if out.IncompleteReason == "" {
+			out.IncompleteReason = "display_unavailable"
+		}
+	}
+	return out
+}
+
+// LegacyCostFloat returns the selected (or original) amount as float64 for
+// compatibility aliases cost / costUsd / total_cost.
+func (q CostQuote) LegacyCostFloat() float64 {
+	if q.Selected != nil {
+		return q.Selected.Float64()
+	}
+	return q.Original.Float64()
+}
+
+// LegacyCurrencySymbol returns a display symbol for the selected/original currency.
+func (q CostQuote) LegacyCurrencySymbol() string {
+	if q.Selected != nil && q.Selected.Currency != "" {
+		return CurrencySymbol(q.Selected.Currency)
+	}
+	return CurrencySymbol(q.Original.Currency)
+}
+
+// LegacyCurrencyCode returns the ISO code for selected/original.
+func (q CostQuote) LegacyCurrencyCode() string {
+	if q.Selected != nil && q.Selected.Currency != "" {
+		return NormalizeCurrency(q.Selected.Currency)
+	}
+	return NormalizeCurrency(q.Original.Currency)
+}
+
+// AggregateQuotes combines occurrence-time quotes into a session/run total.
+// Every entry must have the requested valuation; partial totals stay unavailable.
+func AggregateQuotes(quotes []CostQuote, display string) CostQuote {
+	if len(quotes) == 0 {
+		return emptyAggregate(NormalizeCurrency(display))
+	}
+	accumulator := newQuoteAccumulator(display)
+	for _, quote := range quotes {
+		accumulator.add(quote)
+	}
+	return accumulator.finish()
+}
+
+type quoteAccumulator struct {
+	out              CostQuote
+	display          string
+	totals           map[string]Amount
+	originalCurrency string
+	originalTotal    Amount
+	originalTotals   map[string]Amount
+	originalComplete bool
+	coverage         string
+	displayComplete  bool
+	modes            map[string]struct{}
+	rateBands        map[string]struct{}
+	unbanded         bool
+}
+
+func emptyAggregate(display string) CostQuote {
+	out := CostQuote{
+		Original: MoneyOf(Zero, display), Valuations: map[string]Valuation{}, Estimated: true,
+		CostComplete: false, DisplayComplete: false, Complete: false,
+		Coverage:      CoverageNone,
+		DisplayStatus: DisplayStatusUnavailable, AggregateMode: AggregateModeSingleCurrency,
+		IncompleteReason: "no_usage",
+	}
+	return out
+}
+
+func newQuoteAccumulator(display string) *quoteAccumulator {
+	return &quoteAccumulator{
+		out:     CostQuote{Valuations: map[string]Valuation{}, Estimated: true},
+		display: NormalizeCurrency(display), totals: map[string]Amount{}, originalTotals: map[string]Amount{},
+		originalComplete: true, coverage: CoverageNone, displayComplete: true,
+		modes: map[string]struct{}{}, rateBands: map[string]struct{}{},
+	}
+}
+
+func (a *quoteAccumulator) add(quote CostQuote) {
+	quote = NormalizeQuote(quote)
+	a.coverage = FoldCoverage(a.coverage, quote.Coverage)
+	if quote.Coverage != CoverageComplete && a.out.IncompleteReason == "" {
+		a.out.IncompleteReason = quote.IncompleteReason
+	}
+	a.out.LegacyEstimate = a.out.LegacyEstimate || quote.LegacyEstimate
+	if quote.BillingMode != "" {
+		a.modes[quote.BillingMode] = struct{}{}
+	}
+	a.addRateBand(quote.RateBand)
+	if quote.RateDate > a.out.RateDate {
+		a.out.RateDate = quote.RateDate
+	}
+	originalCurrency := NormalizeCurrency(quote.Original.Currency)
+	if len(quote.OriginalTotals) > 0 {
+		for _, original := range quote.OriginalTotals {
+			a.addOriginal(original, NormalizeCurrency(original.Currency))
+		}
+	} else {
+		a.addOriginal(quote.Original, originalCurrency)
+	}
+	if a.display != "" {
+		_, found := quote.Valuations[a.display]
+		a.displayComplete = a.displayComplete && (found || originalCurrency == a.display)
+	}
+	originalIncluded := false
+	for code, valuation := range quote.Valuations {
+		code = NormalizeCurrency(code)
+		if code == originalCurrency {
+			originalIncluded = true
+		}
+		a.addValuation(code, valuation)
+	}
+	if originalCurrency != "" && !originalIncluded {
+		a.addValuation(originalCurrency, Valuation{
+			Money: quote.Original, Basis: BasisIdentity, Source: "aggregate",
+			AsOf: time.Now().UTC().Format("2006-01-02"),
+		})
+	}
+}
+
+func (a *quoteAccumulator) addRateBand(band string) {
+	switch band {
+	case RateBandPeak, RateBandOffPeak:
+		a.rateBands[band] = struct{}{}
+	case RateBandMixed:
+		a.rateBands[RateBandPeak], a.rateBands[RateBandOffPeak] = struct{}{}, struct{}{}
+	default:
+		a.unbanded = true
+	}
+}
+
+func (a *quoteAccumulator) rateBand() string {
+	if a.unbanded {
+		return ""
+	}
+	switch len(a.rateBands) {
+	case 1:
+		for band := range a.rateBands {
+			return band
+		}
+	case 2:
+		return RateBandMixed
+	}
+	return ""
+}
+
+func (a *quoteAccumulator) addOriginal(original Money, currency string) {
+	if currency != "" {
+		a.originalTotals[currency] = a.originalTotals[currency].Add(original.AmountValue())
+	}
+	if a.originalCurrency == "" {
+		a.originalCurrency = currency
+		a.originalTotal = original.AmountValue()
+		return
+	}
+	if currency != a.originalCurrency {
+		a.originalComplete = false
+		return
+	}
+	a.originalTotal = a.originalTotal.Add(original.AmountValue())
+}
+
+func (a *quoteAccumulator) addValuation(code string, valuation Valuation) {
+	if code == "" {
+		return
+	}
+	a.totals[code] = a.totals[code].Add(valuation.Money.AmountValue())
+	current, found := a.out.Valuations[code]
+	if !found {
+		current = valuation
+	}
+	current.Money = MoneyOf(a.totals[code], code)
+	current.Stale = current.Stale || valuation.Stale
+	a.out.Valuations[code] = current
+}
+
+// costFactsComplete reads the accumulated coverage rather than tracking the
+// same fact a second time: two answers to one question drift.
+func (a *quoteAccumulator) costFactsComplete() bool {
+	return a.coverage == CoverageComplete
+}
+
+func (a *quoteAccumulator) finish() CostQuote {
+	a.out.Coverage = a.coverage
+	a.out.CostComplete = a.costFactsComplete()
+	if a.originalComplete && a.originalCurrency != "" {
+		a.out.Original = MoneyOf(a.originalTotal, a.originalCurrency)
+		a.syncOriginalValuation()
+	} else {
+		a.out.Original = Money{Amount: "0"}
+	}
+	if len(a.originalTotals) > 1 {
+		codes := make([]string, 0, len(a.originalTotals))
+		for code := range a.originalTotals {
+			codes = append(codes, code)
+		}
+		slices.Sort(codes)
+		for _, code := range codes {
+			a.out.OriginalTotals = append(a.out.OriginalTotals, MoneyOf(a.originalTotals[code], code))
+		}
+	}
+	a.out.RateBand = a.rateBand()
+	if len(a.modes) == 1 {
+		for mode := range a.modes {
+			a.out.BillingMode = mode
+		}
+	}
+	if a.display == "" && a.originalComplete && a.costFactsComplete() {
+		selected := a.out.Original
+		a.out.Selected = &selected
+		a.out.DisplayComplete = true
+		a.out.Complete = true
+		a.out.DisplayStatus = DisplayStatusMatched
+		a.out.AggregateMode = AggregateModeSingleCurrency
+		return a.out
+	}
+	valuation, found := a.out.Valuations[a.display]
+	if found && a.displayComplete && a.costFactsComplete() {
+		selected := valuation.Money
+		a.out.Selected = &selected
+		a.out.DisplayComplete = true
+		a.out.Complete = true
+		a.out.DisplayStatus = DisplayStatusMatched
+		if len(a.originalTotals) > 1 {
+			a.out.AggregateMode = AggregateModeCommonValuation
+		} else {
+			a.out.AggregateMode = AggregateModeSingleCurrency
+		}
+		return a.out
+	}
+	a.out.DisplayComplete = false
+	a.out.Complete = false
+	if !a.costFactsComplete() {
+		a.out.DisplayStatus = DisplayStatusUnavailable
+		a.out.IncompleteReason = firstNonEmpty(a.out.IncompleteReason, "incomplete_cost_fact")
+	} else if a.originalComplete && a.originalCurrency != "" {
+		selected := a.out.Original
+		a.out.Selected = &selected
+		a.out.DisplayStatus = DisplayStatusFallbackOriginal
+		a.out.AggregateMode = AggregateModeSingleCurrency
+		a.out.IncompleteReason = firstNonEmpty(a.out.IncompleteReason, "display_unavailable")
+	} else {
+		a.out.DisplayStatus = DisplayStatusBucketed
+		a.out.AggregateMode = AggregateModeCurrencyBuckets
+		a.out.IncompleteReason = firstNonEmpty(a.out.IncompleteReason, "currency_buckets")
+	}
+	return a.out
+}
+
+// NormalizeQuote fills fields introduced after the first CostQuote wire shape.
+// It is used at every persistence and transport boundary so old telemetry and
+// old eventwire payloads remain safe without inventing a new amount.
+func NormalizeQuote(q CostQuote) CostQuote {
+	if !q.CostComplete && !q.DisplayComplete && q.Complete {
+		q.CostComplete = true
+		q.DisplayComplete = true
+	}
+	if q.DisplayStatus != "" && q.DisplayStatus != DisplayStatusMatched && q.DisplayStatus != DisplayStatusFallbackOriginal && q.DisplayStatus != DisplayStatusBucketed && q.DisplayStatus != DisplayStatusUnavailable {
+		q.DisplayStatus = ""
+	}
+	if q.RateBand != RateBandPeak && q.RateBand != RateBandOffPeak && q.RateBand != RateBandMixed {
+		q.RateBand = ""
+	}
+	if q.AggregateMode != "" && q.AggregateMode != AggregateModeSingleCurrency && q.AggregateMode != AggregateModeCommonValuation && q.AggregateMode != AggregateModeCurrencyBuckets {
+		q.AggregateMode = ""
+	}
+	if q.DisplayStatus == "" {
+		switch {
+		case q.Complete:
+			q.DisplayStatus = DisplayStatusMatched
+		case q.Original.Currency != "" && q.Original.Amount != "" && q.IncompleteReason != "no_price":
+			q.DisplayStatus = DisplayStatusFallbackOriginal
+		default:
+			q.DisplayStatus = DisplayStatusUnavailable
+		}
+	}
+	if q.AggregateMode == "" {
+		if len(q.OriginalTotals) > 1 {
+			q.AggregateMode = AggregateModeCurrencyBuckets
+		} else if q.Selected != nil {
+			q.AggregateMode = AggregateModeSingleCurrency
+		}
+	}
+	if !ValidCoverage(q.Coverage) {
+		q.Coverage = CoverageIncomplete
+		if quoteHasCompleteCostFact(q) {
+			q.Coverage = CoverageComplete
+		}
+	}
+	q.Complete = q.DisplayComplete
+	return q
+}
+
+// quoteHasCompleteCostFact separates a known original-currency charge from a
+// display-only valuation failure must not poison an exact original total,
+// while unpriced and unrecoverable legacy records stay incomplete in every
+// display currency.
+func quoteHasCompleteCostFact(q CostQuote) bool {
+	if q.CostComplete {
+		return true
+	}
+	switch q.IncompleteReason {
+	case "no_price", "missing_price_or_usage", "legacy_unrecoverable",
+		"legacy_wiped_or_zero", "legacy_invalid_amount", "mixed_original_currencies",
+		"incomplete_cost_fact":
+		return false
+	}
+	if q.Complete {
+		return true
+	}
+	currency := NormalizeCurrency(q.Original.Currency)
+	if currency == "" {
+		return false
+	}
+	valuation, ok := q.Valuations[currency]
+	return ok && SameCurrency(valuation.Money.Currency, currency)
+}
+
+func (a *quoteAccumulator) syncOriginalValuation() {
+	valuation, found := a.out.Valuations[a.originalCurrency]
+	if !found {
+		valuation = Valuation{
+			Basis: BasisIdentity, Source: "aggregate",
+			AsOf: time.Now().UTC().Format("2006-01-02"),
+		}
+	}
+	valuation.Money = a.out.Original
+	a.out.Valuations[a.originalCurrency] = valuation
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, v := range values {
+		if strings.TrimSpace(v) != "" {
+			return strings.TrimSpace(v)
+		}
+	}
+	return ""
+}
+
+// resolveCatalogIdentity names which official table, if any, may price a quote.
+// The vendor comes only from ProviderKind, which the caller reads off the
+// endpoint's host; guessing it from the entry's name or the model id would bill
+// a relay as the vendor it resells. Unnamed means no official table — the user's
+// own rate card, which is right rather than merely plausible.
+func resolveCatalogIdentity(in QuoteInput) (provider, model string) {
+	provider = strings.ToLower(strings.TrimSpace(in.ProviderKind))
+	model = strings.TrimSpace(in.ModelID)
+	if model == "" {
+		ref := strings.TrimSpace(in.ModelRef)
+		if i := strings.LastIndex(ref, "/"); i >= 0 && i+1 < len(ref) {
+			model = ref[i+1:]
+		} else {
+			model = ref
+		}
+	}
+	return provider, model
+}
@@ -0,0 +1,358 @@
+// rates.go — every rate this project has shipped for a vendor's model, and the
+// two questions that asks: what it costs now, and what it used to cost.
+package pricing
+
+import (
+	"slices"
+	"strings"
+	"time"
+)
+
+// rateGeneration is one published pair. Peak is nil for a generation the vendor
+// billed at a single rate around the clock.
+type rateGeneration struct {
+	Base RateCard
+	Peak *RateCard
+	// From is the first day (YYYY-MM-DD, UTC) this generation is billed; empty
+	// means from when it shipped. An announced change is appended with its date.
+	From string
+}
+
+// today is the day a dated generation is read against; a test replaces it.
+var today = func() string { return time.Now().UTC().Format("2006-01-02") }
+
+// currentIndex is the generation in force today: the last one whose date has
+// come. Rows with no dated generation answer with their last, as before.
+func (r officialRateRow) currentIndex() int {
+	day := today()
+	for i := len(r.Rates) - 1; i > 0; i-- {
+		if r.Rates[i].From == "" || r.Rates[i].From <= day {
+			return i
+		}
+	}
+	return 0
+}
+
+// officialRateRow is one vendor's model, in one currency, under one billing
+// mode, with every rate this project has shipped for it.
+type officialRateRow struct {
+	Provider    string
+	Model       string
+	Currency    string
+	BillingMode string
+	Window      *PeakWindow
+	DocURL      string
+	Notes       string
+	CheckedOn   string
+	// Rates is oldest first; the last entry is what this costs today.
+	Rates []rateGeneration
+}
+
+// officialRates is the price book. A price change appends a generation rather
+// than editing one: that is what leaves the superseded rate where a stored price
+// can still be recognised as this project's own default instead of a number its
+// user chose, which is the difference between refreshing one and losing it.
+var officialRates = []officialRateRow{
+	{
+		Provider: "deepseek", Model: "deepseek-flash", Currency: "CNY",
+		BillingMode: BillingModePAYG, Window: deepseekPeak, DocURL: DocDeepSeekPricing, CheckedOn: deepseekCheckedOn,
+		Rates: []rateGeneration{
+			{Base: RateCard{CacheHit: 0.02, Input: 1, Output: 2, Currency: "CNY"}},
+			{Base: RateCard{CacheHit: 0.05, Input: 1.5, Output: 4.5, Currency: "CNY"},
+				Peak: &RateCard{CacheHit: 0.10, Input: 3.0, Output: 9.0, Currency: "CNY"}},
+			{Base: RateCard{CacheHit: 0.02, Input: 1, Output: 4, Currency: "CNY"},
+				Peak: &RateCard{CacheHit: 0.04, Input: 2, Output: 8, Currency: "CNY"}},
+		},
+	},
+	{
+		Provider: "deepseek", Model: "deepseek-flash", Currency: "USD",
+		BillingMode: BillingModePAYG, Window: deepseekPeak, DocURL: DocDeepSeekPricing, CheckedOn: deepseekCheckedOn,
+		Rates: []rateGeneration{
+			{Base: RateCard{CacheHit: 0.0028, Input: 0.14, Output: 0.28, Currency: "USD"}},
+			{Base: RateCard{CacheHit: 0.007, Input: 0.22, Output: 0.66, Currency: "USD"},
+				Peak: &RateCard{CacheHit: 0.014, Input: 0.44, Output: 1.32, Currency: "USD"}},
+			{Base: RateCard{CacheHit: 0.003, Input: 0.15, Output: 0.6, Currency: "USD"},
+				Peak: &RateCard{CacheHit: 0.006, Input: 0.3, Output: 1.2, Currency: "USD"}},
+		},
+	},
+	{
+		Provider: "deepseek", Model: "deepseek-v4-pro", Currency: "CNY",
+		BillingMode: BillingModePAYG, Window: deepseekPeak, DocURL: DocDeepSeekPricing, CheckedOn: deepseekCheckedOn,
+		Rates: []rateGeneration{
+			{Base: RateCard{CacheHit: 0.025, Input: 3, Output: 6, Currency: "CNY"}},
+			{Base: RateCard{CacheHit: 0.15, Input: 4.5, Output: 13.5, Currency: "CNY"},
+				Peak: &RateCard{CacheHit: 0.30, Input: 9.0, Output: 27.0, Currency: "CNY"}},
+		},
+	},
+	{
+		Provider: "deepseek", Model: "deepseek-v4-pro", Currency: "USD",
+		BillingMode: BillingModePAYG, Window: deepseekPeak, DocURL: DocDeepSeekPricing, CheckedOn: deepseekCheckedOn,
+		Rates: []rateGeneration{
+			{Base: RateCard{CacheHit: 0.003625, Input: 0.435, Output: 0.87, Currency: "USD"}},
+			{Base: RateCard{CacheHit: 0.022, Input: 0.66, Output: 1.98, Currency: "USD"},
+				Peak: &RateCard{CacheHit: 0.044, Input: 1.32, Output: 3.96, Currency: "USD"}},
+		},
+	},
+
+	// LongCat's launch discount, for which the vendor publishes no end date. List
+	// price is CNY 0.10/5/20, USD 0.015/0.75/2.95 — what these revert to, and why
+	// CheckedOn earns its place here.
+	{
+		Provider: "longcat", Model: "LongCat-2.0", Currency: "CNY",
+		BillingMode: BillingModePAYG, DocURL: DocLongCatPricingCNY, Notes: "launch_discount_no_end_date", CheckedOn: checkedOn,
+		Rates: []rateGeneration{{Base: RateCard{CacheHit: 0.04, Input: 2, Output: 8, Currency: "CNY"}}},
+	},
+	{
+		Provider: "longcat", Model: "LongCat-2.0", Currency: "USD",
+		BillingMode: BillingModePAYG, DocURL: DocLongCatPricingUSD, Notes: "launch_discount_no_end_date", CheckedOn: checkedOn,
+		Rates: []rateGeneration{{Base: RateCard{CacheHit: 0.006, Input: 0.30, Output: 1.20, Currency: "USD"}}},
+	},
+
+	// Google: the two flash models double on 2027-01-01, hence the dated generation.
+	// gemini-3.1-pro-preview is the rate up to 200k prompt tokens; gemini-4-argon has no price.
+	{
+		Provider: "google", Model: "gemini-3.8-flash", Currency: "USD",
+		BillingMode: BillingModePAYG, DocURL: DocGeminiPricing, CheckedOn: googleCheckedOn,
+		Rates: []rateGeneration{
+			{Base: RateCard{CacheHit: 0.075, Input: 0.75, Output: 3.75, Currency: "USD"}},
+			{From: "2027-01-01", Base: RateCard{CacheHit: 0.15, Input: 1.50, Output: 7.50, Currency: "USD"}},
+		},
+	},
+	{
+		Provider: "google", Model: "gemini-3.6-flash", Currency: "USD",
+		BillingMode: BillingModePAYG, DocURL: DocGeminiPricing, CheckedOn: googleCheckedOn,
+		Rates: []rateGeneration{
+			{Base: RateCard{CacheHit: 0.075, Input: 0.75, Output: 3.75, Currency: "USD"}},
+			{From: "2027-01-01", Base: RateCard{CacheHit: 0.15, Input: 1.50, Output: 7.50, Currency: "USD"}},
+		},
+	},
+	{
+		Provider: "google", Model: "gemini-3.5-flash-lite", Currency: "USD",
+		BillingMode: BillingModePAYG, DocURL: DocGeminiPricing, CheckedOn: googleCheckedOn,
+		Rates: []rateGeneration{{Base: RateCard{CacheHit: 0.03, Input: 0.30, Output: 2.50, Currency: "USD"}}},
+	},
+	{
+		Provider: "google", Model: "gemini-3.1-pro-preview", Currency: "USD",
+		BillingMode: BillingModePAYG, DocURL: DocGeminiPricing, Notes: "up_to_200k_prompt_tokens", CheckedOn: googleCheckedOn,
+		Rates: []rateGeneration{{Base: RateCard{CacheHit: 0.20, Input: 2.00, Output: 12.00, Currency: "USD"}}},
+	},
+
+	{
+		Provider: "anthropic", Model: "claude-sonnet-4-5", Currency: "USD",
+		BillingMode: BillingModePAYG, DocURL: DocAnthropicPricing, CheckedOn: anthropicCheckedOn,
+		Rates: []rateGeneration{{Base: RateCard{CacheHit: 0.30, Input: 3, Output: 15, CacheWrite: 3.75, Currency: "USD"}}},
+	},
+
+	// MiMo domestic PAYG; Token Plan bills the same rates as subscription_equivalent.
+	{
+		Provider: "mimo", Model: "mimo-v2.5-pro", Currency: "CNY",
+		BillingMode: BillingModePAYG, DocURL: DocMiMoPAYG, CheckedOn: checkedOn,
+		Rates: []rateGeneration{{Base: RateCard{CacheHit: 0.025, Input: 3, Output: 6, Currency: "CNY"}}},
+	},
+	{
+		Provider: "mimo", Model: "mimo-v2.5", Currency: "CNY",
+		BillingMode: BillingModePAYG, DocURL: DocMiMoPAYG, CheckedOn: checkedOn,
+		Rates: []rateGeneration{{Base: RateCard{CacheHit: 0.02, Input: 1, Output: 2, Currency: "CNY"}}},
+	},
+	// Not on the vendor's price page as of CheckedOn. Kept because removing a rate
+	// is what turns a still-configured model's cost silently into zero; a stale
+	// rate at least reads as a number somebody can question.
+	{
+		Provider: "mimo", Model: "mimo-v2-flash", Currency: "CNY",
+		BillingMode: BillingModePAYG, DocURL: DocMiMoPAYG, Notes: "not_on_vendor_page", CheckedOn: checkedOn,
+		Rates: []rateGeneration{{Base: RateCard{CacheHit: 0.07, Input: 0.70, Output: 2.10, Currency: "CNY"}}},
+	},
+	{
+		Provider: "mimo", Model: "mimo-v2.5-pro", Currency: "CNY",
+		BillingMode: BillingModeSubscriptionEquivalent, DocURL: DocMiMoTokenPlan, Notes: "payg_equivalent_not_plan_bill", CheckedOn: checkedOn,
+		Rates: []rateGeneration{{Base: RateCard{CacheHit: 0.025, Input: 3, Output: 6, Currency: "CNY"}}},
+	},
+	{
+		Provider: "mimo", Model: "mimo-v2.5", Currency: "CNY",
+		BillingMode: BillingModeSubscriptionEquivalent, DocURL: DocMiMoTokenPlan, Notes: "payg_equivalent_not_plan_bill", CheckedOn: checkedOn,
+		Rates: []rateGeneration{{Base: RateCard{CacheHit: 0.02, Input: 1, Output: 2, Currency: "CNY"}}},
+	},
+	{
+		Provider: "mimo", Model: "mimo-v2.6-pro", Currency: "CNY",
+		BillingMode: BillingModePAYG, DocURL: DocMiMoPAYG, CheckedOn: mimoCheckedOn,
+		Rates: []rateGeneration{{Base: RateCard{CacheHit: 0.025, Input: 3, Output: 6, Currency: "CNY"}}},
+	},
+	{
+		Provider: "mimo", Model: "mimo-v2.6-flash", Currency: "CNY",
+		BillingMode: BillingModePAYG, DocURL: DocMiMoPAYG, CheckedOn: mimoCheckedOn,
+		Rates: []rateGeneration{{Base: RateCard{CacheHit: 0.02, Input: 1, Output: 2, Currency: "CNY"}}},
+	},
+	{
+		Provider: "mimo", Model: "mimo-v2.6-pro-ultraspeed", Currency: "CNY",
+		BillingMode: BillingModePAYG, DocURL: DocMiMoPAYG, CheckedOn: mimoCheckedOn,
+		Rates: []rateGeneration{{Base: RateCard{CacheHit: 0.25, Input: 30, Output: 60, Currency: "CNY"}}},
+	},
+	{
+		Provider: "mimo", Model: "mimo-v2.6-pro", Currency: "CNY",
+		BillingMode: BillingModeSubscriptionEquivalent, DocURL: DocMiMoTokenPlan, Notes: "payg_equivalent_not_plan_bill", CheckedOn: mimoCheckedOn,
+		Rates: []rateGeneration{{Base: RateCard{CacheHit: 0.025, Input: 3, Output: 6, Currency: "CNY"}}},
+	},
+	{
+		Provider: "mimo", Model: "mimo-v2.6-flash", Currency: "CNY",
+		BillingMode: BillingModeSubscriptionEquivalent, DocURL: DocMiMoTokenPlan, Notes: "payg_equivalent_not_plan_bill", CheckedOn: mimoCheckedOn,
+		Rates: []rateGeneration{{Base: RateCard{CacheHit: 0.02, Input: 1, Output: 2, Currency: "CNY"}}},
+	},
+}
+
+// retiredDeepSeekFlashModels are names DeepSeek still answers as its current
+// flash model, at that model's price. Owned here because that is where the rates
+// they bill at live; config reads them through the accessor below.
+var retiredDeepSeekFlashModels = []string{"deepseek-v4-flash", "deepseek-v4-flash-vision-exp"}
+
+// RetiredDeepSeekFlashModels copies the list on the way out: a caller sorting or
+// trimming the result would otherwise change what every other caller sees.
+func RetiredDeepSeekFlashModels() []string {
+	return append([]string(nil), retiredDeepSeekFlashModels...)
+}
+
+// RateModelFor answers which model's rate a name is billed at — a retired name
+// at the model that replaced it, an older spelling at the one it was renamed
+// from. Scoped to billing on purpose: two models can share a rate without being
+// the same model, and nothing outside a price lookup may read this as identity.
+func RateModelFor(provider, model string) string {
+	model = strings.TrimSpace(model)
+	switch strings.ToLower(strings.TrimSpace(provider)) {
+	case "deepseek":
+		if slices.Contains(retiredDeepSeekFlashModels, model) {
+			return "deepseek-flash"
+		}
+	case "mimo":
+		switch model {
+		case "mimo-v2-pro":
+			return "mimo-v2.5-pro"
+		case "mimo-v2-omni":
+			return "mimo-v2.5"
+		}
+	}
+	return model
+}
+
+// DefaultCurrency is what a vendor's rates are quoted in when an entry does not
+// say. A vendor publishing one currency leaves no choice to make; DeepSeek
+// prices in both, and USD is what an entry that never chose has been read as.
+func DefaultCurrency(provider string) string {
+	provider = strings.ToLower(strings.TrimSpace(provider))
+	seen := map[string]bool{}
+	for _, row := range officialRates {
+		if row.Provider == provider {
+			seen[row.Currency] = true
+		}
+	}
+	if len(seen) == 1 {
+		for currency := range seen {
+			return currency
+		}
+	}
+	return "USD"
+}
+
+// officialRateRowsFor finds the rows for a model, which is more than one when a
+// vendor publishes the same rates under two billing modes.
+func officialRateRowsFor(provider, model, currency string) []officialRateRow {
+	provider, currency = strings.ToLower(strings.TrimSpace(provider)), NormalizeCurrency(currency)
+	model = RateModelFor(provider, model)
+	var out []officialRateRow
+	for _, row := range officialRates {
+		if row.Provider == provider && row.Model == model && row.Currency == currency {
+			out = append(out, row)
+		}
+	}
+	return out
+}
+
+// CurrentRate is what a vendor's model costs in a currency today — the off-peak
+// card, which is what a caller charging one rate should quote. Nil when this
+// catalog prices neither. A model published under two billing modes quotes the
+// pay-as-you-go rate, which is the one an unsubscribed caller is charged.
+func CurrentRate(provider, model, currency string) *RateCard {
+	for _, row := range officialRateRowsFor(provider, model, currency) {
+		if row.BillingMode == BillingModeSubscriptionEquivalent {
+			continue
+		}
+		if len(row.Rates) > 0 {
+			rate := row.Rates[row.currentIndex()].Base
+			return &rate
+		}
+	}
+	return nil
+}
+
+// IsOfficialCard reports whether card is a rate this project has shipped for the
+// model in the card's own currency: any generation, its off-peak or its peak
+// card. A card that is none of them is the user's, or damaged, and cannot be
+// valued against the vendor's other-currency table.
+func IsOfficialCard(provider, model string, card RateCard) bool {
+	for _, row := range officialRateRowsFor(provider, model, card.Currency) {
+		if row.BillingMode == BillingModeSubscriptionEquivalent {
+			continue
+		}
+		for _, generation := range row.Rates {
+			if sameCard(generation.Base, card) || generation.Peak != nil && sameCard(*generation.Peak, card) {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func sameCard(a, b RateCard) bool {
+	return a.CacheHit == b.CacheHit && a.Input == b.Input && a.Output == b.Output && a.CacheWrite == b.CacheWrite
+}
+
+// SupersededRates are the rates shipped for a model before the current one. A
+// stored price matching one came from this project rather than from its user, so
+// a refresh may replace it; anything else is theirs and is left alone.
+func SupersededRates(provider, model, currency string) []RateCard {
+	var out []RateCard
+	for _, row := range officialRateRowsFor(provider, model, currency) {
+		if row.BillingMode == BillingModeSubscriptionEquivalent || len(row.Rates) < 2 {
+			continue
+		}
+		for _, generation := range row.Rates[:row.currentIndex()] {
+			out = append(out, generation.Base)
+		}
+	}
+	return out
+}
+
+// officialCatalogRows publishes the current generation of every row, plus the
+// retired DeepSeek names, which bill at the flash rate under their own id.
+func officialCatalogRows() []CatalogEntry {
+	rows := make([]CatalogEntry, 0, len(officialRates)+len(retiredDeepSeekFlashModels)*2)
+	for _, row := range officialRates {
+		if len(row.Rates) == 0 {
+			continue
+		}
+		current := row.Rates[row.currentIndex()]
+		rows = append(rows, row.entry(row.Model, current))
+		if row.Provider != "deepseek" || row.Model != "deepseek-flash" {
+			continue
+		}
+		for _, retired := range retiredDeepSeekFlashModels {
+			rows = append(rows, row.entry(retired, current))
+		}
+	}
+	return rows
+}
+
+func (r officialRateRow) entry(model string, current rateGeneration) CatalogEntry {
+	// Copied, so a caller holding a returned row cannot reach back into the
+	// table every other caller reads.
+	var peak *RateCard
+	if current.Peak != nil {
+		card := *current.Peak
+		peak = &card
+	}
+	return CatalogEntry{
+		Provider: r.Provider, Model: model, Currency: r.Currency,
+		CacheHit: current.Base.CacheHit, Input: current.Base.Input, Output: current.Base.Output,
+		CacheWrite: current.Base.CacheWrite,
+		Peak:       peak, Window: r.Window, DocURL: r.DocURL,
+		BillingMode: r.BillingMode, Notes: r.Notes, CheckedOn: r.CheckedOn,
+	}
+}
@@ -0,0 +1,12 @@
+prompt = """Some providers bill tokens written into their prompt cache at a rate of their own. Add that to the pricing contract in this repository:
+
+- `RateCard` gains a `CacheWrite` rate, per 1M tokens like the others. Zero means the card has no separate cache-write price, and cache-written tokens keep being charged at `Input` exactly as they are today.
+- When a card sets `CacheWrite`, `OriginalCostAmount` charges the billed cache-write units (`CacheWriteBilledTokens` when set, otherwise `CacheWriteTokens`) at `CacheWrite` instead of `Input`.
+- `PricingFingerprint` must tell apart two cards that differ only in `CacheWrite`, but a card without one must keep exactly the fingerprint it has today: stored ledgers are keyed by it.
+- Two cards that differ only in `CacheWrite` are different cards everywhere cards are compared, including official-card recognition and catalog matching.
+- `CatalogEntry` carries the rate too, and `RateCardFromCatalog` and `CatalogEntry.RatesAt` hand it back.
+- Add Anthropic to the official price book: `claude-sonnet-4-5`, pay-as-you-go in USD, cache hit 0.30, input 3, output 15 and cache write 3.75 per 1M tokens, documented at https://www.anthropic.com/pricing and checked 2026-10-19. `api.anthropic.com` is Anthropic's own endpoint.
+- `benchctl cost` gains a `-write` flag for cache-written tokens, and `benchctl rate` shows a card's cache-write rate when it has one.
+- Add tests for the new behaviour and update the README's pricing section."""
+class = "multi-file-feature"
+timeout_sec = 1200
@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+set -e
+export GOFLAGS=-mod=mod GOTOOLCHAIN=local
+cat > internal/contract/pricing/zz_grader_test.go <<'GO'
+package pricing
+
+import (
+	"testing"
+	"time"
+)
+
+func TestGraderCacheWriteCost(t *testing.T) {
+	card := RateCard{CacheHit: 0.3, Input: 3, Output: 15, Currency: "USD"}
+	priced := card
+	priced.CacheWrite = 3.75
+	cases := []struct {
+		name  string
+		card  RateCard
+		usage UsageTokens
+		want  string
+	}{
+		{"no write, no rate", card, UsageTokens{CacheHitTokens: 200000, CacheMissTokens: 800000, CompletionTokens: 50000}, "3.21"},
+		{"no write, rate set", priced, UsageTokens{CacheHitTokens: 200000, CacheMissTokens: 800000, CompletionTokens: 50000}, "3.21"},
+		{"write at input", card, UsageTokens{CacheMissTokens: 1000000, CacheWriteTokens: 400000, CompletionTokens: 100000}, "4.5"},
+		{"write at cache-write", priced, UsageTokens{CacheMissTokens: 1000000, CacheWriteTokens: 400000, CompletionTokens: 100000}, "4.8"},
+		{"billed units at input", card, UsageTokens{CacheMissTokens: 1000000, CacheWriteTokens: 400000, CacheWriteBilledTokens: 500000}, "3.3"},
+		{"billed units at cache-write", priced, UsageTokens{CacheMissTokens: 1000000, CacheWriteTokens: 400000, CacheWriteBilledTokens: 500000}, "3.675"},
+	}
+	for _, tc := range cases {
+		if got := OriginalCostAmount(tc.card, tc.usage).String(); got != tc.want {
+			t.Errorf("%s: cost = %s, want %s", tc.name, got, tc.want)
+		}
+	}
+}
+
+func TestGraderFingerprintKeepsStoredKeys(t *testing.T) {
+	cny := RateCard{CacheHit: 0.02, Input: 1, Output: 4, Currency: "CNY"}
+	usd := RateCard{CacheHit: 0.3, Input: 3, Output: 15, Currency: "USD"}
+	if got := PricingFingerprint(cny); got != "ba96037de26c3f79" {
+		t.Errorf("fingerprint of a card without CacheWrite moved: %s", got)
+	}
+	if got := PricingFingerprint(usd); got != "e16b53b4599e5fda" {
+		t.Errorf("fingerprint of a card without CacheWrite moved: %s", got)
+	}
+	withWrite := usd
+	withWrite.CacheWrite = 3.75
+	if PricingFingerprint(withWrite) == PricingFingerprint(usd) {
+		t.Error("cards differing only in CacheWrite share a fingerprint")
+	}
+	other := usd
+	other.CacheWrite = 6
+	if PricingFingerprint(withWrite) == PricingFingerprint(other) {
+		t.Error("two different CacheWrite rates share a fingerprint")
+	}
+}
+
+func TestGraderCacheWriteIsPartOfCardIdentity(t *testing.T) {
+	official := RateCard{CacheHit: 0.02, Input: 1, Output: 2, Currency: "CNY"}
+	if !IsOfficialCard("mimo", "mimo-v2.5", official) {
+		t.Fatal("the official mimo-v2.5 card is no longer recognised")
+	}
+	changed := official
+	changed.CacheWrite = 1.25
+	if IsOfficialCard("mimo", "mimo-v2.5", changed) {
+		t.Error("a card with a cache-write rate the vendor never published is recognised as official")
+	}
+	if _, ok := MatchesCatalog("mimo", "mimo-v2.5", official); !ok {
+		t.Fatal("the official mimo-v2.5 card no longer matches the catalog")
+	}
+	if _, ok := MatchesCatalog("mimo", "mimo-v2.5", changed); ok {
+		t.Error("a card with an unpublished cache-write rate matches the catalog")
+	}
+}
+
+func TestGraderAnthropicIsPriced(t *testing.T) {
+	want := RateCard{CacheHit: 0.30, Input: 3, Output: 15, CacheWrite: 3.75, Currency: "USD"}
+	got := CurrentRate("anthropic", "claude-sonnet-4-5", "USD")
+	if got == nil || *got != want {
+		t.Fatalf("CurrentRate(anthropic, claude-sonnet-4-5) = %+v, want %+v", got, want)
+	}
+	if !IsOfficialCard("anthropic", "claude-sonnet-4-5", want) {
+		t.Error("the Anthropic card is not recognised as official")
+	}
+	e, ok := LookupCatalog("anthropic", "claude-sonnet-4-5", "USD", "")
+	if !ok || e.DocURL != "https://www.anthropic.com/pricing" || e.CheckedOn != "2026-10-19" || e.CacheWrite != 3.75 {
+		t.Errorf("catalog entry = %+v, %v", e, ok)
+	}
+	if got := OfficialProviderForEndpoint("https://api.anthropic.com/v1/messages"); got != "anthropic" {
+		t.Errorf("api.anthropic.com resolves to %q", got)
+	}
+	if got := DefaultCurrency("anthropic"); got != "USD" {
+		t.Errorf("DefaultCurrency(anthropic) = %q", got)
+	}
+}
+
+func TestGraderCatalogCarriesCacheWrite(t *testing.T) {
+	e := CatalogEntry{Provider: "x", Model: "y", Currency: "USD", CacheHit: 0.1, Input: 1, Output: 2, CacheWrite: 1.25}
+	if got := RateCardFromCatalog(e); got.CacheWrite != 1.25 || got.Input != 1 {
+		t.Errorf("RateCardFromCatalog = %+v", got)
+	}
+	if got := e.RatesAt(time.Date(2026, 3, 4, 12, 0, 0, 0, time.UTC)); got.CacheWrite != 1.25 {
+		t.Errorf("RatesAt = %+v", got)
+	}
+}
+GO
+gofmt_out="$(gofmt -l .)"
+[ -z "$gofmt_out" ] || { echo "gofmt needed: $gofmt_out"; exit 1; }
+go vet ./...
+go test ./... >/dev/null
+out="$(go run ./cmd/benchctl cost -provider mimo -model mimo-v2.5 -miss 1000000 -write 400000)"
+[ "$out" = "1 CNY" ] || { echo "benchctl cost -write: got $out"; exit 1; }
+out="$(go run ./cmd/benchctl rate -provider anthropic -model claude-sonnet-4-5)"
+case "$out" in *"cache-write 3.75"*) ;; *) echo "benchctl rate does not show the cache-write rate: $out"; exit 1 ;; esac
+out="$(go run ./cmd/benchctl rate -provider mimo -model mimo-v2.5)"
+case "$out" in *"cache-write"*) echo "benchctl rate shows a cache-write rate the card does not have: $out"; exit 1 ;; esac
+grep -lE 'CacheWrite:' internal/contract/pricing/*_test.go | grep -qv zz_grader_test.go \
+	|| { echo "no test of the pricing package sets a CacheWrite rate"; exit 1; }
+awk '/^## Pricing/{on=1; next} /^## /{on=0} on' README.md | grep -q 'CacheWrite' \
+	|| { echo "README's pricing section does not mention CacheWrite"; exit 1; }
@@ -0,0 +1,18 @@
+---
+name: price-change
+description: Record a vendor's announced price change in the official price book without losing the rate it replaces.
+---
+
+# Recording a price change
+
+1. Find the vendor's rows in `officialRates` in
+   `internal/contract/pricing/rates.go`. Each row is one model in one currency.
+2. **Append** a `rateGeneration` to the row's `Rates`; never edit an existing
+   one. Set `From` to the first billed day (`YYYY-MM-DD`, UTC) when the change
+   is announced ahead of time.
+3. Leave the earlier generation where it is: `SupersededRates` reads it so a
+   stored price that matches it is recognised as ours and refreshed.
+4. Update the row's `CheckedOn` constant to the day you confirmed the page.
+5. Add a test beside `rates_test.go` that pins `CurrentRate` before and after
+   the `From` day by replacing `today`.
+6. Run `make check`. `make pricecheck` needs the network and is run by hand.
@@ -0,0 +1,17 @@
+.PHONY: check test vet fmt pricecheck
+
+check: fmt vet test
+
+fmt:
+	@out="$$(gofmt -l .)"; if [ -n "$$out" ]; then echo "gofmt needed:"; echo "$$out"; exit 1; fi
+
+vet:
+	go vet ./...
+
+test:
+	go test ./...
+
+# Reads each vendor's pricing page; this snapshot carries no network client.
+pricecheck:
+	@echo "pricecheck: reaches each vendor's pricing page and needs the network; not available in this snapshot" >&2
+	@exit 2
@@ -0,0 +1,69 @@
+# Reasonix kernel snapshot
+
+A trimmed slice of the Reasonix Go kernel: the contracts a benchmark report is
+priced and labelled with, a few leaf utilities, and `benchctl`, a small command
+that prints what those contracts answer.
+
+```bash
+make check                                   # gofmt, vet, test
+go run ./cmd/benchctl rate -model deepseek-flash -currency USD
+go run ./cmd/benchctl cost -provider mimo -model mimo-v2.5 -miss 1000000
+go run ./cmd/benchctl tariff -currency CNY -at 2026-10-12T02:00:00Z
+go run ./cmd/benchctl arm -ablate planner,evidence
+```
+
+## Packages
+
+| Package | Owns |
+| --- | --- |
+| `internal/contract/pricing` | the official price book, cost quotes, the spend ledger |
+| `internal/contract/ablation` | which subsystems a benchmark arm switches off, and the arm's name |
+| `internal/contract/agentgraph` | the vocabulary of one run's execution graph |
+| `internal/base/retrieval` | BM25 ranking over CJK-aware tokens |
+| `internal/base/rulelist` | splitting a one-line permission rule list |
+| `internal/base/tokencount` | a cheap token estimate |
+| `internal/base/neterr` | classifying transport errors |
+| `internal/base/nilutil` | typed-nil detection |
+| `cmd/benchctl` | prints rates, costs, peak schedules and arm names |
+
+## Pricing
+
+A `RateCard` is a price per million tokens in one currency:
+
+| Field | Charges |
+| --- | --- |
+| `CacheHit` | prompt tokens served from the provider's cache |
+| `Input` | prompt tokens that missed the cache, including tokens written to it |
+| `Output` | completion tokens |
+
+`OriginalCostAmount` turns a card and a `UsageTokens` breakdown into a
+fixed-point `Amount`; `PricingFingerprint` keys a card in the ledger, so a
+stored ledger entry stays attached to the card it was priced with.
+`CurrentRate` and `SupersededRates` answer from `officialRates`, which only
+ever grows: a price change appends a generation.
+
+## Ablation
+
+`ablation.Parse` reads a comma-separated list of modules to switch off, and
+`Set.Arm` names the result (`full` for the control). The switchable modules,
+in the order arm names use:
+
+| Module | Off means |
+| --- | --- |
+| `evidence` | no evidence gate on completion claims |
+| `planner` | no two-model planning turn |
+| `subagent` | no delegation to workers |
+| `retrieval` | no retrieval over the folded transcript |
+| `compaction` | no context folding |
+| `upstream` | a dependency edge orders its endpoints without delivering the answer |
+| `recall-search` | recall can read a given address but cannot search for one |
+
+The fold-index scale is a separate axis (`-fold-index`), not a module.
+
+## Skills
+
+Project skills live under `.reasonix/skills/<name>/SKILL.md`.
+
+| Skill | Use it to |
+| --- | --- |
+| `price-change` | record a vendor's price change in the price book |
@@ -0,0 +1,51 @@
+# Reasonix project memory
+
+This checkout is a trimmed snapshot of the Reasonix kernel: the billing,
+ablation and graph contracts and a handful of leaf utilities, plus one small
+command that drives them. The conventions below are the project's own.
+
+## Conventions
+
+- Go kernel under `internal/`; each package owns one concern. A package's long
+  explanation belongs in its `doc.go`, not spread across implementation files.
+- Judgements read structure, never wording: types, contracts, schemas. An
+  error a caller must tell apart carries an identity — a sentinel, a typed
+  code — never a sentence.
+- A metric is its definition, not its name. Before a number becomes a finding,
+  state what it counts, from which anchor, over which population, and what it
+  excludes.
+
+## Comments
+
+Default is none — the code is the truth. Write one only when the **why** is
+non-obvious: a hidden constraint, an invariant the type system cannot express,
+or an external-protocol quirk. A comment states the constraint that holds now;
+it does not narrate how the code got here. English, always.
+
+- Declaration doc: ≤5 lines. Package comment: ≤8 lines, or ≤40 in a `doc.go`.
+- Every other comment: ≤3 lines. Struct-field and trailing `//`: 1 line.
+- One responsibility per file; 800 lines is the ceiling.
+
+## Vendor rates
+
+Official list prices live in one place: `officialRates` in
+`internal/contract/pricing/rates.go`, oldest generation first, the last being
+what a model charges today. A price change is an **append, never an edit** —
+the superseded rate is what lets an installed config be recognised as holding
+one of ours and brought forward. Callers read these through
+`pricing.CurrentRate` and `pricing.SupersededRates` and restate none of them.
+
+`make pricecheck` compares that table against each vendor's own page. It needs
+the network, so it is not part of `make check`.
+
+## Before every commit
+
+```bash
+make check    # gofmt -l, go vet ./..., go test ./...
+```
+
+## Change discipline
+
+List callers, consumers of the same state and sibling features before editing.
+Fix at the owning layer; a fix that breaks a neighbouring behaviour is a failed
+fix. Write tests first; they must fail without the change.
@@ -0,0 +1,115 @@
+// Command benchctl prints what the pricing and ablation contracts answer for
+// one model or one benchmark arm, so a reviewer can check a rate or an arm name
+// without writing a test.
+package main
+
+import (
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+
+	"reasonix/internal/contract/ablation"
+	"reasonix/internal/contract/pricing"
+)
+
+var errUsage = errors.New("usage: benchctl rate|cost|tariff|arm [flags]")
+
+func main() {
+	if err := run(os.Args[1:], os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "benchctl:", err)
+		os.Exit(2)
+	}
+}
+
+func run(args []string, out io.Writer) error {
+	if len(args) == 0 {
+		return errUsage
+	}
+	switch args[0] {
+	case "rate":
+		return runRate(args[1:], out)
+	case "cost":
+		return runCost(args[1:], out)
+	case "tariff":
+		return runTariff(args[1:], out)
+	case "arm":
+		return runArm(args[1:], out)
+	default:
+		return fmt.Errorf("%w: unknown subcommand %q", errUsage, args[0])
+	}
+}
+
+func runRate(args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("rate", flag.ContinueOnError)
+	fs.SetOutput(out)
+	provider := fs.String("provider", "deepseek", "vendor")
+	model := fs.String("model", "deepseek-flash", "model id")
+	currency := fs.String("currency", "", "currency; empty reads the vendor's default")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	cur := *currency
+	if cur == "" {
+		cur = pricing.DefaultCurrency(*provider)
+	}
+	card := pricing.CurrentRate(*provider, *model, cur)
+	if card == nil {
+		return fmt.Errorf("no official rate for %s/%s in %s", *provider, *model, cur)
+	}
+	fmt.Fprintf(out, "%s/%s %s: cache-hit %g input %g output %g per 1M\n",
+		*provider, *model, card.Currency, card.CacheHit, card.Input, card.Output)
+	if entry, ok := pricing.LookupCatalog(*provider, *model, cur, ""); ok && entry.DocURL != "" {
+		fmt.Fprintf(out, "source: %s\n", entry.DocURL)
+	}
+	fmt.Fprintf(out, "superseded generations: %d\n", len(pricing.SupersededRates(*provider, *model, cur)))
+	return nil
+}
+
+func runCost(args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("cost", flag.ContinueOnError)
+	fs.SetOutput(out)
+	provider := fs.String("provider", "deepseek", "vendor")
+	model := fs.String("model", "deepseek-flash", "model id")
+	currency := fs.String("currency", "", "currency; empty reads the vendor's default")
+	hit := fs.Int("hit", 0, "cached prompt tokens")
+	miss := fs.Int("miss", 0, "uncached prompt tokens")
+	completion := fs.Int("completion", 0, "completion tokens")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	cur := *currency
+	if cur == "" {
+		cur = pricing.DefaultCurrency(*provider)
+	}
+	card := pricing.CurrentRate(*provider, *model, cur)
+	if card == nil {
+		return fmt.Errorf("no official rate for %s/%s in %s", *provider, *model, cur)
+	}
+	usage := pricing.UsageTokens{CacheHitTokens: *hit, CacheMissTokens: *miss, CompletionTokens: *completion}
+	amount := pricing.OriginalCostAmount(*card, usage)
+	fmt.Fprintf(out, "%s %s\n", amount, pricing.NormalizeCurrency(card.Currency))
+	return nil
+}
+
+func runArm(args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("arm", flag.ContinueOnError)
+	fs.SetOutput(out)
+	spec := fs.String("ablate", "", "comma-separated modules to switch off: "+ablation.ModuleList())
+	foldIndex := fs.String("fold-index", "", "fold-index scale: default, half, quarter or off")
+	list := fs.Bool("list", false, "list the switchable modules")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	if *list {
+		fmt.Fprintln(out, ablation.ModuleList())
+		return nil
+	}
+	set, err := ablation.ParseArm(*spec, *foldIndex)
+	if err != nil {
+		return err
+	}
+	fmt.Fprintln(out, set.Arm())
+	return nil
+}
@@ -0,0 +1,65 @@
+package main
+
+import (
+	"bytes"
+	"errors"
+	"strings"
+	"testing"
+)
+
+func runOut(t *testing.T, args ...string) string {
+	t.Helper()
+	var out bytes.Buffer
+	if err := run(args, &out); err != nil {
+		t.Fatalf("run %v: %v", args, err)
+	}
+	return out.String()
+}
+
+func TestRateNamesTheCurrentCard(t *testing.T) {
+	got := runOut(t, "rate", "-provider", "mimo", "-model", "mimo-v2.5")
+	if !strings.Contains(got, "mimo/mimo-v2.5 CNY: cache-hit 0.02 input 1 output 2 per 1M") {
+		t.Fatalf("rate output = %q", got)
+	}
+}
+
+func TestRateRefusesAnUnpricedModel(t *testing.T) {
+	var out bytes.Buffer
+	if err := run([]string{"rate", "-provider", "nobody", "-model", "x"}, &out); err == nil {
+		t.Fatal("an unpriced model must fail")
+	}
+}
+
+func TestCostChargesTheCurrentCard(t *testing.T) {
+	got := runOut(t, "cost", "-provider", "mimo", "-model", "mimo-v2.5", "-miss", "1000000", "-completion", "1000000")
+	if strings.TrimSpace(got) != "3 CNY" {
+		t.Fatalf("cost output = %q", got)
+	}
+}
+
+func TestArmNamesTheConfiguration(t *testing.T) {
+	if got := strings.TrimSpace(runOut(t, "arm")); got != "full" {
+		t.Fatalf("control arm = %q", got)
+	}
+	if got := strings.TrimSpace(runOut(t, "arm", "-ablate", "planner,evidence", "-fold-index", "half")); got != "no-evidence+no-planner+index-half" {
+		t.Fatalf("arm = %q", got)
+	}
+}
+
+func TestUnknownSubcommandIsAUsageError(t *testing.T) {
+	var out bytes.Buffer
+	if err := run([]string{"nope"}, &out); !errors.Is(err, errUsage) {
+		t.Fatalf("err = %v, want errUsage", err)
+	}
+}
+
+func TestTariffReadsTheVendorsSchedule(t *testing.T) {
+	got := runOut(t, "tariff", "-provider", "mimo", "-model", "mimo-v2.5")
+	if !strings.Contains(got, "official card: true") || !strings.Contains(got, "one rate around the clock") {
+		t.Fatalf("tariff output = %q", got)
+	}
+	peak := runOut(t, "tariff", "-currency", "CNY", "-at", "2026-10-12T02:00:00Z")
+	if !strings.Contains(peak, "peak=true until 2026-10-12T04:00:00Z") {
+		t.Fatalf("deepseek tariff at a weekday peak = %q", peak)
+	}
+}
@@ -0,0 +1,49 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"io"
+	"time"
+
+	"reasonix/internal/contract/pricing"
+)
+
+func runTariff(args []string, out io.Writer) error {
+	fs := flag.NewFlagSet("tariff", flag.ContinueOnError)
+	fs.SetOutput(out)
+	provider := fs.String("provider", "deepseek", "vendor")
+	model := fs.String("model", "deepseek-flash", "model id")
+	currency := fs.String("currency", "", "currency; empty reads the vendor's default")
+	at := fs.String("at", "", "instant to read the schedule at, RFC 3339; empty is now")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	when := time.Now()
+	if *at != "" {
+		t, err := time.Parse(time.RFC3339, *at)
+		if err != nil {
+			return fmt.Errorf("-at: %w", err)
+		}
+		when = t
+	}
+	cur := *currency
+	if cur == "" {
+		cur = pricing.DefaultCurrency(*provider)
+	}
+	card := pricing.CurrentRate(*provider, *model, cur)
+	if card == nil {
+		return fmt.Errorf("no official rate for %s/%s in %s", *provider, *model, cur)
+	}
+	fmt.Fprintf(out, "official card: %v\n", pricing.IsOfficialCard(*provider, *model, *card))
+	tariff, ok := pricing.LiveTariff(*provider, *model, *card, when)
+	switch {
+	case !ok:
+		fmt.Fprintln(out, "schedule: one rate around the clock")
+	case !tariff.Changes:
+		fmt.Fprintf(out, "schedule: peak=%v, no change ahead\n", tariff.Peak)
+	default:
+		fmt.Fprintf(out, "schedule: peak=%v until %s\n", tariff.Peak, tariff.ChangesAt.UTC().Format(time.RFC3339))
+	}
+	return nil
+}
@@ -0,0 +1,3 @@
+module reasonix
+
+go 1.26.0
@@ -0,0 +1,7 @@
+//go:build !windows
+
+package neterr
+
+import "syscall"
+
+var resetErrors = []error{syscall.ECONNRESET, syscall.ECONNABORTED, syscall.EPIPE}
@@ -0,0 +1,8 @@
+package neterr
+
+import "syscall"
+
+// syscall.ECONNRESET and friends exist on Windows only as APPLICATION_ERROR
+// placeholders, so errors.Is against them never matches a real socket failure.
+// Winsock's own numbering carries the identities the runtime returns.
+var resetErrors = []error{syscall.WSAECONNRESET, syscall.WSAECONNABORTED, syscall.ERROR_BROKEN_PIPE}
@@ -0,0 +1,47 @@
+// Package neterr answers what a transport error is from the identity the
+// operating system gave it, never from the sentence it rendered. A system
+// error's text arrives in the machine's own language and is reworded between
+// releases, so a word list that matches on an English host silently stops
+// matching elsewhere. The judgement lives here once because three packages
+// were each carrying their own copy of it.
+package neterr
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net"
+)
+
+// IsConnReset reports whether err is a connection-level drop (peer reset,
+// truncated body, closed socket) as opposed to a protocol or caller error. A
+// stream cut this way mid-body can be replayed from scratch, unlike a decode
+// or 4xx error. The common trigger is a local proxy (v2rayN/sing-box)
+// idle-closing a long-lived SSE connection during a reasoner's first-token gap.
+func IsConnReset(err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
+		return false
+	}
+	if errors.Is(err, io.ErrUnexpectedEOF) || errors.Is(err, io.EOF) ||
+		errors.Is(err, net.ErrClosed) || isAny(err, resetErrors) {
+		return true
+	}
+	var dnsErr *net.DNSError
+	if errors.As(err, &dnsErr) {
+		return false
+	}
+	var netErr net.Error
+	return errors.As(err, &netErr)
+}
+
+func isAny(err error, targets []error) bool {
+	for _, target := range targets {
+		if errors.Is(err, target) {
+			return true
+		}
+	}
+	return false
+}
@@ -0,0 +1,43 @@
+package neterr
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"testing"
+)
+
+func TestIsConnReset(t *testing.T) {
+	if IsConnReset(nil) {
+		t.Error("nil is not a conn reset")
+	}
+	if IsConnReset(context.Canceled) || IsConnReset(context.DeadlineExceeded) {
+		t.Error("ctx cancel/deadline must not look like a recoverable reset")
+	}
+	if IsConnReset(errors.New("decode stream: invalid character")) {
+		t.Error("a plain protocol error must not be treated as a conn reset")
+	}
+	for _, err := range []error{
+		io.ErrUnexpectedEOF,
+		&net.OpError{Op: "read", Err: resetErrors[0]},
+		fmt.Errorf("read stream: %w", &net.OpError{Op: "read", Err: errors.New("wsarecv: forcibly closed")}),
+	} {
+		if !IsConnReset(err) {
+			t.Errorf("want conn reset for %v", err)
+		}
+	}
+}
+
+func TestIsConnResetExcludesDNS(t *testing.T) {
+	for _, dns := range []*net.DNSError{
+		{Err: "no such host", Name: "api.deepseek.com", IsNotFound: true},
+		{Err: "i/o timeout", Name: "api.deepseek.com", IsTimeout: true, IsTemporary: true},
+	} {
+		err := fmt.Errorf("dial: %w", &net.OpError{Op: "dial", Err: dns})
+		if IsConnReset(err) {
+			t.Errorf("DNS failure %v is not a connection reset", dns)
+		}
+	}
+}
@@ -0,0 +1,17 @@
+package nilutil
+
+import "reflect"
+
+// IsNil reports whether v is nil or an interface holding a typed nil value.
+func IsNil(v any) bool {
+	if v == nil {
+		return true
+	}
+	rv := reflect.ValueOf(v)
+	switch rv.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
+		return rv.IsNil()
+	default:
+		return false
+	}
+}
@@ -0,0 +1,31 @@
+package nilutil
+
+import "testing"
+
+type sampleInterface interface {
+	Do()
+}
+
+type sampleImpl struct{}
+
+func (*sampleImpl) Do() {}
+
+func TestIsNilDetectsTypedNilInterface(t *testing.T) {
+	var p *sampleImpl
+	var i sampleInterface = p
+
+	if !IsNil(i) {
+		t.Fatal("IsNil should detect typed nil interface")
+	}
+}
+
+func TestIsNilRejectsConcreteValues(t *testing.T) {
+	var p sampleInterface = &sampleImpl{}
+
+	if IsNil(p) {
+		t.Fatal("IsNil should not reject a concrete interface value")
+	}
+	if IsNil("x") {
+		t.Fatal("IsNil should not reject non-nil scalar values")
+	}
+}
@@ -0,0 +1,218 @@
+package retrieval
+
+import (
+	"fmt"
+	"math"
+	"strings"
+	"unicode"
+	"unicode/utf8"
+)
+
+// Tokens lowercases Latin words and splits CJK runs into overlapping bigrams
+// (a lone CJK rune stays a single term) — the standard CJK indexing unit
+// (Lucene's CJKAnalyzer, SQLite FTS): a bigram only matches a real two-rune
+// subsequence where per-rune unigrams matched scattered common characters.
+// Intentionally a local, dependency-free approximation of FTS matching.
+func Tokens(s string) []string {
+	var out []string
+	var b strings.Builder
+	var prev rune
+	cjkRun := 0
+	flush := func() {
+		if b.Len() == 0 {
+			return
+		}
+		out = append(out, b.String())
+		b.Reset()
+	}
+	endCJK := func() {
+		if cjkRun == 1 {
+			out = append(out, string(prev))
+		}
+		cjkRun = 0
+	}
+	for _, r := range s {
+		switch {
+		case isCJK(r):
+			flush()
+			if cjkRun > 0 {
+				out = append(out, string([]rune{prev, r}))
+			}
+			prev = r
+			cjkRun++
+		case unicode.IsLetter(r) || unicode.IsDigit(r) || r == '_':
+			endCJK()
+			b.WriteRune(unicode.ToLower(r))
+		default:
+			flush()
+			endCJK()
+		}
+	}
+	flush()
+	endCJK()
+	return out
+}
+
+func isCJK(r rune) bool {
+	return unicode.In(r, unicode.Han, unicode.Hiragana, unicode.Katakana, unicode.Hangul)
+}
+
+// Unique returns terms in first-seen order.
+func Unique(in []string) []string {
+	seen := map[string]bool{}
+	out := make([]string, 0, len(in))
+	for _, s := range in {
+		if s == "" || seen[s] {
+			continue
+		}
+		seen[s] = true
+		out = append(out, s)
+	}
+	return out
+}
+
+// Counts returns a term-frequency map.
+func Counts(terms []string) map[string]int {
+	counts := map[string]int{}
+	for _, term := range terms {
+		counts[term]++
+	}
+	return counts
+}
+
+// BM25Score scores a document against query terms.
+func BM25Score(counts map[string]int, length int, queryTerms []string, df map[string]int, totalDocs int, avgLen float64) float64 {
+	const (
+		k1 = 1.2
+		b  = 0.75
+	)
+	if length <= 0 || totalDocs <= 0 {
+		return 0
+	}
+	if avgLen <= 0 {
+		avgLen = 1
+	}
+	var score float64
+	docLen := float64(length)
+	for _, term := range queryTerms {
+		tf := counts[term]
+		if tf == 0 {
+			continue
+		}
+		termDF := df[term]
+		if termDF == 0 {
+			continue
+		}
+		idf := math.Log(1 + (float64(totalDocs)-float64(termDF)+0.5)/(float64(termDF)+0.5))
+		freq := float64(tf)
+		score += idf * (freq * (k1 + 1)) / (freq + k1*(1-b+b*docLen/avgLen))
+	}
+	return score
+}
+
+// DocumentFrequency counts how many documents contain each term.
+func DocumentFrequency(docs []map[string]int) map[string]int {
+	df := map[string]int{}
+	for _, counts := range docs {
+		for term := range counts {
+			df[term]++
+		}
+	}
+	return df
+}
+
+// KeepTopRelativeScore keeps the best item and drops trailing items whose score
+// falls below ratio * topScore. Callers must pass items already sorted best
+// first. This mirrors SQLite FTS/BM25 search UIs that over-fetch, then trim
+// common-word-only noise without imposing an absolute score threshold.
+func KeepTopRelativeScore[T any](items []T, ratio float64, score func(T) float64) []T {
+	if len(items) == 0 || ratio <= 0 {
+		return items
+	}
+	top := score(items[0])
+	if top <= 0 {
+		return items
+	}
+	cutoff := top * ratio
+	out := items[:0]
+	for i, item := range items {
+		if i == 0 || score(item) >= cutoff {
+			out = append(out, item)
+		}
+	}
+	return out
+}
+
+// QueryTerms normalizes a search string and reports an error when nothing
+// searchable remains.
+func QueryTerms(query string) ([]string, error) {
+	terms := Unique(Tokens(strings.TrimSpace(query)))
+	if len(terms) == 0 {
+		return nil, fmt.Errorf("query must contain at least one letter or number")
+	}
+	return terms, nil
+}
+
+// MakeSnippet returns a whitespace-compacted excerpt centered near the query.
+func MakeSnippet(text, query string, terms []string, maxRunes int) string {
+	text = CompactWhitespace(text)
+	if maxRunes <= 0 || utf8.RuneCountInString(text) <= maxRunes {
+		return text
+	}
+	lower := strings.ToLower(text)
+	query = strings.ToLower(strings.TrimSpace(query))
+	idx := -1
+	if query != "" {
+		idx = strings.Index(lower, query)
+	}
+	if idx < 0 {
+		for _, term := range terms {
+			runes := []rune(term)
+			if len(runes) == 1 && !isCJK(runes[0]) {
+				continue
+			}
+			if i := strings.Index(lower, term); i >= 0 {
+				idx = i
+				break
+			}
+		}
+	}
+	if idx < 0 {
+		idx = 0
+	}
+	return snippetAround(text, idx, maxRunes)
+}
+
+func snippetAround(text string, byteIdx, maxRunes int) string {
+	if byteIdx < 0 {
+		byteIdx = 0
+	}
+	if byteIdx > len(text) {
+		byteIdx = len(text)
+	}
+	for byteIdx > 0 && byteIdx < len(text) && !utf8.RuneStart(text[byteIdx]) {
+		byteIdx--
+	}
+	runes := []rune(text)
+	pos := utf8.RuneCountInString(text[:byteIdx])
+	start := max(pos-maxRunes/2, 0)
+	end := start + maxRunes
+	if end > len(runes) {
+		end = len(runes)
+		start = max(end-maxRunes, 0)
+	}
+	prefix := ""
+	suffix := ""
+	if start > 0 {
+		prefix = "..."
+	}
+	if end < len(runes) {
+		suffix = "..."
+	}
+	return prefix + string(runes[start:end]) + suffix
+}
+
+// CompactWhitespace collapses runs of whitespace into one ASCII space.
+func CompactWhitespace(s string) string {
+	return strings.Join(strings.Fields(s), " ")
+}
@@ -0,0 +1,77 @@
+package retrieval
+
+import (
+	"strings"
+	"testing"
+	"unicode/utf8"
+)
+
+func TestTokensHandlesLatinAndCJK(t *testing.T) {
+	for _, tc := range []struct {
+		in   string
+		want []string
+	}{
+		{"BM25 检索 cache-first", []string{"bm25", "检索", "cache", "first"}},
+		{"数据库迁移", []string{"数据", "据库", "库迁", "迁移"}},
+		{"库", []string{"库"}},
+		{"用pnpm装依赖", []string{"用", "pnpm", "装依", "依赖"}},
+	} {
+		got := Tokens(tc.in)
+		if strings.Join(got, ",") != strings.Join(tc.want, ",") {
+			t.Fatalf("Tokens(%q) = %#v, want %#v", tc.in, got, tc.want)
+		}
+	}
+}
+
+func TestBM25ScoreRanksMatchingDocument(t *testing.T) {
+	query := Unique(Tokens("prompt cache"))
+	doc1 := Counts(Tokens("prompt cache cache stability"))
+	doc2 := Counts(Tokens("dashboard colors"))
+	df := DocumentFrequency([]map[string]int{doc1, doc2})
+	score1 := BM25Score(doc1, 4, query, df, 2, 3)
+	score2 := BM25Score(doc2, 2, query, df, 2, 3)
+	if score1 <= score2 {
+		t.Fatalf("matching score %.3f should exceed unrelated score %.3f", score1, score2)
+	}
+}
+
+func TestKeepTopRelativeScoreKeepsTopAndDropsWeakTail(t *testing.T) {
+	items := []struct {
+		name  string
+		score float64
+	}{
+		{name: "top", score: 10},
+		{name: "near", score: 2},
+		{name: "noise", score: 1.4},
+		{name: "zero", score: 0},
+	}
+	got := KeepTopRelativeScore(items, 0.15, func(item struct {
+		name  string
+		score float64
+	}) float64 {
+		return item.score
+	})
+	if len(got) != 2 || got[0].name != "top" || got[1].name != "near" {
+		t.Fatalf("KeepTopRelativeScore() = %#v, want top and near", got)
+	}
+}
+
+func TestMakeSnippetHandlesMultibyteBoundary(t *testing.T) {
+	text := strings.Repeat("前缀", 80) + "稳定结论 synthesis cache " + strings.Repeat("后缀", 80)
+	out := MakeSnippet(text, "synthesis cache", QueryTermsForTest(t, "synthesis cache"), 60)
+	if !strings.Contains(out, "synthesis cache") {
+		t.Fatalf("snippet missing query: %q", out)
+	}
+	if strings.ContainsRune(out, utf8.RuneError) {
+		t.Fatalf("snippet contains replacement rune: %q", out)
+	}
+}
+
+func QueryTermsForTest(t *testing.T, query string) []string {
+	t.Helper()
+	terms, err := QueryTerms(query)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return terms
+}
@@ -0,0 +1,176 @@
+// Retrieval V2, shadow-only: BM25F field weighting, code-symbol splitting,
+// and mixed CJK uni+bigrams. Nothing here serves the model — V2 rankings ride
+// the recall audit next to production's, and MemoryBench decides if V2 ever
+// takes over. Weights are candidates under measurement, not tuned truths.
+package retrieval
+
+import (
+	"math"
+	"strings"
+	"unicode"
+)
+
+// TokensV2 extends Tokens with code-symbol structure and CJK unigrams:
+// CamelCase and snake_case words also emit their segments (FooBar → foobar,
+// foo, bar), and CJK runs emit unigrams alongside bigrams so one-character
+// queries still match. The V1 form of every token is preserved, so V2 recall
+// is a superset of V1's vocabulary.
+func TokensV2(s string) []string {
+	var out []string
+	var word []rune
+	var prev rune
+	cjkRun := 0
+	flushWord := func() {
+		if len(word) == 0 {
+			return
+		}
+		lower := strings.ToLower(string(word))
+		out = append(out, lower)
+		for _, seg := range splitCodeSymbol(word) {
+			if seg != lower {
+				out = append(out, seg)
+			}
+		}
+		word = word[:0]
+	}
+	endCJK := func() { cjkRun = 0 }
+	for _, r := range s {
+		switch {
+		case isCJK(r):
+			flushWord()
+			out = append(out, string(r))
+			if cjkRun > 0 {
+				out = append(out, string([]rune{prev, r}))
+			}
+			prev = r
+			cjkRun++
+		case unicode.IsLetter(r) || unicode.IsDigit(r) || r == '_':
+			endCJK()
+			word = append(word, r)
+		default:
+			flushWord()
+			endCJK()
+		}
+	}
+	flushWord()
+	return out
+}
+
+// splitCodeSymbol yields the lowercase segments of a code identifier:
+// CamelCase humps, snake_case parts, and letter/digit boundaries.
+func splitCodeSymbol(word []rune) []string {
+	var segments []string
+	var seg []rune
+	flush := func() {
+		if len(seg) > 1 { // single letters are noise, not signal
+			segments = append(segments, strings.ToLower(string(seg)))
+		}
+		seg = seg[:0]
+	}
+	for i, r := range word {
+		boundary := r == '_' ||
+			(i > 0 && unicode.IsUpper(r) && !unicode.IsUpper(word[i-1])) ||
+			(i > 0 && unicode.IsDigit(r) != unicode.IsDigit(word[i-1]))
+		if boundary {
+			flush()
+		}
+		if r != '_' {
+			seg = append(seg, r)
+		}
+	}
+	flush()
+	if len(segments) < 2 {
+		return nil // no structure worth indexing beyond the whole word
+	}
+	return segments
+}
+
+// FieldedDoc is one document split into weighted fields for BM25F.
+type FieldedDoc struct {
+	ID     string
+	Fields map[string]string
+}
+
+// v2FieldWeights follow the BM25F intuition: identity fields say what a fact
+// IS, the body says everything it mentions. Candidates under measurement.
+var v2FieldWeights = map[string]float64{
+	"name": 2.5, "title": 2.5, "keywords": 2.0, "subject": 2.0,
+	"description": 1.5, "body": 1.0,
+}
+
+// V2Hit is one shadow-ranked document.
+type V2Hit struct {
+	ID    string
+	Score float64
+}
+
+// RankV2 scores docs against a query with BM25F over TokensV2: term
+// frequencies accumulate per field scaled by field weight, then the standard
+// saturation applies once per term (the F in BM25F), with length
+// normalization over the weighted document length.
+func RankV2(query string, docs []FieldedDoc) []V2Hit {
+	queryTerms := Unique(TokensV2(query))
+	if len(queryTerms) == 0 || len(docs) == 0 {
+		return nil
+	}
+	type indexed struct {
+		id     string
+		tf     map[string]float64
+		length float64
+	}
+	corpus := make([]indexed, 0, len(docs))
+	df := map[string]int{}
+	var totalLen float64
+	for _, doc := range docs {
+		ix := indexed{id: doc.ID, tf: map[string]float64{}}
+		seen := map[string]bool{}
+		for field, text := range doc.Fields {
+			weight, ok := v2FieldWeights[field]
+			if !ok {
+				weight = 1.0
+			}
+			for _, term := range TokensV2(text) {
+				ix.tf[term] += weight
+				ix.length += weight
+				seen[term] = true
+			}
+		}
+		for term := range seen {
+			df[term]++
+		}
+		totalLen += ix.length
+		corpus = append(corpus, ix)
+	}
+	avgLen := totalLen / float64(len(corpus))
+	if avgLen <= 0 {
+		avgLen = 1
+	}
+	const k1, b = 1.2, 0.75
+	var hits []V2Hit
+	for _, doc := range corpus {
+		var score float64
+		for _, term := range queryTerms {
+			tf := doc.tf[term]
+			if tf == 0 || df[term] == 0 {
+				continue
+			}
+			idf := math.Log(1 + (float64(len(corpus))-float64(df[term])+0.5)/(float64(df[term])+0.5))
+			score += idf * (tf * (k1 + 1)) / (tf + k1*(1-b+b*doc.length/avgLen))
+		}
+		if score > 0 {
+			hits = append(hits, V2Hit{ID: doc.id, Score: score})
+		}
+	}
+	SortHitsDesc(hits)
+	return hits
+}
+
+// SortHitsDesc orders shadow hits best-first with a stable ID tiebreak.
+func SortHitsDesc(hits []V2Hit) {
+	for i := 1; i < len(hits); i++ {
+		for j := i; j > 0 && (hits[j].Score > hits[j-1].Score ||
+			(hits[j].Score == hits[j-1].Score && hits[j].ID < hits[j-1].ID)); j-- {
+			hits[j], hits[j-1] = hits[j-1], hits[j]
+		}
+	}
+}
@@ -0,0 +1,47 @@
+package retrieval
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestTokensV2CodeSymbolsAndCJK(t *testing.T) {
+	got := strings.Join(TokensV2("RetryPolicy.MaxBackoffMs ticket_1827 数据库"), " ")
+	for _, want := range []string{"retrypolicy", "retry", "policy", "maxbackoffms", "max", "backoff", "ticket_1827", "ticket", "1827", "数", "据", "库", "数据", "据库"} {
+		if !strings.Contains(" "+got+" ", " "+want+" ") {
+			t.Fatalf("TokensV2 missing %q in %q", want, got)
+		}
+	}
+	if strings.Contains(" "+got+" ", " ms ") {
+		// "Ms" splits to a single meaningful segment only when len > 1; "ms" is
+		// fine — assert single letters never appear instead.
+		t.Log("ms segment present (acceptable)")
+	}
+	for _, tok := range TokensV2("A B C") {
+		if len(tok) == 0 {
+			t.Fatal("empty token emitted")
+		}
+	}
+}
+
+func TestRankV2FieldWeightsBeatBodyMentions(t *testing.T) {
+	docs := []FieldedDoc{
+		{ID: "titled", Fields: map[string]string{"title": "Package manager", "body": "We migrated to pnpm."}},
+		{ID: "mention", Fields: map[string]string{"title": "Sprint notes", "body": "Someone asked about the package manager once; also weather, lunch, and a package of stickers."}},
+	}
+	hits := RankV2("package manager", docs)
+	if len(hits) != 2 || hits[0].ID != "titled" {
+		t.Fatalf("field-weighted doc must outrank body mentions: %+v", hits)
+	}
+}
+
+func TestRankV2FindsCodeSymbolBySegment(t *testing.T) {
+	docs := []FieldedDoc{
+		{ID: "sym", Fields: map[string]string{"body": "Configure RetryPolicy.MaxBackoffMs in policy/retry.toml."}},
+		{ID: "other", Fields: map[string]string{"body": "Unrelated fact about deploys."}},
+	}
+	hits := RankV2("max backoff configuration", docs)
+	if len(hits) == 0 || hits[0].ID != "sym" {
+		t.Fatalf("segment query must find the camel-case symbol: %+v", hits)
+	}
+}
@@ -0,0 +1,7 @@
+// Package rulelist splits a list of permission rules written on one line.
+//
+// Rules are separated by commas or whitespace, and a separator inside
+// parentheses belongs to the rule: `Bash(git add:*) Read` is two rules. Skill
+// front matter and the --allowed-tools flag share it, so one spelling means
+// one thing in both.
+package rulelist
@@ -0,0 +1,56 @@
+package rulelist
+
+import (
+	"errors"
+	"strings"
+	"unicode"
+)
+
+var (
+	// ErrUnclosed: an opening parenthesis is never closed.
+	ErrUnclosed = errors.New("unclosed '('")
+	// ErrUnexpectedClose: a closing parenthesis has no opening one.
+	ErrUnexpectedClose = errors.New("unexpected ')'")
+)
+
+// Split returns the rules in value, in order, trimmed and non-empty.
+func Split(value string) ([]string, error) {
+	var rules []string
+	start, depth := -1, 0
+	flush := func(end int) {
+		if start < 0 {
+			return
+		}
+		if rule := strings.TrimSpace(value[start:end]); rule != "" {
+			rules = append(rules, rule)
+		}
+		start = -1
+	}
+	for i, r := range value {
+		switch r {
+		case '(':
+			if start < 0 {
+				start = i
+			}
+			depth++
+		case ')':
+			if depth == 0 {
+				return nil, ErrUnexpectedClose
+			}
+			depth--
+		default:
+			if depth == 0 && (r == ',' || unicode.IsSpace(r)) {
+				flush(i)
+				continue
+			}
+			if start < 0 {
+				start = i
+			}
+		}
+	}
+	if depth != 0 {
+		return nil, ErrUnclosed
+	}
+	flush(len(value))
+	return rules, nil
+}
@@ -0,0 +1,40 @@
+package rulelist
+
+import (
+	"errors"
+	"reflect"
+	"testing"
+)
+
+func TestSplitSeparatesOnCommasAndWhitespaceOutsideParentheses(t *testing.T) {
+	for _, tc := range []struct {
+		in   string
+		want []string
+	}{
+		{"", nil},
+		{"   ", nil},
+		{"Read", []string{"Read"}},
+		{"read_file, grep,bash", []string{"read_file", "grep", "bash"}},
+		{"Read Grep  Bash", []string{"Read", "Grep", "Bash"}},
+		{"Bash(git add:*) Read", []string{"Bash(git add:*)", "Read"}},
+		{"Bash(git add:*, git commit:*), Read", []string{"Bash(git add:*, git commit:*)", "Read"}},
+		{"bash,", []string{"bash"}},
+	} {
+		got, err := Split(tc.in)
+		if err != nil {
+			t.Fatalf("Split(%q): %v", tc.in, err)
+		}
+		if !reflect.DeepEqual(got, tc.want) {
+			t.Errorf("Split(%q) = %q, want %q", tc.in, got, tc.want)
+		}
+	}
+}
+
+func TestSplitReportsUnbalancedParenthesesByIdentity(t *testing.T) {
+	if _, err := Split("Bash(git add"); !errors.Is(err, ErrUnclosed) {
+		t.Errorf("unclosed = %v", err)
+	}
+	if _, err := Split("Bash)"); !errors.Is(err, ErrUnexpectedClose) {
+		t.Errorf("unexpected close = %v", err)
+	}
+}
@@ -0,0 +1,25 @@
+// Package tokencount estimates how many tokens a string costs a model, without
+// carrying a tokenizer. Anything that has to size text before a provider counts
+// it — a cache-shape diagnostic, a tool call's context footprint — needs one
+// answer to that question rather than a private heuristic per caller.
+package tokencount
+
+import "unicode/utf8"
+
+// Text estimates the token count of s. The split is by script because the two
+// behave nothing alike — Latin text and code trend near four bytes per token,
+// CJK closer to one token per character — and either rule applied to the whole
+// string is wrong by ~4x on the other half. A real tokenizer would be exact and
+// would mean a vocabulary per model, re-run over whole transcripts every turn.
+func Text(s string) int {
+	narrow, wide := 0, 0
+	for _, r := range s {
+		if r < utf8.RuneSelf {
+			narrow++
+			continue
+		}
+		wide++
+	}
+	// Round up: a long run of short strings must not sum to nothing.
+	return (narrow+3)/4 + wide
+}
@@ -0,0 +1,27 @@
+package tokencount
+
+import "testing"
+
+func TestTextDoesNotUndercountCJK(t *testing.T) {
+	// The reason this package exists: bytes/4 reads a Chinese transcript as a
+	// third of its real size, so a planner sizing context off it compacts late.
+	const cjk = "把这个仓库跑一遍测试，把失败的那几个定位到具体文件"
+	runes := len([]rune(cjk))
+	if got := Text(cjk); got != runes {
+		t.Fatalf("Text(cjk) = %d, want one token per rune (%d)", got, runes)
+	}
+	if byBytes := len(cjk) / 4; Text(cjk) <= byBytes {
+		t.Fatalf("Text(cjk) = %d, must exceed the bytes/4 reading (%d)", Text(cjk), byBytes)
+	}
+}
+
+func TestTextRoundsASCIIUpAndKeepsEmptyFree(t *testing.T) {
+	if got := Text(""); got != 0 {
+		t.Fatalf("Text(\"\") = %d, want 0", got)
+	}
+	// Five bytes is more than one token's worth; truncating would let a long
+	// run of short strings sum to nothing.
+	if got := Text("abcde"); got != 2 {
+		t.Fatalf("Text(\"abcde\") = %d, want 2", got)
+	}
+}
@@ -0,0 +1,200 @@
+// Package ablation switches individual Reasonix subsystems off so a benchmark
+// can attribute a change in solve rate to one of them.
+package ablation
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+)
+
+type Module string
+
+const (
+	Evidence   Module = "evidence"
+	Planner    Module = "planner"
+	Subagent   Module = "subagent"
+	Retrieval  Module = "retrieval"
+	Compaction Module = "compaction"
+	// Upstream off means a fleet dependency edge orders its endpoints without
+	// delivering the dependency's answer, so a dependent must re-derive it.
+	Upstream Module = "upstream"
+	// RecallSearch off leaves recall able to read an address it was given and
+	// unable to look one up, which is what the tool could do before the folded
+	// region became searchable.
+	RecallSearch Module = "recall-search"
+)
+
+// FoldIndexScale sizes the model-visible fold index against its shipped budget.
+// It is a bench axis, not a module: the question it answers is what an ambient
+// address list is worth, and four steps answer that where a free-form fraction
+// would turn a measurement into a tuning knob.
+type FoldIndexScale string
+
+const (
+	FoldIndexDefault FoldIndexScale = ""
+	FoldIndexHalf    FoldIndexScale = "half"
+	FoldIndexQuarter FoldIndexScale = "quarter"
+	FoldIndexOff     FoldIndexScale = "off"
+)
+
+// Ratio scales a budget. The default returns it unchanged.
+func (f FoldIndexScale) Ratio() float64 {
+	switch f {
+	case FoldIndexHalf:
+		return 0.5
+	case FoldIndexQuarter:
+		return 0.25
+	case FoldIndexOff:
+		return 0
+	default:
+		return 1
+	}
+}
+
+// ParseFoldIndexScale reads a bench flag value. "" and "default" ship as-is.
+func ParseFoldIndexScale(spec string) (FoldIndexScale, error) {
+	switch strings.ToLower(strings.TrimSpace(spec)) {
+	case "", "default", "full":
+		return FoldIndexDefault, nil
+	case string(FoldIndexHalf):
+		return FoldIndexHalf, nil
+	case string(FoldIndexQuarter):
+		return FoldIndexQuarter, nil
+	case string(FoldIndexOff), "none", "0":
+		return FoldIndexOff, nil
+	default:
+		return "", fmt.Errorf("unknown fold-index scale %q (want default, half, quarter, or off)", spec)
+	}
+}
+
+// Modules returns every switchable module in the order arm names use.
+func Modules() []Module {
+	return []Module{Evidence, Planner, Subagent, Retrieval, Compaction, Upstream, RecallSearch}
+}
+
+// Set is the group of modules disabled for a run. The zero value is the
+// control arm: everything on.
+type Set struct {
+	off map[Module]bool
+	// foldIndex is an axis rather than a switch, so it lives beside the module
+	// set instead of inside it. It still reaches Arm(): a run whose index was
+	// quartered must not report the same identity as the control.
+	foldIndex FoldIndexScale
+}
+
+// WithFoldIndex returns this set at the given index scale.
+func (s Set) WithFoldIndex(scale FoldIndexScale) Set {
+	s.foldIndex = scale
+	return s
+}
+
+// FoldIndex is the scale this run sizes its fold index at.
+func (s Set) FoldIndex() FoldIndexScale { return s.foldIndex }
+
+// Parse reads a spec such as "evidence,planner". "" and "none" mean the control
+// arm; "all" disables every module.
+func Parse(spec string) (Set, error) {
+	spec = strings.TrimSpace(spec)
+	if spec == "" || strings.EqualFold(spec, "none") {
+		return Set{}, nil
+	}
+	if strings.EqualFold(spec, "all") {
+		return New(Modules()...), nil
+	}
+	known := map[Module]bool{}
+	for _, m := range Modules() {
+		known[m] = true
+	}
+	var mods []Module
+	for _, field := range strings.FieldsFunc(spec, func(r rune) bool { return r == ',' || r == ' ' }) {
+		m := Module(strings.ToLower(strings.TrimSpace(field)))
+		if !known[m] {
+			return Set{}, fmt.Errorf("unknown ablation module %q (want %s, or none/all)", field, ModuleList())
+		}
+		mods = append(mods, m)
+	}
+	return New(mods...), nil
+}
+
+// ParseArm reads both bench axes at once: the module spec and the fold-index
+// scale. One call so a frontend cannot wire the first and forget the second,
+// which would silently run an index arm under the control arm's name.
+func ParseArm(modules, foldIndex string) (Set, error) {
+	set, err := Parse(modules)
+	if err != nil {
+		return Set{}, err
+	}
+	scale, err := ParseFoldIndexScale(foldIndex)
+	if err != nil {
+		return Set{}, err
+	}
+	return set.WithFoldIndex(scale), nil
+}
+
+// ModuleList names every switchable module for flag help and error text, so
+// those cannot drift from Modules() the way a hand-kept list does.
+func ModuleList() string { return joinModules(Modules(), ", ") }
+
+// New returns a Set with the given modules disabled.
+func New(mods ...Module) Set {
+	if len(mods) == 0 {
+		return Set{}
+	}
+	off := make(map[Module]bool, len(mods))
+	for _, m := range mods {
+		off[m] = true
+	}
+	return Set{off: off}
+}
+
+func (s Set) Off(m Module) bool { return s.off[m] }
+
+func (s Set) Empty() bool { return len(s.off) == 0 && s.foldIndex == FoldIndexDefault }
+
+// Arm is the published name of this configuration: "full" for the control arm,
+// otherwise "no-evidence+no-planner". Stable across runs so results from
+// different machines group by the same key.
+func (s Set) Arm() string {
+	if s.Empty() {
+		return "full"
+	}
+	parts := make([]string, 0, len(s.off)+1)
+	for _, m := range s.disabled() {
+		parts = append(parts, "no-"+string(m))
+	}
+	if s.foldIndex != FoldIndexDefault {
+		parts = append(parts, "index-"+string(s.foldIndex))
+	}
+	return strings.Join(parts, "+")
+}
+
+// String round-trips back through Parse. It carries modules only — the fold
+// index axis has its own flag and its own parser.
+func (s Set) String() string {
+	if s.Empty() {
+		return "none"
+	}
+	return joinModules(s.disabled(), ",")
+}
+
+func (s Set) disabled() []Module {
+	order := map[Module]int{}
+	for i, m := range Modules() {
+		order[m] = i
+	}
+	out := make([]Module, 0, len(s.off))
+	for m := range s.off {
+		out = append(out, m)
+	}
+	sort.Slice(out, func(i, j int) bool { return order[out[i]] < order[out[j]] })
+	return out
+}
+
+func joinModules(mods []Module, sep string) string {
+	parts := make([]string, len(mods))
+	for i, m := range mods {
+		parts[i] = string(m)
+	}
+	return strings.Join(parts, sep)
+}
@@ -0,0 +1,108 @@
+package ablation
+
+import "testing"
+
+func TestParseAcceptsSpecFormsAndRejectsUnknownModules(t *testing.T) {
+	for _, tc := range []struct {
+		spec string
+		arm  string
+	}{
+		{"", "full"},
+		{"none", "full"},
+		{"NONE", "full"},
+		{"evidence", "no-evidence"},
+		{"planner,evidence", "no-evidence+no-planner"},
+		{"planner evidence", "no-evidence+no-planner"},
+		{" Evidence , Retrieval ", "no-evidence+no-retrieval"},
+		{"all", "no-evidence+no-planner+no-subagent+no-retrieval+no-compaction+no-upstream+no-recall-search"},
+	} {
+		set, err := Parse(tc.spec)
+		if err != nil {
+			t.Fatalf("Parse(%q): %v", tc.spec, err)
+		}
+		if got := set.Arm(); got != tc.arm {
+			t.Errorf("Parse(%q).Arm() = %q, want %q", tc.spec, got, tc.arm)
+		}
+	}
+
+	if _, err := Parse("evidence,planer"); err == nil {
+		t.Fatal("a misspelled module must fail loudly, not silently run the control arm")
+	}
+}
+
+func TestArmNameIsIndependentOfSpecOrder(t *testing.T) {
+	a, _ := Parse("retrieval,evidence,planner")
+	b, _ := Parse("planner,retrieval,evidence")
+	if a.Arm() != b.Arm() {
+		t.Fatalf("arm names diverge by input order: %q vs %q", a.Arm(), b.Arm())
+	}
+}
+
+func TestStringRoundTripsThroughParse(t *testing.T) {
+	for _, spec := range []string{"none", "evidence", "evidence,compaction", "all"} {
+		set, err := Parse(spec)
+		if err != nil {
+			t.Fatalf("Parse(%q): %v", spec, err)
+		}
+		again, err := Parse(set.String())
+		if err != nil {
+			t.Fatalf("Parse(%q): %v", set.String(), err)
+		}
+		if again.Arm() != set.Arm() {
+			t.Errorf("%q round-tripped to %q", set.Arm(), again.Arm())
+		}
+	}
+}
+
+// The index axis is not a module, but a run that moved it is not the control
+// arm either: results keyed by arm name would otherwise merge with it.
+func TestFoldIndexScaleNamesItsOwnArm(t *testing.T) {
+	var s Set
+	if got := s.WithFoldIndex(FoldIndexQuarter).Arm(); got != "index-quarter" {
+		t.Errorf("Arm() = %q, want index-quarter", got)
+	}
+	if got := New(Evidence).WithFoldIndex(FoldIndexOff).Arm(); got != "no-evidence+index-off" {
+		t.Errorf("Arm() = %q, want no-evidence+index-off", got)
+	}
+	if s.WithFoldIndex(FoldIndexQuarter).Empty() {
+		t.Error("a quartered index reported itself as the control arm")
+	}
+	if !s.WithFoldIndex(FoldIndexDefault).Empty() {
+		t.Error("the default scale is the control arm")
+	}
+}
+
+func TestFoldIndexScaleRatios(t *testing.T) {
+	for _, tc := range []struct {
+		spec  string
+		scale FoldIndexScale
+		ratio float64
+	}{
+		{"", FoldIndexDefault, 1}, {"default", FoldIndexDefault, 1},
+		{"half", FoldIndexHalf, 0.5}, {"QUARTER", FoldIndexQuarter, 0.25},
+		{"off", FoldIndexOff, 0}, {"0", FoldIndexOff, 0},
+	} {
+		got, err := ParseFoldIndexScale(tc.spec)
+		if err != nil {
+			t.Fatalf("ParseFoldIndexScale(%q): %v", tc.spec, err)
+		}
+		if got != tc.scale || got.Ratio() != tc.ratio {
+			t.Errorf("ParseFoldIndexScale(%q) = %q (ratio %v), want %q (%v)", tc.spec, got, got.Ratio(), tc.scale, tc.ratio)
+		}
+	}
+	if _, err := ParseFoldIndexScale("0.37"); err == nil {
+		t.Fatal("a free-form fraction was accepted; the axis is four steps on purpose")
+	}
+}
+
+func TestZeroValueIsTheControlArm(t *testing.T) {
+	var s Set
+	if !s.Empty() || s.Arm() != "full" {
+		t.Fatalf("zero Set = %q, want the full control arm", s.Arm())
+	}
+	for _, m := range Modules() {
+		if s.Off(m) {
+			t.Errorf("zero Set disabled %s", m)
+		}
+	}
+}
@@ -0,0 +1,15 @@
+// Package agentgraph is the vocabulary of one run's execution graph: the nodes
+// a turn handed work to, and the typed edges between them.
+//
+// It exists because that structure was being re-derived in five places and
+// survived in none. A fleet's dependency DAG died with the call that built it,
+// the persisted sidecar recorded a parent link and nothing else, and the event
+// stream implied edges through id prefixes. A reader asking why a node waited
+// could not tell an unmet dependency from a delivered answer, because neither
+// had ever been written down as anything a reader could tell apart.
+//
+// Nothing here knows what an agent, a tool, or a provider is. A producer
+// publishes a Delta of what it has just proven; every consumer folds deltas
+// with the same Apply, so the graph a headless run reports is the graph the
+// desktop draws.
+package agentgraph
@@ -0,0 +1,219 @@
+package agentgraph
+
+import "slices"
+
+// NodeKind separates the three things a node can be. A group is the call that
+// owns a fan-out, a worker is one delegated run, and an external node is work
+// this run did not do — named only because an edge points at it.
+type NodeKind string
+
+const (
+	KindGroup    NodeKind = "group"
+	KindWorker   NodeKind = "worker"
+	KindExternal NodeKind = "external"
+)
+
+// NodeState is where one node stands. It is the node's own lifecycle and not a
+// tool call's: an adopted node never ran and still holds an answer, and a
+// skipped one never started because something upstream did not finish.
+type NodeState string
+
+const (
+	StatePending NodeState = "pending"
+	// StateQueued is ready and waiting for a session concurrency slot. It is
+	// not StatePending: nothing upstream is missing, and the only thing between
+	// this node and its first step is the scheduler's ceiling.
+	StateQueued    NodeState = "queued"
+	StateRunning   NodeState = "running"
+	StateCompleted NodeState = "completed"
+	StateAdopted   NodeState = "adopted"
+	StateFailed    NodeState = "failed"
+	StateCancelled NodeState = "cancelled"
+	StateSkipped   NodeState = "skipped"
+)
+
+// Answered reports whether this state holds a final answer a dependent may
+// start from: one the node produced, or one adopted in its place.
+func (s NodeState) Answered() bool { return s == StateCompleted || s == StateAdopted }
+
+// Terminal reports whether the node will not change state again.
+func (s NodeState) Terminal() bool {
+	return s != StatePending && s != StateQueued && s != StateRunning
+}
+
+// Grant is what a node was allowed to touch while it ran. Empty means the
+// question does not apply — a group is not a run, and an adopted node never got
+// one — which a bool could not say apart from "may write".
+type Grant string
+
+const (
+	GrantRead  Grant = "read"
+	GrantWrite Grant = "write"
+)
+
+// WaitCause is why a queued node is not running. Queued says a node is ready and
+// held back; it does not say by what, and the answers have different remedies —
+// two are session settings and the third is a path or an edge.
+type WaitCause string
+
+const (
+	// WaitSlots is the session's total sub-agent ceiling.
+	WaitSlots WaitCause = "slots"
+	// WaitWriters is the session's concurrent-writer ceiling, which binds a
+	// writer while total capacity is still free.
+	WaitWriters WaitCause = "writers"
+	// WaitClaim is a write path someone else already holds. No ceiling change
+	// releases it: only disjoint paths, or an edge that orders the two.
+	WaitClaim WaitCause = "claim"
+)
+
+// EdgeKind is what one edge means. The node pair alone says nothing: waiting
+// for an answer and receiving one are separate facts, and an arm that orders
+// two nodes while delivering nothing between them is the case a single edge
+// type cannot describe.
+type EdgeKind string
+
+const (
+	// Spawn is structural: To was created by From.
+	Spawn EdgeKind = "spawn"
+	// Depends orders: To may not start until From has answered.
+	Depends EdgeKind = "depends"
+	// Context carries: From's answer opened To's run.
+	Context EdgeKind = "context"
+	// Adopt reuses: From's existing answer stood in for running To, which
+	// therefore cost nothing. From is usually outside this graph.
+	Adopt EdgeKind = "adopt"
+)
+
+// Node is one participant in a run. Zero fields mean "not learned yet", which
+// is what lets a producer report an outcome without restating the identity it
+// declared when the node entered the graph.
+type Node struct {
+	ID       string    `json:"id"`
+	ParentID string    `json:"parentId,omitempty"`
+	Kind     NodeKind  `json:"kind,omitempty"`
+	State    NodeState `json:"state,omitempty"`
+	Label    string    `json:"label,omitempty"`
+	Profile  string    `json:"profile,omitempty"`
+	Model    string    `json:"model,omitempty"`
+	Effort   string    `json:"effort,omitempty"`
+	Grant    Grant     `json:"grant,omitempty"`
+	// Wait is what held this node out of a slot. Like the stamps it survives the
+	// run starting: the state says it is running now, this says what it waited on.
+	Wait WaitCause `json:"wait,omitempty"`
+	// Ref is the persisted transcript this node's answer reads back from.
+	Ref string `json:"ref,omitempty"`
+	// QueuedAt, StartedAt and EndedAt are unix milliseconds, zero while unknown.
+	// QueuedAt to StartedAt is slot wait, which only the scheduler can measure.
+	QueuedAt  int64  `json:"queuedAt,omitempty"`
+	StartedAt int64  `json:"startedAt,omitempty"`
+	EndedAt   int64  `json:"endedAt,omitempty"`
+	Err       string `json:"err,omitempty"`
+}
+
+// Edge is one typed relation between two node ids. From may name a node outside
+// this graph: an adopted answer's source is work some earlier run did.
+type Edge struct {
+	From string   `json:"from"`
+	To   string   `json:"to"`
+	Kind EdgeKind `json:"kind"`
+}
+
+// Delta is one publication of what a producer has just proven. It is additive:
+// a node named again updates the one already there rather than forking into a
+// second, and a repeated edge is the same edge.
+type Delta struct {
+	Nodes []Node `json:"nodes,omitempty"`
+	Edges []Edge `json:"edges,omitempty"`
+}
+
+// Empty reports whether this delta carries nothing worth publishing.
+func (d Delta) Empty() bool { return len(d.Nodes) == 0 && len(d.Edges) == 0 }
+
+// Graph is the folded result. Nodes and edges keep first-seen order so two
+// consumers fed the same deltas draw the same picture. Lookups scan rather than
+// index: a graph is bounded by one call's fan-out, and a map would have to be
+// rebuilt every time the value crossed a wire.
+type Graph struct {
+	Nodes []Node `json:"nodes,omitempty"`
+	Edges []Edge `json:"edges,omitempty"`
+}
+
+// Apply folds one delta into the graph.
+func (g *Graph) Apply(d Delta) {
+	for _, n := range d.Nodes {
+		g.upsert(n)
+	}
+	for _, e := range d.Edges {
+		g.link(e)
+	}
+}
+
+// Node returns the node with this id.
+func (g *Graph) Node(id string) (Node, bool) {
+	if i := g.indexOf(id); i >= 0 {
+		return g.Nodes[i], true
+	}
+	return Node{}, false
+}
+
+func (g *Graph) indexOf(id string) int {
+	return slices.IndexFunc(g.Nodes, func(n Node) bool { return n.ID == id })
+}
+
+func (g *Graph) upsert(n Node) {
+	if n.ID == "" {
+		return
+	}
+	if i := g.indexOf(n.ID); i >= 0 {
+		g.Nodes[i] = merge(g.Nodes[i], n)
+		return
+	}
+	g.Nodes = append(g.Nodes, n)
+}
+
+// merge keeps what the graph already knew wherever the update says nothing, so
+// an outcome-only update cannot blank the identity an earlier delta declared.
+func merge(old, update Node) Node {
+	out := update
+	out.ParentID = orText(update.ParentID, old.ParentID)
+	out.Kind = NodeKind(orText(string(update.Kind), string(old.Kind)))
+	out.State = NodeState(orText(string(update.State), string(old.State)))
+	out.Label = orText(update.Label, old.Label)
+	out.Profile = orText(update.Profile, old.Profile)
+	out.Model = orText(update.Model, old.Model)
+	out.Effort = orText(update.Effort, old.Effort)
+	out.Ref = orText(update.Ref, old.Ref)
+	out.Err = orText(update.Err, old.Err)
+	out.Grant = Grant(orText(string(update.Grant), string(old.Grant)))
+	out.Wait = WaitCause(orText(string(update.Wait), string(old.Wait)))
+	out.QueuedAt = orStamp(update.QueuedAt, old.QueuedAt)
+	out.StartedAt = orStamp(update.StartedAt, old.StartedAt)
+	out.EndedAt = orStamp(update.EndedAt, old.EndedAt)
+	return out
+}
+
+// link adds an edge once. A self-edge or a half-named one is a producer bug the
+// graph refuses to record rather than render as a loop nothing can explain.
+func (g *Graph) link(e Edge) {
+	if e.From == "" || e.To == "" || e.Kind == "" || e.From == e.To {
+		return
+	}
+	if !slices.Contains(g.Edges, e) {
+		g.Edges = append(g.Edges, e)
+	}
+}
+
+func orText(update, old string) string {
+	if update != "" {
+		return update
+	}
+	return old
+}
+
+func orStamp(update, old int64) int64 {
+	if update != 0 {
+		return update
+	}
+	return old
+}
@@ -0,0 +1,153 @@
+package agentgraph
+
+import (
+	"encoding/json"
+	"slices"
+	"testing"
+)
+
+func TestApplyUpsertsNodesByID(t *testing.T) {
+	var g Graph
+	g.Apply(Delta{Nodes: []Node{
+		{ID: "a", Kind: KindWorker, State: StatePending, Label: "research", Profile: "explore", Grant: GrantRead},
+	}})
+	// An outcome-only update is what a producer sends once the node settles.
+	g.Apply(Delta{Nodes: []Node{{ID: "a", State: StateCompleted, Ref: "sub-1", EndedAt: 42}}})
+
+	if len(g.Nodes) != 1 {
+		t.Fatalf("nodes = %d, want 1 (the update forked the node)", len(g.Nodes))
+	}
+	n, ok := g.Node("a")
+	if !ok {
+		t.Fatal("node a missing")
+	}
+	if n.State != StateCompleted || n.Ref != "sub-1" || n.EndedAt != 42 {
+		t.Fatalf("update did not land: %+v", n)
+	}
+	if n.Label != "research" || n.Profile != "explore" || n.Kind != KindWorker || n.Grant != GrantRead {
+		t.Fatalf("outcome-only update blanked declared identity: %+v", n)
+	}
+}
+
+func TestApplyIgnoresUnusableRecords(t *testing.T) {
+	cases := []struct {
+		name  string
+		delta Delta
+	}{
+		{"node without id", Delta{Nodes: []Node{{State: StateRunning}}}},
+		{"edge without source", Delta{Edges: []Edge{{To: "b", Kind: Depends}}}},
+		{"edge without target", Delta{Edges: []Edge{{From: "a", Kind: Depends}}}},
+		{"edge without kind", Delta{Edges: []Edge{{From: "a", To: "b"}}}},
+		{"self edge", Delta{Edges: []Edge{{From: "a", To: "a", Kind: Depends}}}},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			var g Graph
+			g.Apply(c.delta)
+			if len(g.Nodes) != 0 || len(g.Edges) != 0 {
+				t.Fatalf("recorded %+v", g)
+			}
+		})
+	}
+}
+
+func TestApplyKeepsEdgesDistinctByKind(t *testing.T) {
+	var g Graph
+	// depends and context join the same pair and are not the same fact: an arm
+	// that orders without delivering emits the first and not the second.
+	edges := []Edge{
+		{From: "a", To: "b", Kind: Depends},
+		{From: "a", To: "b", Kind: Context},
+		{From: "a", To: "b", Kind: Depends},
+	}
+	g.Apply(Delta{Edges: edges})
+	if len(g.Edges) != 2 {
+		t.Fatalf("edges = %v, want depends and context once each", g.Edges)
+	}
+	for _, want := range []Edge{{From: "a", To: "b", Kind: Depends}, {From: "a", To: "b", Kind: Context}} {
+		if !slices.Contains(g.Edges, want) {
+			t.Fatalf("missing %+v in %v", want, g.Edges)
+		}
+	}
+}
+
+func TestApplyIsOrderStable(t *testing.T) {
+	build := func() Graph {
+		var g Graph
+		for _, id := range []string{"a", "b", "c"} {
+			g.Apply(Delta{Nodes: []Node{{ID: id, Kind: KindWorker, State: StatePending}}})
+		}
+		g.Apply(Delta{Nodes: []Node{{ID: "b", State: StateRunning}}})
+		return g
+	}
+	first, second := build(), build()
+	if len(first.Nodes) != 3 {
+		t.Fatalf("nodes = %d, want 3", len(first.Nodes))
+	}
+	for i := range first.Nodes {
+		if first.Nodes[i] != second.Nodes[i] {
+			t.Fatalf("node %d diverged: %+v vs %+v", i, first.Nodes[i], second.Nodes[i])
+		}
+	}
+	if first.Nodes[1].ID != "b" || first.Nodes[1].State != StateRunning {
+		t.Fatalf("an update reordered the graph: %+v", first.Nodes)
+	}
+}
+
+func TestStateVocabulary(t *testing.T) {
+	cases := []struct {
+		state    NodeState
+		answered bool
+		terminal bool
+	}{
+		{StatePending, false, false},
+		// Queued is not terminal: the node has not run, and a reader that treats
+		// it as settled stops waiting for the answer it is still going to get.
+		{StateQueued, false, false},
+		{StateRunning, false, false},
+		{StateCompleted, true, true},
+		{StateAdopted, true, true},
+		{StateFailed, false, true},
+		{StateCancelled, false, true},
+		{StateSkipped, false, true},
+	}
+	for _, c := range cases {
+		if got := c.state.Answered(); got != c.answered {
+			t.Errorf("%s.Answered() = %v, want %v", c.state, got, c.answered)
+		}
+		if got := c.state.Terminal(); got != c.terminal {
+			t.Errorf("%s.Terminal() = %v, want %v", c.state, got, c.terminal)
+		}
+	}
+}
+
+// A graph crosses a wire before it is drawn, so the folded value has to survive
+// the round trip that every consumer outside this process reads it through.
+func TestGraphSurvivesJSONRoundTrip(t *testing.T) {
+	var g Graph
+	g.Apply(Delta{
+		Nodes: []Node{
+			{ID: "grp", Kind: KindGroup, State: StateRunning, Label: "fleet(2)"},
+			{ID: "grp/1", ParentID: "grp", Kind: KindWorker, State: StateCompleted, Model: "m", StartedAt: 1, EndedAt: 2},
+			{ID: "old-ref", Kind: KindExternal, State: StateCompleted},
+		},
+		Edges: []Edge{
+			{From: "grp", To: "grp/1", Kind: Spawn},
+			{From: "old-ref", To: "grp/1", Kind: Adopt},
+		},
+	})
+	raw, err := json.Marshal(g)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var back Graph
+	if err := json.Unmarshal(raw, &back); err != nil {
+		t.Fatal(err)
+	}
+	if !slices.Equal(back.Edges, g.Edges) {
+		t.Fatalf("edges = %v, want %v", back.Edges, g.Edges)
+	}
+	if !slices.Equal(back.Nodes, g.Nodes) {
+		t.Fatalf("nodes = %v, want %v", back.Nodes, g.Nodes)
+	}
+}