waterplane 0.0.1 → 0.1.11

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

@@ -0,0 +1,65 @@
+/**
+ * The Intent — one durable "do this, there, when that is true", owned by the
+ * HOST, and the single pure rule that decides whether it may run yet.
+ *
+ * ── Why this file exists ───────────────────────────────────────────────────
+ *
+ * Deferred work in this app is currently decided in six places, each with its
+ * own store, its own tick, its own lifecycle words and its own failure ladder:
+ * the backlog (per-repo JSON, 2 s tick), the schedule (host-wide JSON, 20 s),
+ * the launch gate (host-wide JSON, 5 s), fan-out and builds (in-memory rings
+ * that die with the daemon), and the phone's send queue (localStorage, capped
+ * at 50 entries, expiring anything older than 30 minutes). Five of the six say
+ * "queued" and mean five different things; the sixth deletes work on a clock.
+ *
+ * That last one is what actually cost the user prompts. The phone was the OWNER
+ * of undelivered work while being the least reliable component in the system —
+ * a browser tab on a bad tunnel, which reloads at exactly the worst moment, and
+ * which shreds an unsent prompt to a 200-character gravestone an hour later.
+ *
+ * So the ownership moves: an intent is posted to the desktop, written to disk
+ * BEFORE it is acked, and from that moment the phone may forget it. The desktop
+ * is awake, has a disk, and is where the work happens.
+ *
+ * ── What is in here, and what is deliberately not ──────────────────────────
+ *
+ * This module is the MODEL and the RULE, nothing else. No filesystem, no
+ * `Date.now()`, no host imports — time and every fact about the world arrive as
+ * parameters, exactly as `nextFireAt` already takes them.
+ * That is what lets `packages/shared/test/intent.test.mjs` pin the whole ladder
+ * from literals in ~90 ms with no daemon booted and no `packages/host/dist` in
+ * existence, which in turn is what lets the rule be settled before there is
+ * anything to run it.
+ *
+ * The manager (persistence, the tick, the executors, the broadcast) is the
+ * host's. Everything it decides, it decides by asking `intentVerdict`.
+ *
+ * ── The one rule that is not negotiable ────────────────────────────────────
+ *
+ * An intent is never deleted by a clock. It waits, it fails loudly, or the user
+ * cancels it. `payload.steps` is kept in FULL, forever, un-clipped, until the
+ * row reaches a terminal state a person has actually seen. Every cap in
+ * `cleanIntentRow` below is on a COUNT or on a label — never on the words.
+ *
+ * ── Where it lives ─────────────────────────────────────────────────────────
+ *
+ * This file is the BARREL: the one door into the intent model. The code is in
+ * `intent/` — `types`, `row`, `facts`, `words`, `budgetpass`, `kind`, `target`,
+ * `verdict`, `clean`, `slot` — and every importer names `./intent.js` (or
+ * `@waterplane/shared`), never a slice. The lists below are explicit because a
+ * slice also exports helpers its siblings need (the ladder's own sentences,
+ * `budgetHold`, `targetVerdict`) that are not part of this module's surface,
+ * which `test/intentsurface.test.mjs` pins. Layout, import order and caps:
+ * docs/notes/shared-architecture.md.
+ */
+export { REQUEUE_KEEP } from "./intent/types.js";
+export { HELD_MAX_MS, INTENT_MAX_ATTEMPTS, INTENT_MAX_DIRS, INTENT_MAX_NEEDS, INTENT_MAX_STEPS, ON_TIME_MS } from "./intent/row.js";
+export { busyIntentGroups, intentSerialHolders } from "./intent/facts.js";
+export { intentVerdict } from "./intent/verdict.js";
+export { liveConvSession, needsSlot, reopensConversation } from "./intent/target.js";
+export { AFTER_RESET_LEFTOVER_MS, BUDGET_NOT_HOLDING, RESET_MATCH_MS, budgetAfterResetOf, budgetLeftoverOf, budgetPassAt, budgetPassOf, budgetWaived, budgetWaiverPeriod, budgetWaiverUntil, cleanBudgetWaiver, } from "./intent/budgetpass.js";
+export { INTENT_BLOCK_ORDER, autoSlotsBusy, autoSlotsWaitText, closeWhenDoneOf, intentReasonText, localSlotOverText, localSlotWaitText } from "./intent/words.js";
+export { cleanIntentRow } from "./intent/clean.js";
+export { findSlot, latestClock, parseSlotKey, slotMates, slotOf, slotOthersText, slotRowOfIntent, slotRowOfItem, slotsOf } from "./intent/slot.js";
+export { AGENT_POSTED_WORDS, AGENT_WITHDREW_DETAIL, MANUAL_HOLD_TEXT, ORIGIN_AGENT, ORIGIN_FANOUT_FOLLOWUP, ORIGIN_FANOUT_RUN, ORIGIN_FANOUT_TARGET, ORIGIN_PEER_PREFIX, ORIGIN_SCHEDULE_BUILD, ORIGIN_SCHEDULE_PREFIX, ORIGIN_SCHEDULE_SWEEP, ORIGIN_SCHEDULE_WORK, clockKey, intentKind, isAgentPosted, isAgentWithdrawn, isAssessRow, isBacklogRow, isBuildRow, isCaptureRow, isFanoutRow, isLaunchRow, isPeerPosted, isScheduleRow, isTimedWorkRow, peerOfOrigin, postsScheduledBuild, queuesBacklogItem, scheduleIdFromOrigin, scheduleItemOrigin, timedWorkKey, } from "./intent/kind.js";
+//# sourceMappingURL=intent.js.map

package/node_modules/@waterplane/shared/dist/intent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.js","sourceRoot":"","sources":["../src/intent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAMH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGpI,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE1E,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAErF,OAAO,EACL,uBAAuB,EAAE,kBAAkB,EAAE,cAAc,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,iBAAiB,GACtM,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAElK,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAA6C,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAG9L,OAAO,EACL,kBAAkB,EAAE,qBAAqB,EAAE,gBAAgB,EAC3D,YAAY,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,kBAAkB,EACjG,qBAAqB,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,oBAAoB,EAC1F,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAC1G,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EACnF,mBAAmB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,YAAY,GAC/F,MAAM,kBAAkB,CAAC"}

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

@@ -0,0 +1,35 @@
+/**
+ * The files an item's words name: images anywhere, and the phone↔repo
+ * transport by full path.
+ *
+ * Moved out of the smart pick (removed 2026-10-16), where it decided whether
+ * a merge kept every file its members named. The backlog row's thumbnails read
+ * `imagePaths`; `transportPaths` is the rule anything that ever folds two
+ * items into one must keep — a merged text that drops a path is a merge that
+ * loses the picture somebody attached.
+ */
+/**
+ * An image path as the backlog row's thumbnails find one.
+ *
+ * Global, so `String.match` returns every hit. Never call `.test()` on it: a
+ * global regex carries `lastIndex` between calls and would answer differently on
+ * the second question about the same string.
+ */
+export declare const IMG_RE: RegExp;
+/**
+ * A file on the phone↔repo transport, by its FULL path.
+ *
+ * CLAUDE.md: files a person uploaded arrive in `.claude/inbox/`, artifacts a
+ * person should see go in `.claude/outbox/`, and both are named by full path
+ * every time they are mentioned — a bare filename resolves nowhere.
+ */
+export declare const TRANSPORT_RE: RegExp;
+/** Every image path in some text, de-duplicated, trailing punctuation stripped. */
+export declare function imagePaths(text: string): string[];
+/**
+ * Every FILE this text tells an agent to look at: transport paths first, then
+ * images anywhere. The union, not either half: an inbox path that is not an
+ * image (`.claude/inbox/log.txt`) and an image that is not on the transport
+ * (`docs/flow.png`) are both files a rewritten text has to keep naming.
+ */
+export declare function transportPaths(text: string): string[];

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

@@ -0,0 +1,55 @@
+/**
+ * The files an item's words name: images anywhere, and the phone↔repo
+ * transport by full path.
+ *
+ * Moved out of the smart pick (removed 2026-10-16), where it decided whether
+ * a merge kept every file its members named. The backlog row's thumbnails read
+ * `imagePaths`; `transportPaths` is the rule anything that ever folds two
+ * items into one must keep — a merged text that drops a path is a merge that
+ * loses the picture somebody attached.
+ */
+/**
+ * An image path as the backlog row's thumbnails find one.
+ *
+ * Global, so `String.match` returns every hit. Never call `.test()` on it: a
+ * global regex carries `lastIndex` between calls and would answer differently on
+ * the second question about the same string.
+ */
+export const IMG_RE = /\S+\.(?:png|jpe?g|gif|webp|bmp|heic|heif|svg)\b/gi;
+/**
+ * A file on the phone↔repo transport, by its FULL path.
+ *
+ * CLAUDE.md: files a person uploaded arrive in `.claude/inbox/`, artifacts a
+ * person should see go in `.claude/outbox/`, and both are named by full path
+ * every time they are mentioned — a bare filename resolves nowhere.
+ */
+export const TRANSPORT_RE = /\.claude\/(?:inbox|outbox)\/\S+/gi;
+/**
+ * Markup and punctuation off BOTH ends of a matched path.
+ *
+ * Backticks and asterisks are in the class because prompts are written in
+ * markdown: `` `.claude/inbox/a.png` `` and `**a.png**` otherwise carry their
+ * fences into the path. Both ends, because the two regexes clip differently:
+ * `TRANSPORT_RE` starts at `.claude/`, so an opening fence falls outside its
+ * match, while `IMG_RE` is `\S+` and swallows it.
+ */
+const trimPath = (s) => s.replace(/^[([{'"`*]+/, "").replace(/[)\]}.,;:'"`*]+$/, "");
+/** Every image path in some text, de-duplicated, trailing punctuation stripped. */
+export function imagePaths(text) {
+    const m = typeof text === "string" ? text.match(IMG_RE) : null;
+    return m ? [...new Set(m.map(trimPath))] : [];
+}
+/**
+ * Every FILE this text tells an agent to look at: transport paths first, then
+ * images anywhere. The union, not either half: an inbox path that is not an
+ * image (`.claude/inbox/log.txt`) and an image that is not on the transport
+ * (`docs/flow.png`) are both files a rewritten text has to keep naming.
+ */
+export function transportPaths(text) {
+    if (typeof text !== "string" || !text)
+        return [];
+    const m = text.match(TRANSPORT_RE);
+    const out = m ? m.map(trimPath) : [];
+    return [...new Set([...out, ...imagePaths(text)])];
+}
+//# sourceMappingURL=itempaths.js.map

package/node_modules/@waterplane/shared/dist/itempaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"itempaths.js","sourceRoot":"","sources":["../src/itempaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,mDAAmD,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,mCAAmC,CAAC;AAEhE;;;;;;;;GAQG;AACH,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;AAErG,mFAAmF;AACnF,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,CAAC,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/D,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACjD,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACrC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC"}

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

@@ -0,0 +1,32 @@
+/**
+ * The keys the CLI tells a person to press, and the bytes each one is.
+ *
+ * claude's footer and pickers name their own shortcuts — `(shift+tab to
+ * cycle)`, `s to use this session only`, `Tab to toggle`. A phone has no
+ * shift, no ctrl and (outside CLI mode) no bare letter key, so the host reads
+ * those hints off the screen (`host/keyhints.ts`) and the phone offers each as
+ * one tap on the key row. This file is the half both ends must agree on: which
+ * key names count and what is written to the PTY for them.
+ *
+ * Only keys the fixed row does NOT already have: Esc, Tab, Return and the
+ * arrows are always there, so a hint naming one of them adds no chip.
+ */
+/** One hint as the CLI drew it: the key (normalised, lower case) and its
+ *  verb in the CLI's own words (`cycle`, `use this session only`). */
+export interface KeyHint {
+    key: string;
+    verb: string;
+}
+/** Most chips a row carries — past three the row stops being a key row. */
+export declare const KEY_HINT_MAX = 3;
+/**
+ * The bytes for a hinted key, or null for a key that is not one this list
+ * knows. `shift+tab` → CSI Z, `ctrl+<letter>` → its control byte, a bare
+ * lower-case letter or digit → itself. `ctrl+c` (the row's `^C`) and
+ * `ctrl+g` (opens an editor) are refused.
+ */
+export declare function keyHintBytes(key: string): string | null;
+/** The chip's key label: `⇧Tab`, `^O`, `s`. */
+export declare function keyHintLabel(key: string): string;
+/** Same hints, same order — the host publishes only on a change. */
+export declare function sameKeyHints(a: readonly KeyHint[] | undefined, b: readonly KeyHint[] | undefined): boolean;

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

@@ -0,0 +1,53 @@
+/**
+ * The keys the CLI tells a person to press, and the bytes each one is.
+ *
+ * claude's footer and pickers name their own shortcuts — `(shift+tab to
+ * cycle)`, `s to use this session only`, `Tab to toggle`. A phone has no
+ * shift, no ctrl and (outside CLI mode) no bare letter key, so the host reads
+ * those hints off the screen (`host/keyhints.ts`) and the phone offers each as
+ * one tap on the key row. This file is the half both ends must agree on: which
+ * key names count and what is written to the PTY for them.
+ *
+ * Only keys the fixed row does NOT already have: Esc, Tab, Return and the
+ * arrows are always there, so a hint naming one of them adds no chip.
+ */
+/** Most chips a row carries — past three the row stops being a key row. */
+export const KEY_HINT_MAX = 3;
+/**
+ * The bytes for a hinted key, or null for a key that is not one this list
+ * knows. `shift+tab` → CSI Z, `ctrl+<letter>` → its control byte, a bare
+ * lower-case letter or digit → itself. `ctrl+c` (the row's `^C`) and
+ * `ctrl+g` (opens an editor) are refused.
+ */
+export function keyHintBytes(key) {
+    if (key === "shift+tab")
+        return "\x1b[Z";
+    // Already on the fixed row as `^C`.
+    if (key === "ctrl+c")
+        return null;
+    // `ctrl+g to edit in Vim`: hands the PTY to an editor the phone has no way
+    // back out of except CLI mode and `:q!` — not a one-tap key.
+    if (key === "ctrl+g")
+        return null;
+    const ctrl = /^ctrl\+([a-z])$/.exec(key);
+    if (ctrl)
+        return String.fromCharCode(ctrl[1].charCodeAt(0) - 96);
+    if (/^[a-z0-9]$/.test(key))
+        return key;
+    return null;
+}
+/** The chip's key label: `⇧Tab`, `^O`, `s`. */
+export function keyHintLabel(key) {
+    if (key === "shift+tab")
+        return "⇧Tab";
+    const ctrl = /^ctrl\+([a-z])$/.exec(key);
+    if (ctrl)
+        return `^${ctrl[1].toUpperCase()}`;
+    return key;
+}
+/** Same hints, same order — the host publishes only on a change. */
+export function sameKeyHints(a, b) {
+    const x = a ?? [], y = b ?? [];
+    return x.length === y.length && x.every((h, i) => h.key === y[i].key && h.verb === y[i].verb);
+}
+//# sourceMappingURL=keyhint.js.map

package/node_modules/@waterplane/shared/dist/keyhint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyhint.js","sourceRoot":"","sources":["../src/keyhint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,GAAG,KAAK,WAAW;QAAE,OAAO,QAAQ,CAAC;IACzC,oCAAoC;IACpC,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAClC,2EAA2E;IAC3E,6DAA6D;IAC7D,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,IAAI;QAAE,OAAO,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;IACjE,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IACvC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,GAAG,KAAK,WAAW;QAAE,OAAO,MAAM,CAAC;IACvC,MAAM,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,IAAI;QAAE,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;IAC7C,OAAO,GAAG,CAAC;AACb,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAAC,CAAiC,EAAE,CAAiC;IAC/F,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IAC/B,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAChG,CAAC"}

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

@@ -0,0 +1,86 @@
+/**
+ * Whether the phone talks to a host over its LAN address or over the tailnet.
+ *
+ * Three gates, ANDed, and all three must be FRESH evidence rather than a
+ * remembered one:
+ *
+ * 1. the phone is on Wi-Fi and the network's name is one of `host.lan.ssids`;
+ * 2. the LAN address answered `/api/health` within `LAN_PROBE_TIMEOUT_MS`;
+ * 3. the answer proved it is THIS desktop (`/api/lan/verify` HMAC checked).
+ *
+ * Anything missing, unknown or failed ⇒ `tailnet`, the route that always works.
+ * A LAN failure newer than the last good probe also ⇒ `tailnet`, until the next
+ * trigger re-probes. Each verdict carries the one sentence the UI says about
+ * it; a number the input does not carry (probe time) is left out of the
+ * sentence, never guessed.
+ *
+ * The `NetState` below is also the contract of the Android `ShellNet` plugin:
+ * `ShellNet.current()` resolves to one, `window.shellNetChanged(json)`
+ * delivers one on every change.
+ */
+import type { SavedHost } from "./hosts.js";
+export type NetTransport = "wifi" | "cellular" | "other" | "none";
+/** Android's location permission, which is what reading the SSID needs. */
+export type NetPermission = "granted" | "denied" | "prompt";
+/** What the native shell knows about the phone's current network. */
+export interface NetState {
+    transport: NetTransport;
+    /** Wi-Fi name, `null` when unreadable (not Wi-Fi, or permission missing). */
+    ssid: string | null;
+    permission: NetPermission;
+}
+/** How long the LAN `/api/health` probe may take before the LAN is not used. */
+export declare const LAN_PROBE_TIMEOUT_MS = 1500;
+export interface LanProbe {
+    ok: boolean;
+    /** Round trip in ms, when measured. */
+    ms?: number;
+    /** When it finished (epoch ms) — compared only against `lastFailure.at`. */
+    at: number;
+}
+export interface LanFailure {
+    at: number;
+    /** What went wrong, in words (shown after "LAN failed:"). */
+    reason?: string;
+}
+export interface LanRouteInput {
+    host: Pick<SavedHost, "lan">;
+    /** `null` = no native shell / not reported (the browser PWA). */
+    net: NetState | null;
+    /** `null` = not probed yet on this trigger. */
+    probe: LanProbe | null;
+    /** `null` = not verified yet; `false` = verification failed. */
+    macVerified: boolean | null;
+    lastFailure?: LanFailure | null;
+}
+export type LanRoute = "lan" | "tailnet";
+export type LanRouteReason = "no-lan" | "auto-off" | "no-net" | "not-wifi" | "no-permission" | "no-ssid" | "ssid-mismatch" | "failed-recently" | "probe-pending" | "probe-failed" | "probe-slow" | "mac-pending" | "mac-failed" | "lan-ok";
+export interface LanRouteDecision {
+    route: LanRoute;
+    reason: LanRouteReason;
+    /** One sentence: why this route. */
+    sentence: string;
+    /** What the caller should do next to move toward LAN, if anything. */
+    next: "probe" | "verify" | null;
+}
+/** Is `ssid` one of this host's saved networks? Exact match — SSIDs are
+ *  case-sensitive and `"Home"` is not `"home"`. */
+export declare function ssidMatches(host: Pick<SavedHost, "lan">, ssid: string | null): boolean;
+export declare function decideLanRoute(input: LanRouteInput): LanRouteDecision;
+/** The route chip's word. */
+export declare function lanRouteLabel(route: LanRoute): string;
+/** `GET /api/lan/identity` → (loopback/Tailscale only). The HMAC key is the
+ *  UTF-8 bytes of `secret` as written (a base64url string), NOT its decoding. */
+export interface LanIdentityResponse {
+    hostId: string;
+    secret: string;
+    hostName: string;
+}
+/** `POST /api/lan/verify {nonce}` → `mac` = hex HMAC-SHA256(key = utf8(secret),
+ *  msg = hostId + "\n" + nonce). */
+export interface LanVerifyResponse {
+    hostId: string;
+    mac: string;
+}
+/** What `lanMacMessage` signs — one definition for both ends. */
+export declare function lanMacMessage(hostId: string, nonce: string): string;

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

@@ -0,0 +1,84 @@
+/**
+ * Whether the phone talks to a host over its LAN address or over the tailnet.
+ *
+ * Three gates, ANDed, and all three must be FRESH evidence rather than a
+ * remembered one:
+ *
+ * 1. the phone is on Wi-Fi and the network's name is one of `host.lan.ssids`;
+ * 2. the LAN address answered `/api/health` within `LAN_PROBE_TIMEOUT_MS`;
+ * 3. the answer proved it is THIS desktop (`/api/lan/verify` HMAC checked).
+ *
+ * Anything missing, unknown or failed ⇒ `tailnet`, the route that always works.
+ * A LAN failure newer than the last good probe also ⇒ `tailnet`, until the next
+ * trigger re-probes. Each verdict carries the one sentence the UI says about
+ * it; a number the input does not carry (probe time) is left out of the
+ * sentence, never guessed.
+ *
+ * The `NetState` below is also the contract of the Android `ShellNet` plugin:
+ * `ShellNet.current()` resolves to one, `window.shellNetChanged(json)`
+ * delivers one on every change.
+ */
+/** How long the LAN `/api/health` probe may take before the LAN is not used. */
+export const LAN_PROBE_TIMEOUT_MS = 1500;
+function tail(reason, sentence, next = null) {
+    return { route: "tailnet", reason, sentence, next };
+}
+/** Is `ssid` one of this host's saved networks? Exact match — SSIDs are
+ *  case-sensitive and `"Home"` is not `"home"`. */
+export function ssidMatches(host, ssid) {
+    return !!ssid && !!host.lan && host.lan.ssids.includes(ssid);
+}
+export function decideLanRoute(input) {
+    const { host, net, probe, macVerified, lastFailure } = input;
+    const lan = host.lan;
+    if (!lan)
+        return tail("no-lan", "Using the tailnet: no LAN address saved for this desktop.");
+    if (!lan.auto)
+        return tail("auto-off", "Using the tailnet: switching to LAN automatically is off.");
+    if (!net)
+        return tail("no-net", "Using the tailnet: this phone did not report which network it is on.");
+    if (net.transport !== "wifi") {
+        const what = net.transport === "cellular" ? "on mobile data" : net.transport === "none" ? "offline" : "not on Wi-Fi";
+        return tail("not-wifi", `Using the tailnet: the phone is ${what}.`);
+    }
+    if (net.permission !== "granted") {
+        return tail("no-permission", "Using the tailnet: reading the Wi-Fi name needs the location permission.");
+    }
+    if (!net.ssid)
+        return tail("no-ssid", "Using the tailnet: the Wi-Fi name could not be read.");
+    if (!ssidMatches(host, net.ssid)) {
+        return tail("ssid-mismatch", `Using the tailnet: "${net.ssid}" is not one of this desktop's saved networks.`);
+    }
+    if (lastFailure && (!probe || probe.at <= lastFailure.at)) {
+        const why = lastFailure.reason ? ` (${lastFailure.reason})` : "";
+        return tail("failed-recently", `Using the tailnet: the LAN connection failed${why}; it is tried again on the next network change or reconnect.`, "probe");
+    }
+    if (!probe)
+        return tail("probe-pending", `Using the tailnet while ${lan.base} is checked.`, "probe");
+    if (!probe.ok)
+        return tail("probe-failed", `Using the tailnet: ${lan.base} did not answer on "${net.ssid}".`);
+    if (probe.ms != null && probe.ms > LAN_PROBE_TIMEOUT_MS) {
+        return tail("probe-slow", `Using the tailnet: ${lan.base} took ${Math.round(probe.ms)} ms, over the ${LAN_PROBE_TIMEOUT_MS} ms limit.`);
+    }
+    if (macVerified === null)
+        return tail("mac-pending", `Using the tailnet while ${lan.base} proves it is this desktop.`, "verify");
+    if (!macVerified) {
+        return tail("mac-failed", `Using the tailnet: whatever answers at ${lan.base} could not prove it is this desktop.`);
+    }
+    const took = probe.ms != null ? ` in ${Math.round(probe.ms)} ms` : "";
+    return {
+        route: "lan",
+        reason: "lan-ok",
+        sentence: `Using LAN: on "${net.ssid}", ${lan.base} answered${took} and proved it is this desktop.`,
+        next: null,
+    };
+}
+/** The route chip's word. */
+export function lanRouteLabel(route) {
+    return route === "lan" ? "LAN" : "tailnet";
+}
+/** What `lanMacMessage` signs — one definition for both ends. */
+export function lanMacMessage(hostId, nonce) {
+    return `${hostId}\n${nonce}`;
+}
+//# sourceMappingURL=lanroute.js.map

package/node_modules/@waterplane/shared/dist/lanroute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lanroute.js","sourceRoot":"","sources":["../src/lanroute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAgBH,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAsDzC,SAAS,IAAI,CAAC,MAAsB,EAAE,QAAgB,EAAE,OAAiC,IAAI;IAC3F,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AACtD,CAAC;AAED;mDACmD;AACnD,MAAM,UAAU,WAAW,CAAC,IAA4B,EAAE,IAAmB;IAC3E,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAoB;IACjD,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC;IAC7D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;IACrB,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC,QAAQ,EAAE,2DAA2D,CAAC,CAAC;IAC7F,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC,UAAU,EAAE,2DAA2D,CAAC,CAAC;IACpG,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC,QAAQ,EAAE,sEAAsE,CAAC,CAAC;IACxG,IAAI,GAAG,CAAC,SAAS,KAAK,MAAM,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC;QACrH,OAAO,IAAI,CAAC,UAAU,EAAE,mCAAmC,IAAI,GAAG,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC,eAAe,EAAE,0EAA0E,CAAC,CAAC;IAC3G,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC,SAAS,EAAE,sDAAsD,CAAC,CAAC;IAC9F,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC,eAAe,EAAE,uBAAuB,GAAG,CAAC,IAAI,gDAAgD,CAAC,CAAC;IAChH,CAAC;IACD,IAAI,WAAW,IAAI,CAAC,CAAC,KAAK,IAAI,KAAK,CAAC,EAAE,IAAI,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC;QAC1D,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACjE,OAAO,IAAI,CAAC,iBAAiB,EAAE,+CAA+C,GAAG,8DAA8D,EAAE,OAAO,CAAC,CAAC;IAC5J,CAAC;IACD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC,eAAe,EAAE,2BAA2B,GAAG,CAAC,IAAI,cAAc,EAAE,OAAO,CAAC,CAAC;IACrG,IAAI,CAAC,KAAK,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC,cAAc,EAAE,sBAAsB,GAAG,CAAC,IAAI,uBAAuB,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC;IAC9G,IAAI,KAAK,CAAC,EAAE,IAAI,IAAI,IAAI,KAAK,CAAC,EAAE,GAAG,oBAAoB,EAAE,CAAC;QACxD,OAAO,IAAI,CAAC,YAAY,EAAE,sBAAsB,GAAG,CAAC,IAAI,SAAS,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,iBAAiB,oBAAoB,YAAY,CAAC,CAAC;IAC1I,CAAC;IACD,IAAI,WAAW,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC,aAAa,EAAE,2BAA2B,GAAG,CAAC,IAAI,6BAA6B,EAAE,QAAQ,CAAC,CAAC;IACjI,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC,YAAY,EAAE,0CAA0C,GAAG,CAAC,IAAI,sCAAsC,CAAC,CAAC;IACtH,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACtE,OAAO;QACL,KAAK,EAAE,KAAK;QACZ,MAAM,EAAE,QAAQ;QAChB,QAAQ,EAAE,kBAAkB,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,IAAI,YAAY,IAAI,iCAAiC;QACnG,IAAI,EAAE,IAAI;KACX,CAAC;AACJ,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,aAAa,CAAC,KAAe;IAC3C,OAAO,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7C,CAAC;AAQD,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,KAAa;IACzD,OAAO,GAAG,MAAM,KAAK,KAAK,EAAE,CAAC;AAC/B,CAAC"}

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

@@ -0,0 +1,110 @@
+/**
+ * A session that is supposed to open, held by the HOST until the files its
+ * first prompt names have actually landed.
+ *
+ * The failure this exists for: "open a session in this repo and look at
+ * `.claude/inbox/shot.jpg`" is assembled on the PHONE. The bytes are parked in
+ * the send queue, the create op is parked behind them in the same lane, and the
+ * whole plan lives in one browser tab on a device with a bad tunnel. If the
+ * upload cannot get through inside the client's 30-minute queue TTL, the upload
+ * fails, everything naming that path is failed with it, and the host — which is
+ * the machine that will actually do the work, and the one that is not on a
+ * train — never learned that any of it was supposed to happen.
+ *
+ * So the INTENT is handed over as early as it can be: the moment the create op
+ * reaches the host, whether or not the picture has. The host writes it down,
+ * persists it across restarts, and from then on it is the host that decides
+ * when the session opens. The phone may go into a tunnel, be killed by the OS,
+ * or be closed for the night; the launch still happens the moment the last file
+ * arrives, because nothing about it depends on that tab any more.
+ *
+ * The rule is pure and lives here so both ends agree on it (the queue sheet has
+ * to be able to say WHY a launch has not fired without asking) and so
+ * `scripts/e2e-launchwait.mjs` can pin it directly.
+ *
+ * At-most-once is by INTENT ID, which is the create op's own ackId: a replayed
+ * op upserts the row rather than adding a second one, exactly as
+ * `schedule.save` does. The host writes the "opening" state BEFORE it spawns,
+ * so a crash between the two can never open the session twice.
+ */
+import type { LaunchOpts } from "./wire/session.js";
+/**
+ * How long a launch may wait for its files before the host gives up.
+ *
+ * Deliberately much longer than the client's `QUEUE_TTL_MS` (30 min): the whole
+ * point of the handover is that the phone's clock stops mattering. Six hours
+ * covers a commute, a flight, and a night with the laptop shut — and it still
+ * ends, because a session opened tomorrow against a photo taken today is a
+ * surprise, not a feature.
+ */
+export declare const LAUNCH_WAIT_MS: number;
+/**
+ * **A launch somebody chose, as it may be STORED** — on a deferred row
+ * (`Intent.launch`), a schedule's action, a `backlog.add`.
+ *
+ * A `session.create` spends its launch at once; a row keeps it for days and
+ * every tick re-reads it off disk, so the opts are rebuilt from the five fields
+ * `LaunchOpts` names and nothing else rides along. A field that is not one of
+ * them, or not a value the CLI would take, is DROPPED rather than guessed at —
+ * a dropped field is the new-session default, which is what absent always
+ * meant. All five gone ⇒ `undefined`: an empty object is not a choice.
+ *
+ * It does not decide whether the BACKEND exists; that is the host's
+ * `resolveBackend` at spawn time, which refuses in words.
+ */
+export declare function cleanLaunchOpts(v: unknown): LaunchOpts | undefined;
+export type LaunchState = 
+/** Files outstanding. Nothing has been spawned. */
+"waiting"
+/** The gate opened and the session is being made. Written BEFORE the spawn. */
+ | "opening"
+/** The session exists and the first prompt was handed to `deliverPrompt`. */
+ | "done"
+/** It will never open: the deadline passed, or the spawn itself failed. */
+ | "failed"
+/** The user called it off from the phone. */
+ | "canceled";
+/**
+ * One parked "open a session here and run this".
+ *
+ * Carries everything `session.create` carries, because that is precisely what
+ * it is: a create that has not been allowed to happen yet. Storing the fields
+ * rather than the message keeps the persisted file readable and stops a wire
+ * type change from silently rewriting rows that are already on disk.
+ */
+export interface LaunchIntent {
+    /** The create op's ackId. Upsert key — a replayed op must not park twice. */
+    id: string;
+    cwd: string;
+    /** For the UI, so a waiting row can name its repo with no listing loaded. */
+    repoName?: string;
+    /** The first prompt, typed once the session is up. May be empty (a bare open
+     *  that still wants to wait for files someone else's prompt will use). */
+    prompt: string;
+    /** Repo-relative paths that must exist before this may open. */
+    needs: string[];
+    createdAt: number;
+    /** Ms-epoch after which `waiting` becomes `failed`. Absolute, not a duration:
+     *  a host restart must not restart the clock. */
+    deadlineAt: number;
+    state: LaunchState;
+    /** Set when the gate opened. */
+    sessionId?: string;
+    /** The subset of `needs` still absent at the last check — what the row says. */
+    missing?: string[];
+    /** Why it is `failed`/`canceled`, in the words the phone shows. */
+    reason?: string;
+    openedAt?: number;
+    settledAt?: number;
+    cols?: number;
+    rows?: number;
+    title?: string;
+    launch?: unknown;
+    replaceSessionId?: string;
+}
+/** A repo-relative path that stays inside the repo. Rejects absolute paths,
+ *  `..` segments and backslash separators (a Windows-ish path would be one
+ *  opaque filename here, which is not what the sender meant). */
+export declare function safeRel(p: string): boolean;
+/** One line for the row: what it is waiting for, in the user's terms. */
+export declare function describeLaunch(i: LaunchIntent): string;

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

@@ -0,0 +1,102 @@
+/**
+ * A session that is supposed to open, held by the HOST until the files its
+ * first prompt names have actually landed.
+ *
+ * The failure this exists for: "open a session in this repo and look at
+ * `.claude/inbox/shot.jpg`" is assembled on the PHONE. The bytes are parked in
+ * the send queue, the create op is parked behind them in the same lane, and the
+ * whole plan lives in one browser tab on a device with a bad tunnel. If the
+ * upload cannot get through inside the client's 30-minute queue TTL, the upload
+ * fails, everything naming that path is failed with it, and the host — which is
+ * the machine that will actually do the work, and the one that is not on a
+ * train — never learned that any of it was supposed to happen.
+ *
+ * So the INTENT is handed over as early as it can be: the moment the create op
+ * reaches the host, whether or not the picture has. The host writes it down,
+ * persists it across restarts, and from then on it is the host that decides
+ * when the session opens. The phone may go into a tunnel, be killed by the OS,
+ * or be closed for the night; the launch still happens the moment the last file
+ * arrives, because nothing about it depends on that tab any more.
+ *
+ * The rule is pure and lives here so both ends agree on it (the queue sheet has
+ * to be able to say WHY a launch has not fired without asking) and so
+ * `scripts/e2e-launchwait.mjs` can pin it directly.
+ *
+ * At-most-once is by INTENT ID, which is the create op's own ackId: a replayed
+ * op upserts the row rather than adding a second one, exactly as
+ * `schedule.save` does. The host writes the "opening" state BEFORE it spawns,
+ * so a crash between the two can never open the session twice.
+ */
+/**
+ * How long a launch may wait for its files before the host gives up.
+ *
+ * Deliberately much longer than the client's `QUEUE_TTL_MS` (30 min): the whole
+ * point of the handover is that the phone's clock stops mattering. Six hours
+ * covers a commute, a flight, and a night with the laptop shut — and it still
+ * ends, because a session opened tomorrow against a photo taken today is a
+ * surprise, not a feature.
+ */
+export const LAUNCH_WAIT_MS = 6 * 60 * 60_000;
+const EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+const PERM_MODES = ["default", "plan", "acceptEdits", "auto", "dontAsk", "bypassPermissions"];
+/** A model id or alias is one printable token — `opus`, `claude-opus-5[1m]`,
+ *  `ollama/qwen3-coder:30b`. A space or a control character is not a model. */
+const MODEL_RE = /^[\w.:/@[\]+-]{1,120}$/;
+const BACKEND_RE = /^[\w.-]{1,64}$/;
+/**
+ * **A launch somebody chose, as it may be STORED** — on a deferred row
+ * (`Intent.launch`), a schedule's action, a `backlog.add`.
+ *
+ * A `session.create` spends its launch at once; a row keeps it for days and
+ * every tick re-reads it off disk, so the opts are rebuilt from the five fields
+ * `LaunchOpts` names and nothing else rides along. A field that is not one of
+ * them, or not a value the CLI would take, is DROPPED rather than guessed at —
+ * a dropped field is the new-session default, which is what absent always
+ * meant. All five gone ⇒ `undefined`: an empty object is not a choice.
+ *
+ * It does not decide whether the BACKEND exists; that is the host's
+ * `resolveBackend` at spawn time, which refuses in words.
+ */
+export function cleanLaunchOpts(v) {
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        return undefined;
+    const r = v;
+    const out = {};
+    const model = typeof r.model === "string" ? r.model.trim() : "";
+    if (MODEL_RE.test(model))
+        out.model = model;
+    if (EFFORTS.includes(r.effort))
+        out.effort = r.effort;
+    if (PERM_MODES.includes(r.permissionMode))
+        out.permissionMode = r.permissionMode;
+    if (r.remoteControlled === true)
+        out.remoteControlled = true;
+    const backend = typeof r.backend === "string" ? r.backend.trim() : "";
+    if (BACKEND_RE.test(backend))
+        out.backend = backend;
+    return Object.keys(out).length ? out : undefined;
+}
+/** A repo-relative path that stays inside the repo. Rejects absolute paths,
+ *  `..` segments and backslash separators (a Windows-ish path would be one
+ *  opaque filename here, which is not what the sender meant). */
+export function safeRel(p) {
+    const s = p.trim();
+    if (!s || s.startsWith("/") || s.includes("\\") || s.includes("\0"))
+        return false;
+    return !s.split("/").some((seg) => seg === ".." || seg === ".");
+}
+/** One line for the row: what it is waiting for, in the user's terms. */
+export function describeLaunch(i) {
+    const names = (i.missing?.length ? i.missing : i.needs).map((p) => p.split("/").pop() || p);
+    switch (i.state) {
+        case "waiting":
+            return names.length === 1
+                ? `waiting for ${names[0]} to finish uploading`
+                : `waiting for ${names.length} files to finish uploading`;
+        case "opening": return "opening the session…";
+        case "done": return "opened";
+        case "canceled": return i.reason || "called off";
+        default: return i.reason || "did not open";
+    }
+}
+//# sourceMappingURL=launch.js.map