waterplane 0.1.16 → 0.1.18

package/CHANGELOG.md

@@ -5,6 +5,34 @@ version — so entries are grouped by the release they shipped in. A fixed secur
 vulnerability in what ships is listed under a **Security:** bullet of the release that
 fixed it, with its CVE or GHSA id when one exists.
 
+## 0.1.18
+
+### New
+
+- **Another desktop that is waiting on you is named on the launcher.** A chip beside the desktop key shows what is waiting elsewhere. One tap switches to that desktop and lands on the item. The background connection now watches every saved desktop, and an alert starts with the desktop's name.
+- **Pair and use a desktop on Wi-Fi without Tailscale.** Pairing by code is sealed, so the code never crosses the network in the clear. The phone pins the desktop's key and refuses a swapped one in words. Over-the-air updates are signed by the desktop and checked on the phone.
+- **Lock the app with your fingerprint or screen lock.** Saved sign-ins can be sealed behind the same prompt. Settings says what locking costs each desktop before you choose, and offers a way out if the seal gets stuck.
+- **Run the pre-push checks without pushing.** In the git view, Run checks shows a verdict on each unpushed commit. A commit that passed offers Push up to here, which leaves newer commits local.
+- **The git sheet says how old the incoming count is, and fetches when it opens.** A stale zero now reads ↓? instead of claiming you are up to date.
+- **The first screen says what the app is.** It tells you the desktop half comes first and gives the pair command. It also says to scan the QR with the phone's camera app.
+- **Plain HTTP addresses are warned about.** The phone refuses fingerprints and over-the-air updates there and says why.
+- **The queue strip folds away.** Queued, sending and not-delivered rows go behind the corner button. A row that is moving keeps the fold, and a new row or a failure brings it back.
+
+### Fixed
+
+- **The "% of week" no longer reads wildly high on a desktop that does little of the week's work.** It refuses a figure that a paired desktop has outspent, and says so where the share would be. Settings can count every paired desktop instead.
+- **A plan with no 5-hour window says so in one row** instead of showing an empty bar and a complaint about a missing reset time.
+- **Reconnecting to a desktop without voice dictation no longer crashes the page.**
+- **A signing-key conflict on an app install no longer offers a retry that cannot work.** The card explains the conflict, and the button says to uninstall the old copy first and what that costs in data.
+- **A network failure while pulling is one info notice naming every repo.** A repo is filed as needing you only after three failures in a row, and a failed fetch says why.
+- **The upstream-age note in the git sheet keeps its height when the branch list opens.**
+
+## 0.1.17
+
+### Fixed
+
+- **A long build name no longer wraps one word per line in the build sheet.** The params line and the time line of a run row now sit under its name instead of beside it, so the name keeps the full row width.
+
 ## 0.1.16
 
 ### New

package/NOTICES.md

@@ -1,8 +1,8 @@
 # Third-party notices
 
 waterplane is MIT-licensed (see `LICENSE`). This file lists the runtime
-(non-dev) dependencies actually shipped across the three workspaces
-(`packages/shared`, `packages/host`, `packages/web`) and their licenses, as
+(non-dev) dependencies actually shipped across the three workspaces (`packages/shared`, `packages/host`,
+`packages/web`) and the Android shell (`packages/app`), and their licenses, as
 declared in each package's own `package.json` under `node_modules`.
 
 No Anthropic code is bundled in this project. It only spawns and talks to a
@@ -15,20 +15,31 @@ not a redistribution of Claude Code.
 | Package | Version | License | Project |
 | --- | --- | --- | --- |
 | `@xterm/headless` | 5.5.0 | MIT | https://github.com/xtermjs/xterm.js |
-| `node-pty` | 1.1.0 | MIT | https://github.com/microsoft/node-pty |
+| `node-pty` | 1.2.0-beta.15 | MIT | https://github.com/microsoft/node-pty |
 | `web-push` | 3.6.7 | **MPL-2.0** | https://github.com/web-push-libs/web-push |
-| `ws` | 8.21.0 | MIT | https://github.com/websockets/ws |
+| `ws` | 8.22.0 | MIT | https://github.com/websockets/ws |
 
 ## `packages/web`
 
 | Package | Version | License | Project |
 | --- | --- | --- | --- |
-| `@xterm/addon-fit` | 0.10.0 | MIT | https://github.com/xtermjs/xterm.js |
-| `@xterm/xterm` | 5.5.0 | MIT | https://github.com/xtermjs/xterm.js |
-| `lucide-react` | 1.21.0 | ISC | https://lucide.dev |
+| `@noble/hashes` | 2.4.0 | MIT | https://paulmillr.com/noble/ |
+| `@noble/post-quantum` | 0.7.1 | MIT | https://paulmillr.com/noble/ |
+| `@xterm/addon-fit` | 0.11.0 | MIT | https://github.com/xtermjs/xterm.js |
+| `@xterm/xterm` | 6.0.0 | MIT | https://github.com/xtermjs/xterm.js |
+| `lucide-react` | 1.61.0 | ISC | https://lucide.dev |
+| `qrcode-generator` | 2.0.4 | MIT | https://github.com/kazuhikoarase/qrcode-generator |
 | `react` | 18.3.1 | MIT | https://reactjs.org/ |
 | `react-dom` | 18.3.1 | MIT | https://reactjs.org/ |
 
+## `packages/app` (the Android shell)
+
+| Package | Version | License | Project |
+| --- | --- | --- | --- |
+| `@capacitor/android` | 8.5.3 | MIT | https://capacitorjs.com |
+| `@capacitor/core` | 8.5.3 | MIT | https://capacitorjs.com |
+| `@capacitor/ios` | 8.5.3 | MIT | https://capacitorjs.com |
+
 ## `packages/extensions/ocr` (downloaded to the phone, not in the web bundle)
 
 The text-in-marks extension's engine is copied from these packages into its `assets/` folder at

package/README.md

@@ -1,6 +1,7 @@
 # waterplane
 
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/16195/badge)](https://www.bestpractices.dev/projects/16195)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/waterplane-dev/waterplane/badge)](https://scorecard.dev/viewer/?uri=github.com/waterplane-dev/waterplane)
 
 <!-- site:intro -->
 **An IDE, rethought for the phone in the age of agentic coding.** The agent writes the code; what
@@ -28,6 +29,48 @@ macOS, Linux, Windows via WSL2 · Android app or web app, no iOS app yet
   will and when a fresh session is cheaper; run a build without a session; queue prompts for after
   the reset and give a session a budget.
 
+<!-- site:why -->
+### Why I wrote it
+
+waterplane started as my own itch, and that is still what it is at its core. Its first name was
+USAMC, "unsuck agentic mobile coding".
+
+- **What I build needs an emulator.** Android apps and Garmin watch apps: build, run it in the
+  emulator or the simulator, look at the screen. A cloud sandbox cannot do that, so the agent has
+  to work on my own machine.
+- **The agents need to be logged in as me.** App stores, registries, admin consoles. Handing my
+  credentials to a hosted agent is not what those services are for, and not an idea I was
+  comfortable with.
+- **I am away a lot, and the agents always need something from me.** A decision, an approval, a
+  look at a screenshot. Auto-approve gets around some of it; do you want that on a system with
+  real users?
+
+So I did what everyone does: NoMachine to the Mac, VS Code to open remote sessions, a few tricks on
+top. Every one of them was annoying from a phone, inconvenient, and not something I wanted exposed.
+I tried the other projects that put an agent on a phone, a lot of them; none fitted my requirements
+and the way I work completely. waterplane is what came out of that.
+
+**And many projects at once.** With agents doing the typing, people work on many projects at the
+same time. VS Code gives you one project per window; the Claude Code mobile app gives you one mixed
+list of conversations. waterplane keeps dozens of repos apart and in view at the same time. I run
+coding sessions across many projects with 100+ sessions open, and at peak hundreds of local agents
+at once, on a Mac Studio (M4, 64 GB). It works the same at a smaller scale on any machine where
+Claude Code runs, with little overhead.
+
+Two more things I was not at ease with:
+
+- **Credentials and admin logins permanently within reach of agents.** There is a vault extension
+  for this: a secret is released to one command for one run, with a fingerprint on the phone. It is
+  experimental and still private; it may be in a release soon, tagged experimental and off by
+  default. It has been tortured only by AI agents and reviewed by nobody else, so do not trust it
+  yet. And it has a limit no vault can move: a compromised desktop is a compromised desktop, and a
+  vault makes the attacker's work harder, not impossible.
+- **Remote desktop to a Mac from a phone is miserable.** Every solution I tried was. It was
+  surprisingly easy to let Claude build an alternative into waterplane that is actually usable from
+  a phone: the [live desktop view](packages/extensions/desktop/README.md), experimental, macOS and Windows,
+  shipped off by default.
+<!-- /site:why -->
+
 <!-- site:desk -->
 ### Not only on the phone
 

package/SECURITY.md

@@ -87,6 +87,60 @@ summary:
   and as the WebSocket subprotocol `waterplane-tok.<tok>` on the upgrade (the host
   echoes only the base protocol, never the token). No token is valid while
   no password is set.
+  On the phone the page keeps its tokens in the app's private localStorage; the
+  APK's background link keeps a second copy of each gated desktop's token so it
+  can reconnect with the app swiped away, AES-256-GCM sealed under a non-exportable
+  Android Keystore key (`ShellLinkTokens`), bound to that desktop's id and address,
+  sent only to that desktop's saved tailnet address, deleted when the desktop is
+  removed, the token is refused or the link is switched off. **Stated residual:**
+  the key needs no user authentication, because nobody is holding the phone when
+  the service reconnects, so this protects against a copied file, not against code
+  running as this app. That residual holds only while the phone's sign-ins are not
+  locked: with *lock the desktop sign-ins* on (next bullet), the link keeps no copy at rest.
+- **Sealed sign-ins (optional, off by default).** Settings › Connection ›
+  *lock the desktop sign-ins* (Android app) puts this phone's device tokens in one
+  blob under a Keystore key that each use opens with the fingerprint, or on a newer
+  shell the phone's PIN, and removes the plaintext. **It guards against a copy of
+  the app's storage (a backup, a pulled file), not against a hand holding the
+  unlocked phone** (that is the app lock, and the process holds the tokens in plaintext
+  memory while running). A desktop with no password has no token, so there is nothing
+  to lock for it. The background link, per APK: a newer app keeps each token in
+  memory only (alerts continue after a swipe-away until the phone restarts or
+  Android stops the app, then "locked — open the app"); an older app is handed no
+  token, so alerts from gated desktops wait until the app is opened. Nothing on the
+  host changes. **Stated residuals:** a token the desktop revoked stays in the blob
+  until the next rewrap; a stray bare token that belongs to no saved desktop can stay
+  plaintext (the row says so); passive (kids') tokens are not sealed; on an older
+  app the start prompt is the fingerprint only, and on a plain-HTTP route that app
+  refuses the key, so its card stays until the route is the tailnet or HTTPS (the row
+  refuses to lock in that state, and the host setup form refuses to save a plain
+  address while that app has both locks on); the recents thumbnail is as before; and a lost key
+  (screen lock removed, or a new fingerprint on a fingerprint-only key) loses the
+  sign-ins, so a tailnet-gated desktop must be paired again. A missing sensor never
+  counts as a lost key, and a lost one's blob is set aside on the phone
+  (`tokenSealDead`), not deleted; nothing restores it yet, and the next lock's new key
+  makes it unreadable. A key that is dead but not worded as such by an OEM stays a
+  refusal, and the person's way out is *forget the locked sign-ins* (confirmed, behind
+  the app lock): it discards the blob by hand, which gives a stranger nothing. "Nothing
+  connects before the unlock" is true of the socket only: tokenless HTTP, such as the
+  app-update check, runs first, carrying no token.
+- **App lock (optional, off by default).** The Android app can require the
+  phone's fingerprint, or on a newer shell its PIN, before it shows its screen
+  (Settings › Connection › *lock this app*). **It is a hold-the-phone defence at
+  UI level and nothing more.** No host route, token, gate or wire message changes;
+  deny-until-set, token rotation, the passive allowlist and the origin checks are
+  untouched, and **the device token's storage is unchanged** unless *lock the desktop
+  sign-ins* is on (localStorage, plus the sealed copy above). The page stays mounted behind an opaque card. Stated
+  residuals: anyone who has the phone's PIN passes it (the PIN fallback, or by
+  enrolling a finger); the recents thumbnail, and the frame the WebView shows on
+  wake before the page's JS runs, still show the last screen. The lock fails
+  closed: a cancelled, failed, locked-out or unrecognised refusal never opens the
+  app, at any repeat count. It opens and switches itself off (saying so) only when
+  the phone's own credential had to change the key, the app's saved check is
+  unreadable, or a fresh status read confirms no sensor or nothing to check with.
+  So on an old APK with a dead sensor that still reports hardware, or on a plain
+  HTTP route (where the old APK's key use is refused), the way out is a newer APK,
+  another route (the tailnet or HTTPS), or clearing the app's data.
 - **LAN identity.** `<state dir>/lan-identity.json` (0600) holds a `hostId`
   and a secret. `GET /api/lan/identity` hands them out to loopback and
   Tailscale callers ONLY — refused (403) for every other peer kind before the
@@ -97,8 +151,137 @@ summary:
   the thing answering at a LAN address holds the secret; it cannot resist an
   **active relay** on the person's own Wi-Fi that forwards the probe to the
   real desktop and then reads the plain-HTTP traffic (the token included).
+  With the token that relay can drive the desktop. It could also answer the app
+  with a forged page. So the Android app asks of every route whether it is
+  *protected* (`isPlainRoute` in shared, mirrored natively by `ShellRoute.java`),
+  and on one that is not it refuses every fingerprint use, every over-the-air
+  update and every app download or install, and warns in the address form, the
+  health sheet, the strip ("LAN, not protected") and a toast.
+  **The protected-route rule.** A route is protected only if it is exactly one
+  of: loopback; a Tailscale address or MagicDNS name over `http`, or `https` to a
+  `*.ts.net` name, unless a newer app reports that the phone has no tailnet
+  (then a tailnet name proves nothing: with Tailscale off, `100.x` goes to the
+  Wi-Fi gateway); the desktop's own TLS address on a newer app that holds its
+  pin; or an `https` address the person typed themselves. Everything else is
+  plain, **whatever its scheme**: a relay with a public certificate for its own
+  name passes `https` validation. A reply from a desktop that has not proved
+  itself (anything not sealed by the pairing code, or not received over a
+  protected route) never sets a saved desktop's address, key, pin or identity,
+  so a relay cannot walk a row onto itself. **Stated residuals:** a row saved
+  by an older app may already hold an address someone planted (a non-`ts.net`
+  `https` one reads as plain and the app opens an empty field to retype it; a
+  planted `ts.net` or `100.x` one cannot be told apart); and a person who taps
+  "pair" on a pairing link someone else made pairs with whoever made it (the
+  confirm says so). A browser on plain HTTP has no such defence, because the page
+  itself is what arrives unprotected, and the token is still exposed to the
+  relay. An older app keeps the older answer (tailnet and HTTPS only).
   Plain HTTP on a LAN has no defence against a man in the middle; if that
   network is not trusted, do not enable `WATERPLANE_ALLOW_PUBLIC`.
+- **LAN TLS and the pin** (`packages/host/src/lantls.ts`). Only where
+  `WATERPLANE_ALLOW_PUBLIC=1` already binds LAN addresses, the host also
+  listens on `WATERPLANE_TLS_PORT` (default port + 1) on those same addresses
+  with the same handler and the same gate, so a caller there is still peer kind
+  `lan` and needs its token. Off with `WATERPLANE_TLS=0`; never on loopback or
+  the tailnet; nothing without the opt-in. The key is P-256 in
+  `<state dir>/lan-tls.json` (0600), kept across restarts; the certificate is
+  self-signed and re-issued on the same key when the addresses change, so the
+  phone's pin (SHA-256 of the key) survives. The app stores the pin per desktop
+  and enforces it in the WebView, the background link and the pull service; a
+  desktop with a pin is then never reached over plain HTTP on a LAN address.
+  A self-signed port does not serve the web app (it answers a notice page): a
+  browser click-through would look protected and is not. With
+  `WATERPLANE_TLS_CERT` + `WATERPLANE_TLS_KEY` (a person's own leaf from a CA;
+  a self-signed one is read as self-signed) it serves the app, and the pin
+  follows that leaf. **What the pin does not defend:** the
+  WebView's handler runs only when validation fails, so a certificate valid
+  under a CA the phone trusts would skip the pin inside the WebView (pinned
+  addresses are private IPs and `.local` names, which public CAs do not issue,
+  and the app trusts no user-added CA); a first install of the APK over the
+  network (Android accepts any signature then); code already running in the
+  page; a browser; and dropping packets. The pin is a property of a newer APK:
+  a shipped one learns it and ignores it, and stays on plain LAN with the
+  warnings. The way out of a pinned desktop whose TLS port is off is a
+  confirmed "use plain HTTP for this desktop" on its row; nothing does it
+  by itself. The spike behind this (measured on two emulator WebViews only)
+  is in `docs/notes/protocol-and-security.md`. **None of this has been tried on
+  a real phone yet.**
+- **Signed updates** (`packages/host/src/updatekey.ts`, `webbundle.ts`,
+  `packages/web/src/updateTrust.ts`, `ShellBundleVerify.java`). Each desktop
+  signs its web bundle's manifest with its own P-256 key
+  (`<state dir>/update-key.json`, 0600), not a project key: people build their
+  own bundles, and a private key shipped to every desktop is no key. The
+  manifest carries `signed` (hostId, build id, `gen`, the file list with hashes)
+  and `sig`. A phone learns the desktop's public key from `welcome` only when
+  the delivering socket's address was protected (above), so a relay cannot
+  hand it one. Once a phone holds a key, an update that is unsigned, badly
+  signed, for another desktop or older than the last it took (`gen`, which
+  rises when the served build id changes, so a real revert still works) is
+  refused and nothing is written. The check runs in the page (works on a
+  shipped APK) and again natively on a newer one, which also asks in its own
+  dialog the first time it sees a desktop's key, a changed key, or a
+  restored desktop; page code cannot tap it. A new key (a wiped state dir) or a
+  lower `gen` (a restored one) waits for that answer. **What it does not do:** a
+  signature proves the bundle came from the desktop you paired, never that
+  its code is good. **A hostile desktop can still ship anything**, and a
+  paired host stays fully trusted (last section). A passive (kids') phone opens
+  no socket, so it never learns a key and takes updates as before, over a
+  route that is protected or it would take none. A shipped APK without the
+  native check has the page's check only, so page code that is already
+  compromised can still persist a bundle there. A desktop that cannot read or
+  write its key file serves the bundle unsigned (logged once): a phone that
+  holds a key then refuses it and says to update or repair the desktop.
+- **Pairing with no tailnet** (`pairpake.ts`, `shared/pake.ts`). A phone
+  pairs by CPace over ristretto255 keyed by the 8-character code, on the plain
+  port: the phone proves it knows the code first, the host answers with a
+  sealed reply (token, `hostId`, TLS pin, update key, LAN identity), and the
+  seal authenticates the host. A relay gets one online guess per attempt; an
+  impostor host answering `start` gets at most five, one per share it sends,
+  which is all a phone will answer. A real host offers the five newest open
+  codes, each confirm checked against all of them in constant time, so with
+  more than five open an older code never pairs this way: its phone is told
+  the desktop does not know that code and to show a new QR, which then works,
+  and the attempt counts as a miss against the five offered. A session lives
+  60 s and is deleted on its first `finish`.
+  10 wrong confirms close a code *for this pairing only*: it still redeems over
+  the tailnet, so a device on the Wi-Fi can stop an encrypted pairing (as
+  dropping packets does) but cannot burn a code meant for the tailnet. The
+  desktop refuses with no password set. **A code never crosses a plain socket
+  and lives:** on one that is not loopback, the tailnet, `tailscale serve` or
+  TLS, `/pair/<code>` and `/pair/<code>/apk` burn the code and show a page with
+  no link and no APK; a LAN-only desktop's screen shows the deep-link QR, which
+  goes camera to app. A code already sent plain is dead on that phone. The
+  link also carries a 128-bit commitment to the key and pin, which the seal
+  must match. **Stated residuals:** a person who accepts the question that
+  appears for an older desktop (it cannot tell an old desktop from someone
+  blocking encrypted pairing) spends that code and token in the clear, as
+  before; a relay can fill the miss count and stop pairing; whether every
+  camera app opens the waterplane link is unverified, and the typed code runs the
+  same protocol; the first APK install over the network is unprotected.
+  `waterplane pair` prints the update key's fingerprint beside the code.
+- **Read ticket** (`auth.ts`, `POST /api/auth/read-ticket`). An image tag or a
+  download link cannot carry a bearer, so a phone with no tailnet could not
+  load them. A signed device token buys a one-hour ticket (HMAC of device id,
+  scope and expiry; the key lives in memory, so a restart voids every
+  ticket) that is accepted as `?wt=` **only** on the two opaque read routes
+  (`OPAQUE_READ_ROUTES`), **only** over the TLS socket, GET/HEAD only, only
+  while the device row exists, and held to the row's scope (a passive phone's
+  ticket gets what a passive token gets). Access logs, shares and copies
+  strip `wt`. A ticket in a URL is a credential for those two read routes for
+  up to an hour: do not paste such a URL.
+- **A phone with Tailscale off.** It reaches the desktop only on the Wi-Fi.
+  A shipped APK stays on plain LAN with name-based trust as before, except
+  that an update key it already holds still refuses a forged bundle. A newer
+  APK pairs by code, holds the pin and goes over TLS. A phone that never
+  learned a pin cannot tell a relay from the desktop on the first
+  plain contact; pairing by code is the fix. The password-change case: tokens
+  rotate as before, so a LAN-only phone must pair again, and its gate says so
+  rather than asking for a password that cannot work there.
+  On a shell that enforces pins, a page that knows Tailscale is off sends no
+  device token to a tailnet address, pinned or not, since only the Wi-Fi can
+  answer it. Until the shell's first network reading it holds the token back on
+  those addresses and learns no pin, for at most 8 seconds; a shell silent past
+  that falls to trust by name. The background link is not covered on an unpinned
+  row: it sends its token to the address it holds, as before.
 - **Pairing codes** (`packages/host/src/pair.ts`). `POST /api/pair/mint`
   sits behind the normal gate; the 8-character code lives 10 minutes, is kept
   in memory only as its sha256 (a restart invalidates every outstanding one),
@@ -169,19 +352,20 @@ summary:
   The shell does not inherit the daemon's API keys and key files
   (`*_API_KEY`, `*_KEY_FILE`, `*_KEYCHAIN` are unset in the pane), and its
   commands are never written to the session's prompt history.
-- **Live desktop** (`packages/extensions/desktop`, macOS, experimental). Watching is a
+- **Live desktop** (`packages/extensions/desktop`, macOS, and Windows with the host in WSL; experimental). Watching is a
   stream on the same device-token socket and widens no gate. **Control is
   arbitrary input on the desktop** (clicks and keys reach every app, password
   managers and a logged-in terminal included), so it carries the same trust as
   the PTY and is a separate setting, **off by default**. It is gated on the
   host, not only on the phone: with it off, `stream.input` is dropped before it
-  reaches the helper, and with it on it still needs the macOS Accessibility
-  grant. A peer token never reaches a stream (`/api/peer/*` only), and no job,
-  schedule or peer desktop opens a desktop stream. The helper `wp-desktop` runs
-  as the desktop user, is signed with a stable identifier and holds only the
-  Screen Recording and Accessibility grants a person gave it at the Mac (it asks
-  macOS only when a person taps Fix on a setup row), and capture runs only while a
-  view is open. macOS shows its own recording indicator the whole time.
+  reaches the helper, and with it on a Mac still needs the macOS Accessibility
+  grant. Windows asks no app for a grant, so there the host's switch is the only
+  gate. A peer token never reaches a stream (`/api/peer/*` only), and no job,
+  schedule or peer desktop opens a desktop stream. The helper `wp-desktop` runs as the desktop user and capture runs only while a
+  view is open. On a Mac it is signed with a stable identifier and holds only the
+  Screen Recording and Accessibility grants a person gave it there (it asks macOS
+  only when a person taps Fix on a setup row), and macOS shows its own recording
+  indicator the whole time. Windows shows no such indicator.
 - **Browser origins** (`packages/host/src/origin.ts`). Every `/api/*` request
   and WebSocket upgrade is checked on `Origin` and `Host`; only `http`/`https`
   origins naming this machine on a port it serves pass, plus exactly one
@@ -386,10 +570,10 @@ do so anyway, e.g.:
   running the daemon.
 - **A paired host is fully trusted by the Android shell.** The app's UI
   updates over the air from the host it is paired with
-  (`packages/web/src/webUpdate.ts`); the manifest's sha256 hashes come from
-  that same host, so they catch corruption, not a hostile host. A host you
-  pair with can ship JS that runs with the shell's native plugins. Pair only
-  with desktops you control.
+  (`packages/web/src/webUpdate.ts`). Its bundles are signed with a per-desktop
+  key the phone pins over a protected route, which stops a relay on the network,
+  never the desktop itself: a host you pair with can ship JS that runs with the
+  shell's native plugins. Pair only with desktops you control.
 
 If you're not sure whether something is in scope, report it privately anyway
 and let us sort it out together — a false positive costs us a few minutes; a

package/node_modules/@waterplane/shared/dist/desktopfiles.d.ts

@@ -17,6 +17,8 @@ export interface DesktopInventoryInput {
     userOnlyPlugins?: string[];
     /** `mcpServers` keys of `~/.claude.json` `projects[<cwd realpath>]` — local scope (`claude mcp add`). */
     localMcp?: string[];
+    /** Context hooks of the user's settings.json; null = unreadable (a row says so). */
+    hooks?: ContextHook[] | null;
 }
 /** Every kind word `desktopInventory` writes (plugin skills carry their plugin in brackets after it). */
 export declare const DESKTOP_KINDS: {
@@ -30,6 +32,7 @@ export declare const DESKTOP_KINDS: {
     readonly localMcp: "local MCP server";
     readonly plugin: "plugin";
     readonly managedSkills: "managed plugin skills";
+    readonly hook: "context hook";
 };
 /** Why a plugin row has no skills listed: `enabledPlugins` turned it off. */
 export declare const PLUGIN_DISABLED = "disabled in settings.json enabledPlugins \u2014 its skills are not carried";
@@ -37,6 +40,18 @@ export declare const PLUGIN_DISABLED = "disabled in settings.json enabledPlugins
 export declare const PLUGIN_UNREAD = "enabled in settings, but not installed under the config dir \u2014 its skills are not sized here";
 /** The one row for plugin packs no file on this desktop names (claude.ai-managed, synced). */
 export declare const MANAGED_SKILLS = "skills from claude.ai-managed or synced plugins are not on disk here; the session view's skill listing (what a session's first request carried) is the measured count";
+/** The two hook events whose output reaches the model's context; every other event injects nothing. */
+export declare const CONTEXT_HOOK_EVENTS: readonly ["SessionStart", "UserPromptSubmit"];
+export type ContextHookEvent = (typeof CONTEXT_HOOK_EVENTS)[number];
+/** One file's commands on one event. A count, never the command text: that can hold a secret, and these rows reach the phone. */
+export interface ContextHook {
+    event: ContextHookEvent;
+    /** The file that declares it, in the row's own path words. */
+    path: string;
+    commands: number;
+}
+/** Why a context-hook row has no number, and where its size is measured instead. */
+export declare const hookUnsized: (h: Pick<ContextHook, "event" | "commands">) => string;
 /** `~/.claude.json` sits in the home dir, BESIDE the config dir, so its rows name it whole (a `~` path is already words). */
 export declare const USER_CLAUDE_JSON = "~/.claude.json";
 /** This desktop's always-on rows, user files first, then skills, then the unsized MCP rows. */
@@ -82,6 +97,12 @@ export interface DesktopSources {
     localMcp: string[];
     /** `.mcp.json` servers this desktop declined (`disabledMcpjsonServers`, in `.claude.json` or any settings file). */
     mcpjsonDeclined: string[];
+    /** Context hooks of the user's settings.json; null = that file is there but unreadable. */
+    hooks: ContextHook[] | null;
+    /** Context hooks of the repo's settings files: repo rows, unsized. */
+    projectHooks: ContextHook[];
+    /** The repo's settings files that are there but unreadable: one row each. */
+    projectHooksUnread: string[];
 }
 /**
  * Which plugins and MCP servers a session started in this repo on this desktop gets, out of the
@@ -94,7 +115,8 @@ export declare function desktopSources(i: DesktopSourcesInput): DesktopSources;
 export declare const MCP_DECLINED = "declined on this desktop (disabledMcpjsonServers) \u2014 not loaded";
 /**
  * The repo rows as THIS desktop loads them: a `.mcp.json` server it declined says so instead of
- * claiming tool schemas, and the plugins the repo's settings turn on are listed, unsized.
+ * claiming tool schemas, and the plugins and context hooks the repo's settings turn on are listed,
+ * unsized.
  */
-export declare function repoRowsOnThisDesktop(files: InstructionFile[], s: Pick<DesktopSources, "mcpjsonDeclined" | "projectPlugins">): InstructionFile[];
+export declare function repoRowsOnThisDesktop(files: InstructionFile[], s: Pick<DesktopSources, "mcpjsonDeclined" | "projectPlugins"> & Partial<Pick<DesktopSources, "projectHooks" | "projectHooksUnread">>): InstructionFile[];
 export {};

package/node_modules/@waterplane/shared/dist/desktopfiles.js

@@ -3,7 +3,9 @@
  * auto-memory file of the repo's project slug, user skills, plugin skills (minus the plugins
  * `enabledPlugins` turns off, which get a row saying so), user and local-scope MCP servers, and ONE
  * unsized row for the managed/synced plugin packs no file here names — the static list is what
- * disk shows; a session's measured skill listing is the truth (`SessionCarried`).
+ * disk shows; a session's measured skill listing is the truth (`SessionCarried`). Hooks that can
+ * put text in context (`CONTEXT_HOOK_EVENTS`) are one unsized row per file and event: the log
+ * records the event, never the command, so only the session's measured "hook context" has a size.
  * The per-repo half is `agentfiles.ts` `instructionInventory()`; these rows carry `scope: "desktop"`
  * so a list can hold both and say which is which.
  *
@@ -29,6 +31,7 @@ export const DESKTOP_KINDS = {
     localMcp: "local MCP server",
     plugin: "plugin",
     managedSkills: "managed plugin skills",
+    hook: "context hook",
 };
 /** Why a plugin row has no skills listed: `enabledPlugins` turned it off. */
 export const PLUGIN_DISABLED = "disabled in settings.json enabledPlugins — its skills are not carried";
@@ -36,6 +39,15 @@ export const PLUGIN_DISABLED = "disabled in settings.json enabledPlugins — its
 export const PLUGIN_UNREAD = "enabled in settings, but not installed under the config dir — its skills are not sized here";
 /** The one row for plugin packs no file on this desktop names (claude.ai-managed, synced). */
 export const MANAGED_SKILLS = "skills from claude.ai-managed or synced plugins are not on disk here; the session view's skill listing (what a session's first request carried) is the measured count";
+/** The two hook events whose output reaches the model's context; every other event injects nothing. */
+export const CONTEXT_HOOK_EVENTS = ["SessionStart", "UserPromptSubmit"];
+// closed: `event` comes from this build's own CONTEXT_HOOK_EVENTS, read off this desktop's settings, never off the wire
+const HOOK_REACH = { SessionStart: "every session", UserPromptSubmit: "every prompt" };
+/** Why a context-hook row has no number, and where its size is measured instead. */
+export const hookUnsized = (h) => {
+    const [runs, it] = h.commands === 1 ? ["a command", "it"] : ["commands", "them"];
+    return `runs ${runs} whose output the CLI adds to ${HOOK_REACH[h.event]}; a session's context view measures the size as "hook context", and /hooks lists ${it}`;
+};
 /** `~/.claude.json` sits in the home dir, BESIDE the config dir, so its rows name it whole (a `~` path is already words). */
 export const USER_CLAUDE_JSON = "~/.claude.json";
 const D = { scope: "desktop" };
@@ -51,6 +63,24 @@ function skillsUnder(fs, dir) {
     }
     return out;
 }
+const hookKind = (h, plugin) => `${DESKTOP_KINDS.hook} ${h.event} (${h.commands} ${h.commands === 1 ? "command" : "commands"}${plugin ? `, plugin ${plugin}` : ""})`;
+const hookRow = (h, plugin) => ({ path: h.path, kind: hookKind(h, plugin), parts: [], unsized: hookUnsized(h) });
+const hooksUnreadRow = (path) => ({ path, kind: `${DESKTOP_KINDS.hook}s`, parts: [], unsized: `${path} could not be read` });
+/** The hooks an enabled plugin ships. The reader cannot tell missing from unreadable, so null is no rows; text that is not JSON says so. */
+function pluginHookRows(fs, p) {
+    const path = `${trimEndChars(p.rel, "/")}/hooks/hooks.json`;
+    const text = fs.read(path);
+    if (text == null)
+        return [];
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        return [hooksUnreadRow(path)];
+    }
+    return isObj(json) ? contextHooksOf(json, path).map((h) => hookRow(h, p.name)) : [hooksUnreadRow(path)];
+}
 const skillKind = (base, text) => (skillDescChars(text) > 0 ? base : `${base} — no description found in its frontmatter`);
 /** This desktop's always-on rows, user files first, then skills, then the unsized MCP rows. */
 export function desktopInventory(i) {
@@ -82,6 +112,14 @@ export function desktopInventory(i) {
     for (const key of i.userOnlyPlugins ?? []) {
         out.push({ path: "settings.json", kind: `${DESKTOP_KINDS.plugin} ${key}`, parts: [], unsized: PLUGIN_UNREAD, ...D });
     }
+    if (i.hooks === null)
+        out.push({ ...hooksUnreadRow("settings.json"), ...D });
+    for (const h of i.hooks ?? [])
+        out.push({ ...hookRow(h), ...D });
+    // `plugins` holds the enabled ones only: a disabled plugin's hooks do not load, so they are never read.
+    for (const p of i.plugins ?? [])
+        for (const r of pluginHookRows(i.fs, p))
+            out.push({ ...r, ...D });
     if (i.userMcp == null) {
         out.push({ path: USER_CLAUDE_JSON, kind: DESKTOP_KINDS.userMcpServers, parts: [], unsized: "~/.claude.json could not be read", ...D });
     }
@@ -99,6 +137,23 @@ export function desktopInventory(i) {
 }
 const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
 const strs = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string") : []);
+/** A settings-shaped object's context hooks, one entry per event with a command. A missing or non-object `hooks` is none. */
+function contextHooksOf(json, path) {
+    const hooks = json.hooks;
+    if (!isObj(hooks))
+        return [];
+    const out = [];
+    for (const event of CONTEXT_HOOK_EVENTS) {
+        const groups = hooks[event];
+        if (!Array.isArray(groups))
+            continue;
+        const commands = groups.flatMap((g) => (isObj(g) && Array.isArray(g.hooks) ? g.hooks : []))
+            .filter((h) => isObj(h) && h.type === "command" && typeof h.command === "string").length;
+        if (commands)
+            out.push({ event, path, commands });
+    }
+    return out;
+}
 /**
  * Which plugins and MCP servers a session started in this repo on this desktop gets, out of the
  * files that decide it: `enabledPlugins` (user < project < local; `false` turns a plugin off),
@@ -117,7 +172,7 @@ export function desktopSources(i) {
     takeEnabled(i.userSettings, null);
     for (const p of i.projectSettings)
         takeEnabled(p.json, p.path);
-    const out = { plugins: [], outside: [], disabledPlugins: [], userOnlyPlugins: [], projectPlugins: [], userMcp: [], localMcp: [], mcpjsonDeclined: [] };
+    const out = { plugins: [], outside: [], disabledPlugins: [], userOnlyPlugins: [], projectPlugins: [], userMcp: [], localMcp: [], mcpjsonDeclined: [], hooks: [], projectHooks: [], projectHooksUnread: [] };
     const userKeys = new Set();
     if (i.installed !== "missing") {
         if (!isObj(i.installed) || !isObj(i.installed.plugins))
@@ -153,6 +208,16 @@ export function desktopSources(i) {
         else
             out.userOnlyPlugins.push(key);
     }
+    if (isObj(i.userSettings))
+        out.hooks = contextHooksOf(i.userSettings, "settings.json");
+    else if (i.userSettings !== "missing")
+        out.hooks = null;
+    for (const p of i.projectSettings) {
+        if (isObj(p.json))
+            out.projectHooks.push(...contextHooksOf(p.json, p.path));
+        else if (p.json !== "missing")
+            out.projectHooksUnread.push(p.path);
+    }
     const declined = new Set();
     for (const p of i.projectSettings)
         if (isObj(p.json))
@@ -178,7 +243,8 @@ export function desktopSources(i) {
 export const MCP_DECLINED = "declined on this desktop (disabledMcpjsonServers) — not loaded";
 /**
  * The repo rows as THIS desktop loads them: a `.mcp.json` server it declined says so instead of
- * claiming tool schemas, and the plugins the repo's settings turn on are listed, unsized.
+ * claiming tool schemas, and the plugins and context hooks the repo's settings turn on are listed,
+ * unsized.
  */
 export function repoRowsOnThisDesktop(files, s) {
     const declined = new Set(s.mcpjsonDeclined);
@@ -188,6 +254,10 @@ export function repoRowsOnThisDesktop(files, s) {
     for (const p of s.projectPlugins) {
         rows.push({ path: p.path, kind: `project ${DESKTOP_KINDS.plugin} ${p.key}`, parts: [], unsized: "enabled in this repo's settings — its skills load from the plugin cache and are not sized here" });
     }
+    for (const path of s.projectHooksUnread ?? [])
+        rows.push(hooksUnreadRow(path));
+    for (const h of s.projectHooks ?? [])
+        rows.push(hookRow(h));
     return rows;
 }
 //# sourceMappingURL=desktopfiles.js.map