waterplane 0.0.1 → 0.1.6

package/node_modules/@waterplane/shared/dist/wire/messages/hosttools.d.ts

@@ -0,0 +1,338 @@
+import type { ArtifactPolicy } from "../../artifacts.js";
+import type { BudgetVerdict, UsageBudget } from "../../budget.js";
+import type { PeriodState } from "../../period.js";
+import type { BillingStatus } from "../../billing.js";
+import type { CliHealth, HealthRollup } from "../../clihealth.js";
+import type { LocalRuntimeSample } from "../localrt.js";
+import type { Intent } from "../../intent.js";
+import type { ScheduleEntry } from "../../schedule.js";
+import type { SettingsDoc } from "../../settings.js";
+import type { InstallLogDoc } from "../install.js";
+import type { NotificationItem, NotifyPrefs } from "../notify.js";
+import type { BuildParamAnswer } from "../../buildparams.js";
+import type { BuildCandidate } from "../../buildscan.js";
+import type { CaptureBackendInfo, CaptureRun, CaptureTarget } from "../capture.js";
+import type { OnboardJob } from "../onboard.js";
+import type { LimitResumeMode } from "../session.js";
+import type { HaltState } from "../../halt.js";
+import type { MeterSummary } from "../telemetry.js";
+import type { AssessRun, AutoPullConfig, BuildConfig, BuildRun, FanoutRun, PullItem } from "../work.js";
+export type HostToolsMsg = 
+/** The whole synced document. Sent on hello and on `settings.get`. */
+{
+    t: "settings.all";
+    doc: SettingsDoc;
+}
+/**
+ * One setting changed. Broadcast to EVERY socket including the writer's: the
+ * echo is what tells a client its write was accepted, and a client applies it
+ * only when `ts` is newer than what it holds, so the round trip cannot loop.
+ */
+ | {
+    t: "settings.update";
+    key: string;
+    value: string;
+    ts: number;
+    device?: string;
+}
+/**
+ * The install log, whole. Sent on hello, on `install.get`, and broadcast to
+ * EVERY socket whenever a phone reports something new — so a second device
+ * watching the screen sees the first one update itself.
+ */
+ | {
+    t: "install.log";
+    doc: InstallLogDoc;
+}
+/** Transient status note for the client to surface as a toast. */
+ | {
+    t: "toast";
+    text: string;
+}
+/** A new in-app notification (also fired as OS push when subscribed). */
+ | {
+    t: "notification";
+    item: NotificationItem;
+}
+/** Full in-app notification feed (newest first). */
+ | {
+    t: "notification.list";
+    items: NotificationItem[];
+}
+/** Which notification kinds are muted (sent on hello and on every change).
+ *  Sparse: a kind not present takes `NOTIFY_DEFAULT_OFF`'s default. */
+ | {
+    t: "notify.prefs";
+    prefs: NotifyPrefs;
+}
+/**
+ * The usage budget and what it currently says (sent on hello, on every
+ * change, and whenever the verdict itself flips).
+ *
+ * The verdict rides along rather than being re-derived on the phone even
+ * though the rule is shared: the reading it is computed from (`UsageInfo`) is
+ * scraped on the host, and a client that has been offline through a reset
+ * would otherwise explain a queue with a percentage from an hour ago.
+ */
+ | {
+    t: "budget.state";
+    budget: UsageBudget;
+    verdict: BudgetVerdict;
+    /** Each configured period and where it stands (`periodBounds` at send time,
+     *  spend from the host's ledger). Optional: an older host omits it and the
+     *  phone shows today's two windows; an older phone ignores it. Additive,
+     *  `PROTOCOL_VERSION` stays 2. */
+    periods?: PeriodState[];
+}
+/**
+ * Which billing profile this desktop's claude runs under (`shared/billing.ts`):
+ * probed, or the person's override (`source: "setting"`). Sent on hello and on
+ * change, and as the answer to `billing.get` / `billing.set`. Absent from an
+ * older host: the phone treats that as `unknown` and shows today's subscription
+ * chrome. Additive, `PROTOCOL_VERSION` stays 2.
+ */
+ | ({
+    t: "billing.status";
+} & BillingStatus)
+/**
+ * The health board and its rollup — sent on hello and on change (debounced
+ * ~5 s: a health record must not become a frame source on this link).
+ *
+ * The rollup rides along rather than being re-derived on the phone even
+ * though the rule is shared, for the same reason `budget.state` carries its
+ * verdict: every verdict here is relative to a CLOCK, and a client that has
+ * been offline for a day would otherwise render yesterday's misses as today's
+ * alarm. `PROTOCOL_VERSION` did not move for it — this is additive.
+ */
+ | {
+    t: "clihealth";
+    health: CliHealth;
+    rollup: HealthRollup;
+    /** Only from a host running out of a source checkout (`devSource`, host
+     *  `clihealth.ts`): what the phone's "inspect in a session" names, both
+     *  absolute desktop paths — the checkout a session opens in, and the
+     *  state dir holding `clihealth.json` + `clifixtures/`. Absent elsewhere,
+     *  so a packaged install never offers to inspect code it does not have. */
+    source?: {
+        repo: string;
+        stateDir: string;
+    };
+}
+/**
+ * One reading of the local runner. The host keeps NO history of these — the
+ * phone keeps the ring (`shared/wire/localrt.ts`).
+ *
+ * `disabled` is sent once per watch when `WATERPLANE_LOCAL_RUNTIME=0` and the host
+ * will not poll at all. It exists to keep "polling is switched off on this
+ * desktop" apart from "the runner did not answer", which are different
+ * sentences and would otherwise both arrive as `reachable: false`.
+ */
+ | {
+    t: "localrt.sample";
+    sample: LocalRuntimeSample;
+    disabled?: true;
+}
+/** The answer to `localrt.evict`: did the runner unload it? `error` is the
+ *  runner's own sentence (an HTTP status or a fetch failure), never a code —
+ *  there is no vocabulary to translate it into that would say more. */
+ | {
+    t: "localrt.evict";
+    name: string;
+    ok: boolean;
+    error?: string;
+} | {
+    t: "meter.status";
+    summary: MeterSummary;
+}
+/** Global auto-continue-on-usage-limit switch (sent on hello and on change),
+ *  plus the resume queue's host-wide state: `resumingId` is the session being
+ *  resumed right now, and `holdUntil` is set when a resume attempt came back
+ *  still blocked — the limit demonstrably has not reset, so no OTHER session
+ *  may spend an attempt proving the same thing until then. */
+ | {
+    t: "limit.config";
+    enabled: boolean;
+    resumingId: string | null;
+    resumingIds?: string[];
+    holdUntil: number | null;
+    mode?: LimitResumeMode;
+}
+/** The halt latch (sent on hello and on every change). */
+ | {
+    t: "halt.state";
+    halt: HaltState;
+} | {
+    t: "pong";
+}
+/** A repo's build config + recent runs (sent on request and on save). `builds` is the
+ *  MERGED list (committed `.waterplane-shared/builds.json`, then this desktop's own
+ *  `.waterplane/builds.json`, local winning by id). `localIds`: the ids that live in
+ *  the local file — every other entry came with the checkout. Absent from an older
+ *  host: nobody said, so the phone draws no attribution. */
+ | {
+    t: "build.list";
+    repoDir: string;
+    builds: BuildConfig[];
+    runs: BuildRun[];
+    localIds?: string[];
+}
+/** Streamed build output. `full` (on a fresh list/reconnect) = the retained
+ *  tail, replacing the client's buffer; absent/false = a live delta to append. */
+ | {
+    t: "build.output";
+    runId: string;
+    dataB64: string;
+    full?: boolean;
+}
+/** A run's state changed (started / done / failed / cancelled). Artifacts ride the terminal states. */
+ | {
+    t: "build.run";
+    run: BuildRun;
+}
+/** What this repo does with what its builds produce (`artifacts.get`/`.save`). */
+ | {
+    t: "artifacts.config";
+    repoDir: string;
+    policy: ArtifactPolicy;
+}
+/**
+ * The first-app onboarding job, whole, on every step transition (broadcast; additive, so
+ * `PROTOCOL_VERSION` stays). A host-to-phone frame only: starting and resuming are
+ * `POST /api/onboard` / `POST /api/onboard/resume`, and a reconnecting phone reads
+ * `GET /api/onboard` rather than waiting for the next frame. The build's own output rides
+ * `build.output` under `job.buildRunId`.
+ */
+ | {
+    t: "onboard.progress";
+    job: OnboardJob;
+}
+/**
+ * The answer to `build.scan`: build commands this repo already describes.
+ *
+ * `total` is how many were found before the list was capped, so the editor
+ * can say what it is not showing instead of implying the repo has sixty.
+ * An empty `candidates` with `total: 0` is a real answer — this repo's
+ * manifests describe nothing — and is worded as one.
+ */
+ | {
+    t: "build.candidates";
+    repoDir: string;
+    candidates: BuildCandidate[];
+    total: number;
+}
+/**
+ * The answer to `build.options`: what each discovered parameter may be set to.
+ *
+ * One entry per parameter whose options were READ (a static list needs no
+ * round trip — the client already has it on the config). `total` is what the
+ * command produced before the cap, so a cut list can say so; `error` is the
+ * honest alternative to an empty one, because "that command failed" and "this
+ * monorepo has no apps" are opposite facts and only one of them means the
+ * form should offer a typed field instead.
+ */
+ | {
+    t: "build.options";
+    repoDir: string;
+    buildId: string;
+    options: Record<string, BuildParamAnswer>;
+}
+/**
+ * A repo's capture targets + recent runs (sent on request and on save).
+ *
+ * `backends` rides ALONG rather than being asked for separately, because the
+ * sheet's alternative to having the sentence in hand is guessing: it would
+ * draw a button, then learn Playwright is missing, then have to explain a
+ * failure it could have prevented. With availability on the list it says
+ * "web needs Playwright" where the button would be — words, never a greyed-out
+ * control (CLAUDE.md).
+ */
+ | {
+    t: "capture.list";
+    repoDir: string;
+    targets: CaptureTarget[];
+    runs: CaptureRun[];
+    backends: CaptureBackendInfo[];
+}
+/** A run's state changed (started / done / failed / cancelled). The verdict,
+ *  the verification level and the frames ride the terminal states —
+ *  `build.run`'s shape exactly. */
+ | {
+    t: "capture.run";
+    run: CaptureRun;
+}
+/** Streamed capture output. `full` (on a fresh list/reconnect) = the retained
+ *  tail, replacing the client's buffer; absent/false = a live delta to append.
+ *  `build.output`'s contract, deliberately identical. */
+ | {
+    t: "capture.output";
+    runId: string;
+    dataB64: string;
+    full?: boolean;
+}
+/**
+ * One repo's newest assessment run, pushed on every state change.
+ *
+ * Its own snapshot rather than a filter over an existing one, because an
+ * assess row falls out of BOTH of them: `isBacklogRow` wants a prompt payload
+ * and `isBuildRow` wants a build one, so a run would otherwise appear in no
+ * host snapshot at all — invisible for the whole time it works, which is the
+ * failure this rework is against. `run: null` means "this repo has never been
+ * assessed", which is a different sentence from "we could not ask".
+ */
+ | {
+    t: "assess.state";
+    repoDir: string;
+    run: AssessRun | null;
+}
+/** A fan-out run's state (sent on every target transition) — newest runs first in fanout.list. */
+ | {
+    t: "fanout.run";
+    run: FanoutRun;
+} | {
+    t: "fanout.list";
+    runs: FanoutRun[];
+}
+/** A repo's auto-pull rule (sent on request and on save). */
+ | {
+    t: "pull.config";
+    repoDir: string;
+    config: AutoPullConfig;
+}
+/** The whole pull queue, newest first (on hello, on request, after a dismiss). */
+ | {
+    t: "pull.list";
+    items: PullItem[];
+}
+/** One newly-queued file. Broadcast the moment it is detected so an attached
+ *  phone starts fetching without waiting for the next list. */
+ | {
+    t: "pull.new";
+    item: PullItem;
+}
+/** The whole schedule list (on hello, on request, after every mutation and
+ *  every fire — `nextAt` and `lastResult` are host-computed, so the client
+ *  never derives them). */
+ | {
+    t: "schedule.list";
+    entries: ScheduleEntry[];
+}
+/** Every intent this host is holding, newest first. Sent on request; a client
+ *  that was off all night learns from this alone what ran and what did not. */
+ | {
+    t: "intent.list";
+    intents: Intent[];
+}
+/**
+ * One intent changed state. Pushed the moment it does — the `pull.new` /
+ * `delivery.settled` shape, and for the same reason: a row never vanishes on
+ * a state change, it changes verdict, and the phone must be able to see that
+ * happen without asking.
+ */
+ | {
+    t: "intent.changed";
+    intent: Intent;
+} | {
+    t: "error";
+    message: string;
+    context?: string;
+};

package/node_modules/@waterplane/shared/dist/wire/messages/hosttools.js

@@ -0,0 +1,3 @@
+// Host → client: synced settings, builds, captures, assessments, fan-out, pulls, schedules, intents. Member list of `HostMessage` in `../messages.ts`. 
+export {};
+//# sourceMappingURL=hosttools.js.map

package/node_modules/@waterplane/shared/dist/wire/messages/hosttools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosttools.js","sourceRoot":"","sources":["../../../src/wire/messages/hosttools.ts"],"names":[],"mappings":"AAAA,wJAAwJ"}

package/node_modules/@waterplane/shared/dist/wire/messages/hostupdates.d.ts

@@ -0,0 +1,16 @@
+import type { UpdatesRestart, UpdatesStatus } from "../updates.js";
+export type HostUpdatesMsg = 
+/** On connect, after any check and after any apply. */
+{
+    t: "updates.status";
+    status: UpdatesStatus;
+}
+/** The answer to one `updates.apply`, by its `reqId`. `restart` says whether the daemon is
+ *  restarting itself, needs the person to, or nothing changes. */
+ | {
+    t: "updates.result";
+    reqId: string;
+    ok: boolean;
+    message: string;
+    restart: UpdatesRestart;
+};

package/node_modules/@waterplane/shared/dist/wire/messages/hostupdates.js

@@ -0,0 +1,3 @@
+// Host → client: the updates view. A member list of `HostMessage`.
+export {};
+//# sourceMappingURL=hostupdates.js.map

package/node_modules/@waterplane/shared/dist/wire/messages/hostupdates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostupdates.js","sourceRoot":"","sources":["../../../src/wire/messages/hostupdates.ts"],"names":[],"mappings":"AAAA,mEAAmE"}

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

@@ -0,0 +1,25 @@
+/**
+ * The two unions on the wire, and the protocol version they are versioned by.
+ *
+ * Kept apart from the DTOs deliberately: this file changes when a MESSAGE is
+ * added, and the DTO files change when a FIELD is. Both used to be the same
+ * 1,768-line file, which every feature in the project therefore edited.
+ */
+import type { ClientSessionMsg } from "./messages/clientsession.js";
+import type { ClientBacklogMsg } from "./messages/clientbacklog.js";
+import type { ClientHostMsg } from "./messages/clienthost.js";
+import type { ClientWorkMsg } from "./messages/clientwork.js";
+import type { HostCoreMsg } from "./messages/hostcore.js";
+import type { HostToolsMsg } from "./messages/hosttools.js";
+/** 2 is a DELIBERATE bump: `plugin.call`/`plugin.reply`/`plugin.push` are the generic extension
+ *  channel. An older host ignores `plugin.call`, so calls time out and say so. Today the bump only
+ *  triggers the phone's mismatch toast and the host's warning (`routes/system.ts` `onHello`). */
+export declare const PROTOCOL_VERSION = 2;
+/** The intent DTOs travel with the messages that carry them, so no import site
+ *  has to know they live one file over. */
+export type { IntentDraft, IntentPatch } from "./intent.js";
+export type { PeerKind, AuthState } from "./messages/hostcore.js";
+export type ClientMessage = ClientSessionMsg | ClientBacklogMsg | ClientHostMsg | ClientWorkMsg;
+export type HostMessage = HostCoreMsg | HostToolsMsg;
+export declare function encode(msg: ClientMessage | HostMessage): string;
+export declare function decode<T = ClientMessage | HostMessage>(raw: string): T;

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

@@ -0,0 +1,18 @@
+/**
+ * The two unions on the wire, and the protocol version they are versioned by.
+ *
+ * Kept apart from the DTOs deliberately: this file changes when a MESSAGE is
+ * added, and the DTO files change when a FIELD is. Both used to be the same
+ * 1,768-line file, which every feature in the project therefore edited.
+ */
+/** 2 is a DELIBERATE bump: `plugin.call`/`plugin.reply`/`plugin.push` are the generic extension
+ *  channel. An older host ignores `plugin.call`, so calls time out and say so. Today the bump only
+ *  triggers the phone's mismatch toast and the host's warning (`routes/system.ts` `onHello`). */
+export const PROTOCOL_VERSION = 2;
+export function encode(msg) {
+    return JSON.stringify(msg);
+}
+export function decode(raw) {
+    return JSON.parse(raw);
+}
+//# sourceMappingURL=messages.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/wire/messages.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH;;iGAEiG;AACjG,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AA4BlC,MAAM,UAAU,MAAM,CAAC,GAAgC;IACrD,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,MAAM,CAAkC,GAAW;IACjE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;AAC9B,CAAC"}

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

@@ -0,0 +1,145 @@
+/**
+ * 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.
+ */
+export declare const NOTIFICATION_KINDS: readonly ["prompt", "approval", "limit", "burn", "cli", "disk", "undelivered", "backlog", "followup", "health", "agent", "artifact", "image", "plugin", "autofire", "idle", "info"];
+/** 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;
+/** 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;
+    /**
+     * 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;
+}

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

@@ -0,0 +1,96 @@
+/**
+ * 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.
+ */
+export const NOTIFICATION_KINDS = [
+    "prompt", "approval", "limit", "burn", "cli", "disk", "undelivered", "backlog", "followup", "health", "agent", "artifact", "image", "plugin", "autofire", "idle", "info",
+];
+/**
+ * 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);
+}
+/** 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;
+}
+//# 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":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM;CAChK,CAAC;AAcX;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAgC,CAAC,MAAM,CAAC,CAAC;AAExE,iFAAiF;AACjF,MAAM,UAAU,aAAa,CAAC,KAAqC,EAAE,IAAsB;IACzF,MAAM,QAAQ,GAAG,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,OAAO,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACnD,OAAO,CAAC,kBAAkB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IACtE,KAAK,MAAM,CAAC,IAAI,kBAAkB,EAAE,CAAC;QACnC,MAAM,CAAC,GAAI,GAA+B,CAAC,CAAC,CAAC,CAAC;QAC9C,IAAI,OAAO,CAAC,KAAK,SAAS;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}