waterplane 0.0.1 → 0.1.11

package/node_modules/@waterplane/shared/dist/wire/notify.d.ts

@@ -0,0 +1,273 @@
+/**
+ * Which alert kinds may fire at all.
+ *
+ * The two pure functions live with the types because both ends run them: the
+ * host checks inside `notify()` — before the feed entry AND before the push,
+ * since muting only the display still buzzes the phone — and the client checks
+ * to render the switches.
+ */
+/**
+ * Kinds of in-app notification (drives the icon shown, and what may be muted).
+ *
+ * Declared as a list rather than a bare union because it is also the ORDER the
+ * settings UI offers them in, and the set a stored preference is validated
+ * against: a kind removed from this list must not keep muting anything.
+ *
+ * `undelivered` sits next to `limit` on purpose: it fires when the host opened
+ * a session and then could NOT get the prompt into it — a state nothing else
+ * reports, because the op was acked `ok` (accepted) long before the typing
+ * failed. It used to be a broadcast toast, i.e. a sentence shown to whoever
+ * happened to be looking at a phone at that second, for a prompt that was gone.
+ *
+ * `cli` sits right after `limit` for the same reason and is the same class of
+ * alert: something outside this app has changed under it and work is being lost
+ * because of it. It fires when one of the integration points this app reads the
+ * CLI through — the choice-box detector, the hook pipe, the echo probe, the
+ * conversation log (`shared/clihealth.ts`) — stops answering. Every one of those
+ * degrades to null by design and therefore fails in silence, which is how a 22%
+ * delivery-confirmation failure ran for a week with nobody told. This is the
+ * telling.
+ *
+ * `disk` sits right after `cli`, same class: the desktop's home volume is
+ * nearly full (`host/diskwatch.ts`). Not cosmetic — on macOS, low space starts
+ * `cache_delete`, which ENDS apps to empty their caches, Tailscale among them
+ * (2026-10-21: the tunnel died that way, cutting the phone off). Default ON,
+ * once per level crossed, words only: nothing is deleted.
+ *
+ * `burn` sits right after `limit` because it is the limit's early warning: the
+ * weekly figure is climbing faster than a threshold (`shared/burn.ts`). Default
+ * ON — it fires at most once per cooldown and never twice for one stretch, so
+ * it is not `idle`'s class — and it is words only: nothing is paused.
+ *
+ * `approval` sits right after `prompt` because it is the same class: a plugin's
+ * request a person must approve NOW (a vault fingerprint), urgent like a waiting
+ * question. It is its own kind and not `plugin` so the phone can give it the
+ * loud channel while a plugin's ordinary "FYI" stays quiet. Default ON.
+ *
+ * `followup` sits right after `backlog`: a session was flagged for follow up
+ * WITHOUT a tap — its launch option on finishing, or its own agent with a
+ * reason (`followup.ts`). Default ON; a flag set by hand sends none.
+ *
+ * `health` sits after `followup`: a repo's health index (`healthindex.ts`)
+ * made a move unusual for that repo's own past. Default ON — it fires on a
+ * called move only, at most one per repo per week — and words only.
+ *
+ * `agent` sits after `health`: a RUNNING subagent's window passed the person's
+ * line (`agentWindowWarnSetting`), pushed once per agent. Default ON — once per
+ * agent, words only; nothing is stopped or held.
+ *
+ * `weekburn` sits last (a kind added later arrives with its own default): the
+ * week-end burn's once-a-week offer, "pick repos for the rest of the week's
+ * budget" (`weekburn.ts`). Default ON — at most one per week, words only; it
+ * starts nothing, the person's pick is the approval.
+ *
+ * `git` sits after `weekburn` (added 2026-10-25): a pull or push the desktop
+ * ran in one worktree — from the git view or the sync sheet — ended. A FAILED
+ * one is attention and stays until the next run of that verb succeeds or the
+ * person taps done (`gitAttentionKey`); a successful push is information; a
+ * successful pull raises nothing at all. Default ON.
+ *
+ * `exposure` sits last (added 2026-10-26): the exposure watch (`exposurepush.ts`) found a NEW
+ * open alert in a repo that is on the watch — one push per finding, keyed (repo, measure,
+ * subject, version) and spent for good; more than three at once in one repo is a single push.
+ * Critical and high severity are attention, the rest information. Default ON. Words only.
+ */
+export declare const NOTIFICATION_KINDS: readonly ["prompt", "approval", "limit", "burn", "cli", "disk", "undelivered", "backlog", "followup", "health", "agent", "artifact", "image", "plugin", "autofire", "idle", "info", "weekburn", "git", "exposure"];
+/** Kind of in-app notification (drives the icon shown). */
+export type NotificationKind = (typeof NOTIFICATION_KINDS)[number];
+/**
+ * Which kinds the user wants to hear about. Absent kind = the default below.
+ *
+ * Stored sparsely (only the kinds explicitly set) so that a kind added later
+ * arrives with its own default rather than as "muted, because the phone that
+ * wrote this file had never heard of it".
+ */
+export type NotifyPrefs = Partial<Record<NotificationKind, boolean>>;
+/**
+ * Kinds that are OFF unless the user turns them on.
+ *
+ * `idle` is the per-turn "Turn finished" ping, and it is the one kind that
+ * fires on every single turn of every session: half a dozen agents working a
+ * backlog produce a notification a minute, which buries the two kinds that
+ * actually need a human — a waiting question and a usage limit — under a wall
+ * of identical rows. It stays available, it just is not the default.
+ *
+ * `cli` is deliberately NOT here. A health readout that ships muted is not a
+ * readout — the failure it exists to end is precisely one nobody was told about
+ * — and it is rate-limited by construction anyway: it fires on a verdict
+ * TRANSITION into degraded or broken, per signal, never per observation.
+ */
+export declare const NOTIFY_DEFAULT_OFF: readonly NotificationKind[];
+/** Whether a kind may be published, given the user's (possibly absent) prefs. */
+export declare function notifyEnabled(prefs: NotifyPrefs | null | undefined, kind: NotificationKind): boolean;
+/**
+ * Two levels, and only one of them is allowed to ask for a person (owner,
+ * 2026-10-25: the bell read 9+ and stopped meaning anything).
+ *
+ * - `attention` — something waits on the person or broke: it counts on the
+ *   bell's red badge, it is pushed, and it stays until handled (`handled`).
+ * - `info` — a receipt (a run that went fine, a new file): readable in the
+ *   feed, never counted, pushed only when the person asked for that
+ *   (`notify.prefs`' `pushInfo`).
+ */
+export type NotifyLevel = "attention" | "info";
+/** What a run that raised the alert came to, when the call site knows. */
+export type NotifyOutcome = "ok" | "failed";
+/**
+ * The level a kind has when its call site says nothing more. A kind not here
+ * is `info`. `followup` is attention because a session's AGENT chose to raise
+ * it; the launch option's routine "done" flag passes `level: "info"` itself.
+ */
+export declare const ATTENTION_KINDS: readonly NotificationKind[];
+/**
+ * THE one rule for a notification's level, run by the host when it fires and
+ * by the phone for an item an older host sent without one. An explicit level
+ * from the call site wins; then a known outcome (failed ⇒ attention, ok ⇒
+ * info, whatever the kind); then the kind's default.
+ */
+export declare function notifyLevel(kind: NotificationKind, outcome?: NotifyOutcome, explicit?: NotifyLevel): NotifyLevel;
+/** An item's level: the host's stamp, else the same rule over its kind. */
+export declare function levelOf(item: Pick<NotificationItem, "kind" | "level">): NotifyLevel;
+/**
+ * Does this item still need the person — the ONE predicate behind the bell's
+ * count, the cut a tap on it opens, and the per-repo chips (the host derives
+ * `RepoTarget.gitFailed`/`buildFailed` from its own store with it).
+ */
+export declare function needsYou(item: Pick<NotificationItem, "kind" | "level" | "handled">): boolean;
+/** The `key` a failed pull or push of one repo/worktree is filed under —
+ *  spelled once, so the host's resolve and the phone's chip cannot drift. */
+export declare function gitAttentionKey(repoId: string, verb: "pull" | "push"): string;
+/** The `key` a failed build is filed under: one per build ENTRY of one
+ *  repo/worktree, so only the next successful run of that same entry resolves it. */
+export declare function buildAttentionKey(repoId: string, buildId: string): string;
+/** Drop anything that is not a known kind / boolean — the file is hand-editable. */
+export declare function cleanNotifyPrefs(raw: unknown): NotifyPrefs;
+/**
+ * An in-app notification. Mirrors every OS push the host fires, kept in a feed
+ * inside the app so alerts work even without a secure context / granted push.
+ */
+export interface NotificationItem {
+    id: string;
+    ts: number;
+    kind: NotificationKind;
+    title: string;
+    body: string;
+    /** Session to focus when tapped. */
+    sessionId?: string;
+    /** When set, tapping opens this image in the annotator. */
+    image?: {
+        repoId: string;
+        relPath: string;
+    };
+    /** When set, tapping downloads this artifact (outbox file, e.g. an APK).
+     *  `mtime` is part of the file's IDENTITY, not decoration: the download queue
+     *  keys a record on repo + path + mtime, so a payload without it makes every
+     *  future build of `app.apk` the same row — and a tap on next week's
+     *  notification hands over last week's bytes. */
+    file?: {
+        repoId: string;
+        relPath: string;
+        name: string;
+        size: number;
+        mtime?: number;
+    };
+    /**
+     * When set, tapping opens the Backlog on exactly these rows.
+     *
+     * The *Backlog groomed* notification is the only writer. Without it the phone
+     * had to match the repo by BASENAME out of the notification's title, which is
+     * a guess the moment two roots hold a `myapp` — and it had no way at all to
+     * name the rows the sentence was about, so the tap opened the whole list for
+     * the reader to re-derive the cut from. `ids` is the merged rows, which is
+     * what CLAUDE.md's *a count on a control is a filter* asks for: the number in
+     * the sentence and the cut the tap opens come from one place.
+     */
+    backlog?: {
+        cwd: string;
+        ids: string[];
+    };
+    /**
+     * The id of the plugin that posted this. Filled by the HOST from the
+     * registry entry, never taken from the plugin's own words. A tap opens that
+     * plugin's screen (a vault ask has no session to focus).
+     */
+    plugin?: string;
+    /**
+     * Where a tap lands for an alert that names no session, file, image, backlog
+     * cut or plugin of its own (a health move, a burning week).
+     * Every tap has to land on a page that says more about what was tapped; an
+     * alert with none of these opens the feed on its own row (`openNotif`).
+     * Absent on an older host — never a guess.
+     */
+    open?: NotifyOpen;
+    /**
+     * `attention` or `info` (`notifyLevel`). ABSENT on an older host: the phone
+     * derives it with `levelOf`, never a second way.
+     */
+    level?: NotifyLevel;
+    /**
+     * What an attention item is ABOUT, so its cause going away can resolve it:
+     * `gitAttentionKey`, `buildAttentionKey`, `prompt:<sessionId>`,
+     * `followup:<sessionId>`, `undelivered:<sessionId>`. Absent = only the
+     * person's done clears it.
+     */
+    key?: string;
+    /**
+     * Set once an attention item is dealt with: by the person's `done`, or by
+     * its cause going away (`by: "resolved"`, `note` saying how — "fixed by the
+     * 14:02 push"). A handled item stays in the feed and stops counting.
+     */
+    handled?: NotifyHandled;
+    /**
+     * A stable key: a later notification with the same tag REPLACES the earlier one in the OS tray (the APK posts
+     * under `tag`; web push passes it to `showNotification`). A plugin's own tag is namespaced by the HOST
+     * (`plugin-<id>-<tag>`), so no plugin can replace another's. The in-app feed keeps every item.
+     */
+    tag?: string;
+}
+/**
+ * A screen a tapped alert opens. `repohealth`: that repo's health chart;
+ * `tokens`: the token-stats sheet (the week's burn); `plugin`: that in-repo
+ * extension's screen. The phone ignores a `to` it does not
+ * know and falls back to the alert's own row in the feed.
+ */
+export type NotifyOpen = {
+    to: "repohealth";
+    repoId: string;
+} | {
+    to: "tokens";
+} | {
+    to: "plugin";
+    id: string;
+}
+/** That repo's (or worktree's) git view, showing the stored failure. */
+ | {
+    to: "git";
+    repoId: string;
+    verb?: "pull" | "push";
+}
+/** That repo's (or worktree's) build sheet, on the failed entry. */
+ | {
+    to: "build";
+    repoId: string;
+    buildId?: string;
+}
+/** That repo's readings sheet, on the exposure watch region. */
+ | {
+    to: "setup";
+    repoId: string;
+};
+/** How an attention item was dealt with. */
+export interface NotifyHandled {
+    at: number;
+    by: "person" | "resolved";
+    /** One line, for `resolved`: what took it away. */
+    note?: string;
+}
+/**
+ * A notification as the Android shell hands it back on a tap: `notif:<item JSON>`
+ * (`ShellLinkService.openAppIntent`, for an alert with no session or plugin).
+ * Null when the string is not one, or the JSON is not an item — never a
+ * half-read item.
+ */
+export declare function notifFromShell(s: string): NotificationItem | null;

package/node_modules/@waterplane/shared/dist/wire/notify.js

@@ -0,0 +1,174 @@
+/**
+ * Which alert kinds may fire at all.
+ *
+ * The two pure functions live with the types because both ends run them: the
+ * host checks inside `notify()` — before the feed entry AND before the push,
+ * since muting only the display still buzzes the phone — and the client checks
+ * to render the switches.
+ */
+/**
+ * Kinds of in-app notification (drives the icon shown, and what may be muted).
+ *
+ * Declared as a list rather than a bare union because it is also the ORDER the
+ * settings UI offers them in, and the set a stored preference is validated
+ * against: a kind removed from this list must not keep muting anything.
+ *
+ * `undelivered` sits next to `limit` on purpose: it fires when the host opened
+ * a session and then could NOT get the prompt into it — a state nothing else
+ * reports, because the op was acked `ok` (accepted) long before the typing
+ * failed. It used to be a broadcast toast, i.e. a sentence shown to whoever
+ * happened to be looking at a phone at that second, for a prompt that was gone.
+ *
+ * `cli` sits right after `limit` for the same reason and is the same class of
+ * alert: something outside this app has changed under it and work is being lost
+ * because of it. It fires when one of the integration points this app reads the
+ * CLI through — the choice-box detector, the hook pipe, the echo probe, the
+ * conversation log (`shared/clihealth.ts`) — stops answering. Every one of those
+ * degrades to null by design and therefore fails in silence, which is how a 22%
+ * delivery-confirmation failure ran for a week with nobody told. This is the
+ * telling.
+ *
+ * `disk` sits right after `cli`, same class: the desktop's home volume is
+ * nearly full (`host/diskwatch.ts`). Not cosmetic — on macOS, low space starts
+ * `cache_delete`, which ENDS apps to empty their caches, Tailscale among them
+ * (2026-10-21: the tunnel died that way, cutting the phone off). Default ON,
+ * once per level crossed, words only: nothing is deleted.
+ *
+ * `burn` sits right after `limit` because it is the limit's early warning: the
+ * weekly figure is climbing faster than a threshold (`shared/burn.ts`). Default
+ * ON — it fires at most once per cooldown and never twice for one stretch, so
+ * it is not `idle`'s class — and it is words only: nothing is paused.
+ *
+ * `approval` sits right after `prompt` because it is the same class: a plugin's
+ * request a person must approve NOW (a vault fingerprint), urgent like a waiting
+ * question. It is its own kind and not `plugin` so the phone can give it the
+ * loud channel while a plugin's ordinary "FYI" stays quiet. Default ON.
+ *
+ * `followup` sits right after `backlog`: a session was flagged for follow up
+ * WITHOUT a tap — its launch option on finishing, or its own agent with a
+ * reason (`followup.ts`). Default ON; a flag set by hand sends none.
+ *
+ * `health` sits after `followup`: a repo's health index (`healthindex.ts`)
+ * made a move unusual for that repo's own past. Default ON — it fires on a
+ * called move only, at most one per repo per week — and words only.
+ *
+ * `agent` sits after `health`: a RUNNING subagent's window passed the person's
+ * line (`agentWindowWarnSetting`), pushed once per agent. Default ON — once per
+ * agent, words only; nothing is stopped or held.
+ *
+ * `weekburn` sits last (a kind added later arrives with its own default): the
+ * week-end burn's once-a-week offer, "pick repos for the rest of the week's
+ * budget" (`weekburn.ts`). Default ON — at most one per week, words only; it
+ * starts nothing, the person's pick is the approval.
+ *
+ * `git` sits after `weekburn` (added 2026-10-25): a pull or push the desktop
+ * ran in one worktree — from the git view or the sync sheet — ended. A FAILED
+ * one is attention and stays until the next run of that verb succeeds or the
+ * person taps done (`gitAttentionKey`); a successful push is information; a
+ * successful pull raises nothing at all. Default ON.
+ *
+ * `exposure` sits last (added 2026-10-26): the exposure watch (`exposurepush.ts`) found a NEW
+ * open alert in a repo that is on the watch — one push per finding, keyed (repo, measure,
+ * subject, version) and spent for good; more than three at once in one repo is a single push.
+ * Critical and high severity are attention, the rest information. Default ON. Words only.
+ */
+export const NOTIFICATION_KINDS = [
+    "prompt", "approval", "limit", "burn", "cli", "disk", "undelivered", "backlog", "followup", "health", "agent", "artifact", "image", "plugin", "autofire", "idle", "info", "weekburn", "git", "exposure",
+];
+/**
+ * Kinds that are OFF unless the user turns them on.
+ *
+ * `idle` is the per-turn "Turn finished" ping, and it is the one kind that
+ * fires on every single turn of every session: half a dozen agents working a
+ * backlog produce a notification a minute, which buries the two kinds that
+ * actually need a human — a waiting question and a usage limit — under a wall
+ * of identical rows. It stays available, it just is not the default.
+ *
+ * `cli` is deliberately NOT here. A health readout that ships muted is not a
+ * readout — the failure it exists to end is precisely one nobody was told about
+ * — and it is rate-limited by construction anyway: it fires on a verdict
+ * TRANSITION into degraded or broken, per signal, never per observation.
+ */
+export const NOTIFY_DEFAULT_OFF = ["idle"];
+/** Whether a kind may be published, given the user's (possibly absent) prefs. */
+export function notifyEnabled(prefs, kind) {
+    const explicit = prefs?.[kind];
+    if (typeof explicit === "boolean")
+        return explicit;
+    return !NOTIFY_DEFAULT_OFF.includes(kind);
+}
+/**
+ * The level a kind has when its call site says nothing more. A kind not here
+ * is `info`. `followup` is attention because a session's AGENT chose to raise
+ * it; the launch option's routine "done" flag passes `level: "info"` itself.
+ */
+export const ATTENTION_KINDS = ["prompt", "approval", "cli", "disk", "undelivered", "followup"];
+/**
+ * THE one rule for a notification's level, run by the host when it fires and
+ * by the phone for an item an older host sent without one. An explicit level
+ * from the call site wins; then a known outcome (failed ⇒ attention, ok ⇒
+ * info, whatever the kind); then the kind's default.
+ */
+export function notifyLevel(kind, outcome, explicit) {
+    if (explicit === "attention" || explicit === "info")
+        return explicit;
+    if (outcome === "failed")
+        return "attention";
+    if (outcome === "ok")
+        return "info";
+    return ATTENTION_KINDS.includes(kind) ? "attention" : "info";
+}
+/** An item's level: the host's stamp, else the same rule over its kind. */
+export function levelOf(item) {
+    return item.level === "attention" || item.level === "info" ? item.level : notifyLevel(item.kind);
+}
+/**
+ * Does this item still need the person — the ONE predicate behind the bell's
+ * count, the cut a tap on it opens, and the per-repo chips (the host derives
+ * `RepoTarget.gitFailed`/`buildFailed` from its own store with it).
+ */
+export function needsYou(item) {
+    return levelOf(item) === "attention" && !item.handled;
+}
+/** The `key` a failed pull or push of one repo/worktree is filed under —
+ *  spelled once, so the host's resolve and the phone's chip cannot drift. */
+export function gitAttentionKey(repoId, verb) {
+    return `git:${repoId}:${verb}`;
+}
+/** The `key` a failed build is filed under: one per build ENTRY of one
+ *  repo/worktree, so only the next successful run of that same entry resolves it. */
+export function buildAttentionKey(repoId, buildId) {
+    return `build:${repoId}:${buildId}`;
+}
+/** Drop anything that is not a known kind / boolean — the file is hand-editable. */
+export function cleanNotifyPrefs(raw) {
+    const out = {};
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return out;
+    for (const k of NOTIFICATION_KINDS) {
+        const v = raw[k];
+        if (typeof v === "boolean")
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * A notification as the Android shell hands it back on a tap: `notif:<item JSON>`
+ * (`ShellLinkService.openAppIntent`, for an alert with no session or plugin).
+ * Null when the string is not one, or the JSON is not an item — never a
+ * half-read item.
+ */
+export function notifFromShell(s) {
+    if (!s.startsWith("notif:"))
+        return null;
+    try {
+        const v = JSON.parse(s.slice("notif:".length));
+        if (!v || typeof v !== "object" || typeof v.id !== "string" || typeof v.title !== "string" || typeof v.kind !== "string")
+            return null;
+        return { ...v, body: typeof v.body === "string" ? v.body : "", ts: typeof v.ts === "number" ? v.ts : Date.now() };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=notify.js.map

package/node_modules/@waterplane/shared/dist/wire/notify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.js","sourceRoot":"","sources":["../../src/wire/notify.ts"],"names":[],"mappings":"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"}

package/node_modules/@waterplane/shared/dist/wire/notifylink.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The Android background link: a socket that is only there to raise alerts.
+ *
+ * The APK's native `ShellLinkService` holds its own WebSocket so notifications
+ * arrive with the app closed, and acts on exactly three inbound frames. Every
+ * other frame the host sends it wakes the phone's radio and CPU only to be
+ * thrown away — and that socket never sleeps. So the host marks it, and sends
+ * it the allow-list below and nothing else (`server/clients.ts`'s `send`).
+ *
+ * Two ways a socket becomes one, the explicit one winning:
+ * - `hello.role: "notify"` (an APK built after 2026-10-13);
+ * - a `User-Agent` starting `okhttp/` at the upgrade — the WebView sends a
+ *   Chrome UA, OkHttp its own. That is what covers every APK already installed,
+ *   which says nothing about its role and does not update with the bundle.
+ */
+/** The one role a socket may declare today. Absent ⇒ a full client. */
+export type ClientRole = "notify";
+/**
+ * What a notify link is sent. The three `ShellLinkService.onFrame` reads, plus
+ * `pong` — sent only when the socket ASKED with `{t:"ping"}`, so a link that
+ * keeps a JSON heartbeat is not torn down for lack of an answer. No
+ * `notification.list`: the service posts each `notification` as it comes and
+ * dedupes by tag; it never replays a feed.
+ */
+export declare const NOTIFY_LINK_FRAMES: ReadonlySet<string>;
+/** The client frames a notify link may send. Anything else (an attach above
+ *  all) is ignored, so the link can never count as somebody watching. */
+export declare const NOTIFY_LINK_INBOUND: ReadonlySet<string>;
+/** May a socket in this role be sent a frame of this type? */
+export declare function roleAllows(role: ClientRole | undefined, t: string): boolean;
+/** May a socket in this role send this client frame? */
+export declare function roleAccepts(role: ClientRole | undefined, t: string): boolean;
+/** The role guessed at upgrade, before any frame: OkHttp is the native link. */
+export declare function roleFromUserAgent(ua: string | string[] | undefined): ClientRole | undefined;
+/** The role after `hello`: an explicit one wins, else whatever the upgrade said. */
+export declare function roleAfterHello(declared: unknown, upgraded: ClientRole | undefined): ClientRole | undefined;

package/node_modules/@waterplane/shared/dist/wire/notifylink.js

@@ -0,0 +1,44 @@
+/**
+ * The Android background link: a socket that is only there to raise alerts.
+ *
+ * The APK's native `ShellLinkService` holds its own WebSocket so notifications
+ * arrive with the app closed, and acts on exactly three inbound frames. Every
+ * other frame the host sends it wakes the phone's radio and CPU only to be
+ * thrown away — and that socket never sleeps. So the host marks it, and sends
+ * it the allow-list below and nothing else (`server/clients.ts`'s `send`).
+ *
+ * Two ways a socket becomes one, the explicit one winning:
+ * - `hello.role: "notify"` (an APK built after 2026-10-13);
+ * - a `User-Agent` starting `okhttp/` at the upgrade — the WebView sends a
+ *   Chrome UA, OkHttp its own. That is what covers every APK already installed,
+ *   which says nothing about its role and does not update with the bundle.
+ */
+/**
+ * What a notify link is sent. The three `ShellLinkService.onFrame` reads, plus
+ * `pong` — sent only when the socket ASKED with `{t:"ping"}`, so a link that
+ * keeps a JSON heartbeat is not torn down for lack of an answer. No
+ * `notification.list`: the service posts each `notification` as it comes and
+ * dedupes by tag; it never replays a feed.
+ */
+export const NOTIFY_LINK_FRAMES = new Set(["notification", "authRequired", "pull.new", "pong"]);
+/** The client frames a notify link may send. Anything else (an attach above
+ *  all) is ignored, so the link can never count as somebody watching. */
+export const NOTIFY_LINK_INBOUND = new Set(["hello", "ping"]);
+/** May a socket in this role be sent a frame of this type? */
+export function roleAllows(role, t) {
+    return role !== "notify" || NOTIFY_LINK_FRAMES.has(t);
+}
+/** May a socket in this role send this client frame? */
+export function roleAccepts(role, t) {
+    return role !== "notify" || NOTIFY_LINK_INBOUND.has(t);
+}
+/** The role guessed at upgrade, before any frame: OkHttp is the native link. */
+export function roleFromUserAgent(ua) {
+    const s = Array.isArray(ua) ? ua[0] : ua;
+    return typeof s === "string" && /^okhttp\//i.test(s) ? "notify" : undefined;
+}
+/** The role after `hello`: an explicit one wins, else whatever the upgrade said. */
+export function roleAfterHello(declared, upgraded) {
+    return declared === "notify" ? "notify" : upgraded;
+}
+//# sourceMappingURL=notifylink.js.map

package/node_modules/@waterplane/shared/dist/wire/notifylink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifylink.js","sourceRoot":"","sources":["../../src/wire/notifylink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;AAErH;yEACyE;AACzE,MAAM,CAAC,MAAM,mBAAmB,GAAwB,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;AAEnF,8DAA8D;AAC9D,MAAM,UAAU,UAAU,CAAC,IAA4B,EAAE,CAAS;IAChE,OAAO,IAAI,KAAK,QAAQ,IAAI,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,WAAW,CAAC,IAA4B,EAAE,CAAS;IACjE,OAAO,IAAI,KAAK,QAAQ,IAAI,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,iBAAiB,CAAC,EAAiC;IACjE,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9E,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,QAAiB,EAAE,QAAgC;IAChF,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AACrD,CAAC"}

package/node_modules/@waterplane/shared/dist/wire/onboard.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The first-app onboarding job on the wire (`docs/analysis/first-app-plan.md`, WP6).
+ *
+ * One host-side job (`packages/host/src/onboard.ts`) turns three answers and one consent screen
+ * into a repo, a build and a session. The phone reads the PLAN before the consent screen
+ * (`GET /api/onboard/plan`), starts the job (`POST /api/onboard`), and follows it as
+ * `onboard.progress` frames over the one socket, or `GET /api/onboard` after a reconnect. Every
+ * step is a sentence; a stopped step names its fix.
+ */
+/** Which journey: an Android app (template `android-hello`) or a web page (`web-hello`). */
+export type OnboardPath = "android" | "web";
+/** The person's answers from the three questions. */
+export interface OnboardAnswers {
+    /** The app name; becomes the folder `<root>/<name>` and the package segment. */
+    name: string;
+    path: OnboardPath;
+    /** "Describe what you want": becomes the new session's FIRST prompt, after the first build. */
+    description?: string;
+    /** "Set this repo up for waterplane" (default on): the setup checklist's one-tap fixes, as one step. */
+    setup?: boolean;
+}
+/**
+ * The consent screen's ticks, one per line it showed. The host REFUSES a start whose plan needs a
+ * line that is not `true` (`repo` always; `toolchain` and `signingKey` when the plan lists them).
+ * `session: false` is allowed: that step is then skipped, said so, and nothing runs `claude`.
+ * `installApps` is the phone's own (the allow-list and Android's setting); the host records it.
+ */
+export interface OnboardConsent {
+    repo?: boolean;
+    /** Download and install the toolchain AND accept Google's SDK licence on the person's behalf. */
+    toolchain?: boolean;
+    signingKey?: boolean;
+    installApps?: boolean;
+    session?: boolean;
+}
+export type OnboardConsentId = "repo" | "toolchain" | "signingKey" | "installApps" | "session";
+/** One line of the consent screen: shown only if it applies to this desktop. */
+export interface OnboardConsentLine {
+    id: OnboardConsentId;
+    /** What it does, in one sentence the screen shows as is. */
+    what: string;
+    /** Where it lands on this desktop (a folder), when it writes anything. */
+    where?: string;
+    /** About how much is downloaded (derived, an estimate shown as "about"). */
+    bytes?: number;
+    /** The licence text, for the line that accepts one. */
+    link?: string;
+    /** The start is refused without this tick. */
+    required: boolean;
+    /** Acted on by the phone, not the desktop. */
+    phone?: boolean;
+}
+export type OnboardStepId = "probe" | "toolchain" | "scaffold" | "signing-key" | "setup" | "build" | "session";
+export type OnboardStepStatus = "pending" | "running" | "done" | "skipped" | "failed" | "needs-you" | "needs-consent";
+export interface OnboardStep {
+    id: OnboardStepId;
+    status: OnboardStepStatus;
+    /** What the step does, said before it runs ("First build: the slow one, about 5 minutes"). */
+    what: string;
+    /** What happened, or why it stopped. */
+    note?: string;
+    /** `needs-you`: the exact command the person must run; `failed`: the do-it-yourself command.
+     *  Never run by the host. */
+    command?: string;
+    startedAt?: number;
+    endedAt?: number;
+}
+/** What `GET /api/onboard/plan` answers: the steps that apply here, and the consent lines. */
+export interface OnboardPlan {
+    ok: boolean;
+    /** The refusal in words (bad name, folder exists, broken key…); `ok:false`. */
+    error?: string;
+    path: OnboardPath;
+    /** The cleaned name and the folder it becomes. */
+    name: string;
+    folder: string;
+    /** Android only. */
+    packageId?: string;
+    steps: Array<{
+        id: OnboardStepId;
+        needed: boolean;
+        what: string;
+    }>;
+    consent: OnboardConsentLine[];
+    /** What the session's first prompt will be (the description), or the suggestion offered. */
+    firstPrompt?: string;
+    suggestedPrompt: string;
+    /** Set when claude is NOT signed in on this desktop: the sentence saying how to sign in from
+     *  the phone. The job still runs; its session would stop at the sign-in screen. Absent when
+     *  signed in, when the answer could not be read, and from an older desktop. */
+    signIn?: string;
+    /** One-shot token for `POST /api/onboard` `{ answers, consent, confirm }`, bound to this path and
+     *  to the consent ids listed above (`host/confirmgate.ts`). Absent from an older desktop. */
+    confirm?: string;
+}
+export type OnboardJobState = "running" | "done" | "stopped";
+export interface OnboardJob {
+    id: string;
+    state: OnboardJobState;
+    answers: OnboardAnswers;
+    consent: OnboardConsent;
+    name: string;
+    folder: string;
+    packageId?: string;
+    steps: OnboardStep[];
+    /** Set once the scaffold step made it. */
+    repoDir?: string;
+    repoId?: string;
+    /** The first build's run (`build.output`/`build.run` frames carry the same id). */
+    buildRunId?: string;
+    /** Repo-relative path of what the build left for the phone (the APK or the HTML in the outbox). */
+    artifact?: string;
+    /** The session opened in the new repo, once known; `intentId` when it opens through the store. */
+    sessionId?: string;
+    intentId?: string;
+    suggestedPrompt: string;
+    /** One sentence: where the job is. */
+    summary: string;
+    createdAt: number;
+    updatedAt: number;
+}