waterplane 0.0.1 → 0.1.6

package/packages/host/dist/server/shutdown.js

@@ -0,0 +1,135 @@
+import { logTag, envName } from "@waterplane/shared";
+import { restartReason } from "../restartnote.js";
+import { runPendingRestore } from "../cli/selfupdate.js";
+export function installShutdown(ctx) {
+    /**
+     * Flush the ack ledger before we go.
+     *
+     * `npm run restart` is `launchctl kickstart -k` — an immediate SIGTERM — and the
+     * ledger's low-frequency writes are debounced on an UNREF'd timer, so without
+     * this the last few hundred milliseconds of receipts die with the process. That
+     * is precisely the window that matters: the phone fires a 12-repo `fanout.run`,
+     * the host starts it, the socket drops before `op.ack` lands, a restart happens
+     * — and a forgotten verdict turns the client's retry into a second sweep.
+     *
+     * Op verdicts are already written synchronously (acks.ts), so this covers the
+     * debounced `input.ack` records and any op whose sync write raced the signal.
+     * Exit behaviour is otherwise unchanged: node's default for both signals is to
+     * terminate, so we terminate — installing a handler suppresses that default, and
+     * a daemon that ignores SIGTERM would make `npm run restart` hang.
+     */
+    for (const sig of ["SIGTERM", "SIGINT"]) {
+        process.on(sig, () => {
+            // Tell every phone first, while the sockets are still up: without it a
+            // restart is a dropped socket that looks like the tunnel (`host.restarting`).
+            // `reason` is what the restarting caller posted first (`restartnote.ts`), else absent.
+            try {
+                const reason = restartReason();
+                ctx.broadcast({ t: "host.restarting", at: Date.now(), ...(reason ? { reason } : {}) });
+            }
+            catch { /* shutdown must never throw */ }
+            try {
+                ctx.acks.flush();
+            }
+            catch { /* shutdown must never throw */ }
+            // Debounced ~2 s, and `npm run restart` is routine — without this the last
+            // observations before every restart die with the process, which for a record
+            // whose whole job is to notice a slow drift is the wrong seconds to lose.
+            try {
+                ctx.cliHealthStore.flush();
+            }
+            catch { /* shutdown must never throw */ }
+            try {
+                ctx.sentLogStore.flush();
+            }
+            catch { /* shutdown must never throw */ }
+            try {
+                ctx.installLog.flush();
+            }
+            catch { /* shutdown must never throw */ }
+            try {
+                ctx.netstats.flush();
+            }
+            catch { /* shutdown must never throw */ }
+            // The per-model context-window marks. Debounced ~3 s, and losing the one
+            // that just moved means every context graph for that model draws on the
+            // wrong axis until another long conversation re-earns it.
+            try {
+                ctx.sessions.flushContextWindows();
+            }
+            catch { /* shutdown must never throw */ }
+            try {
+                ctx.tokenStats.flush();
+            }
+            catch { /* shutdown must never throw */ }
+            try {
+                ctx.usageLog.flush();
+            }
+            catch { /* shutdown must never throw */ }
+            try {
+                ctx.usageSources.flush();
+            }
+            catch { /* shutdown must never throw */ }
+            try {
+                ctx.settings.flush();
+            }
+            catch { /* shutdown must never throw */ }
+            // Open questions are debounced nowhere — but a row created in the last
+            // milliseconds before a restart is exactly the one whose answer nobody has
+            // yet, so flush it with the rest.
+            try {
+                ctx.openDeliveries.flush();
+            }
+            catch { /* shutdown must never throw */ }
+            // Belt and braces: the intent store writes synchronously on every mutation
+            // precisely so that `op.ack ok` means "on disk" with no exit hook involved.
+            // A flush here can therefore never be load-bearing — and that is exactly why
+            // it is safe to keep, and why `e2e-intent.mjs` uses `kill -9`, which would
+            // skip it, rather than a signal this handler could paper over.
+            try {
+                ctx.intents.flush();
+            }
+            catch { /* shutdown must never throw */ }
+            // Every plugin stream ends first (cause "socket", nothing sent — the sockets go with the
+            // process), so a producer hears `close` before its plugin's `deactivate()`.
+            try {
+                ctx.plugins.streams.endAll();
+            }
+            catch { /* shutdown must never throw */ }
+            // Plugins' `deactivate()` — started, never awaited: a plugin cannot hold
+            // the exit, and anything it must keep it writes as it goes.
+            try {
+                ctx.plugins.deactivateAll();
+            }
+            catch { /* shutdown must never throw */ }
+            // Plugins' child processes go last, just before exit (`shutdown()`, synchronous —
+            // opencode's per-session `serve` children): they own the session state on disk, so
+            // nothing above may depend on them being alive.
+            try {
+                ctx.plugins.shutdownAll();
+            }
+            catch { /* shutdown must never throw */ }
+            // A phone-tapped rollback owes the older state back (`cli/selfupdate.ts`): AFTER every flush above,
+            // so nothing rewrites it, and before the supervisor starts the older version on it.
+            try {
+                const r = runPendingRestore();
+                if (r)
+                    console.error(`${logTag} rollback: ${r}`);
+            }
+            catch { /* shutdown must never throw */ }
+            process.exit(0);
+        });
+    }
+    // A single bad request or dropped push must never take the daemon down.
+    process.on("unhandledRejection", (err) => console.error(`${logTag} unhandledRejection`, err));
+    process.on("uncaughtException", (err) => {
+        // A port we can't bind is fatal, not swallowable — exit cleanly so we never
+        // linger as a half-bound zombie (the thing that broke restarts).
+        if (err?.code === "EADDRINUSE") {
+            console.error(`${logTag} port ${ctx.PORT} already in use — exiting. Another host already running? From a checkout: \`npm run restart\`; otherwise stop whatever holds the port, or set ${envName("PORT")} to a free one.`);
+            process.exit(1);
+        }
+        console.error(`${logTag} uncaughtException`, err);
+    });
+}
+//# sourceMappingURL=shutdown.js.map

package/packages/host/dist/server/shutdown.js.map

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

package/packages/host/dist/server/wsops.d.ts

@@ -0,0 +1,44 @@
+import type { WebSocket, WebSocketServer } from "ws";
+import { type SendStamp } from "@waterplane/shared";
+import type { InputVerdict, OpVerdict } from "../routes/types.js";
+import type { ServerCtx } from "./ctx.js";
+/** What `main()` learned about this machine's addresses before binding, and
+ *  hands every socket in `welcome`. */
+export interface WelcomeNet {
+    ip: string | null;
+    tsBin: string | null;
+    tsDns: string | null;
+    httpsUrl: string | null;
+    boundLan: string[];
+}
+/**
+ * The largest client→host frame `main()`'s `WebSocketServer` accepts (ws
+ * enforces it on the INFLATED size, so a deflate bomb is bounded too; past it
+ * the socket closes 1009). The biggest legitimate frame is `settings.set` at
+ * `MAX_SETTING_BYTES` (1 MiB), at most ~6 MiB even if every byte were
+ * `\u`-escaped; files and audio go over HTTP. 16 MiB is that with headroom —
+ * ws's own default is 100 MiB, buffered whole and then `JSON.parse`d.
+ */
+export declare const WS_MAX_PAYLOAD: number;
+/**
+ * How often the host pings each socket at the protocol level (`liveness.ts`):
+ * a socket that answers neither of two pings in a row is terminated, so a dead
+ * phone is let go within two to three of these. 0 turns the ping off.
+ * `WATERPLANE_WS_PING_MS`; the liveness e2e boots with a few hundred ms.
+ */
+export declare const WS_PING_MS: number;
+/**
+ * Send-buffer depth past which a socket gets no more PTY deltas, only one full
+ * replay once it drains (`liveness.ts`'s `ptyFrameAction`). 1 MiB is dozens of
+ * deflated repaints — far more than a live phone ever has in flight.
+ * `WATERPLANE_WS_PTY_BACKLOG_BYTES`; 0 turns the guard off.
+ */
+export declare const WS_PTY_BACKLOG_BYTES: number;
+export declare function createWsOps(ctx: ServerCtx): {
+    opsInFlight: Map<string, Promise<OpVerdict>>;
+    inputsInFlight: Map<string, Promise<InputVerdict>>;
+    sendOpAck: (ws: WebSocket, ackId: string, v: OpVerdict) => void;
+    durableOp: (ws: WebSocket, ackId: string | undefined, exec: () => OpVerdict | Promise<OpVerdict>, stamp?: SendStamp) => void;
+    containRepoDir: (dir: unknown) => Promise<string | null>;
+    wireWsConnections: (wss: WebSocketServer, net: WelcomeNet) => void;
+};

package/packages/host/dist/server/wsops.js

@@ -0,0 +1,313 @@
+/**
+ * The socket's side of at-most-once: the in-flight maps, `durableOp` and its
+ * `op.ack`, the ONE gate on a directory a client named (`containRepoDir`), and
+ * each `/ws` server's connection handler.
+ *
+ * Moved verbatim out of `main.ts` (M2 of the host split, see
+ * docs/notes/host-architecture.md). Every main-scope name is read as
+ * `ctx.<name>` at CALL time. `new AckLedger`/`new NetStats` and the
+ * `new WebSocketServer(…)` stay in `main.ts`; the two in-flight maps are this
+ * factory's closure state (memory only, on purpose — see each).
+ *
+ * `durableOp`: thrown ⇒ NOT remembered (a host fault gets a real second
+ * attempt), `ok: false` ⇒ remembered. `containRepoDir`: never loosen it.
+ */
+import { bootClock } from "./http.js";
+import { existsSync } from "node:fs";
+import { PROTOCOL_VERSION, decode, isClientFrame, logTag, envName, roleFromUserAgent } from "@waterplane/shared";
+import { WIRE, recordWireFrame } from "../wirerecord.js";
+import { requestPeerKind, isProxied } from "../net.js";
+import { checkRequestOrigin } from "../origin.js";
+import { tokenFromRequest } from "../auth.js";
+import { lanIdentity } from "../lanid.js";
+import { hostName } from "../net.js";
+import { discoverTargets } from "../repos.js";
+import { inRoot, realResolve } from "../scaffold.js";
+import { backendInfos, recheckUnavailableBackends } from "../backends/index.js";
+import { envInt } from "../env.js";
+import { pingTick } from "./liveness.js";
+/**
+ * The largest client→host frame `main()`'s `WebSocketServer` accepts (ws
+ * enforces it on the INFLATED size, so a deflate bomb is bounded too; past it
+ * the socket closes 1009). The biggest legitimate frame is `settings.set` at
+ * `MAX_SETTING_BYTES` (1 MiB), at most ~6 MiB even if every byte were
+ * `\u`-escaped; files and audio go over HTTP. 16 MiB is that with headroom —
+ * ws's own default is 100 MiB, buffered whole and then `JSON.parse`d.
+ */
+export const WS_MAX_PAYLOAD = 16 * 1024 * 1024;
+/**
+ * How often the host pings each socket at the protocol level (`liveness.ts`):
+ * a socket that answers neither of two pings in a row is terminated, so a dead
+ * phone is let go within two to three of these. 0 turns the ping off.
+ * `WATERPLANE_WS_PING_MS`; the liveness e2e boots with a few hundred ms.
+ */
+export const WS_PING_MS = Math.max(0, envInt("WS_PING_MS", 20_000));
+/**
+ * Send-buffer depth past which a socket gets no more PTY deltas, only one full
+ * replay once it drains (`liveness.ts`'s `ptyFrameAction`). 1 MiB is dozens of
+ * deflated repaints — far more than a live phone ever has in flight.
+ * `WATERPLANE_WS_PTY_BACKLOG_BYTES`; 0 turns the guard off.
+ */
+export const WS_PTY_BACKLOG_BYTES = Math.max(0, envInt("WS_PTY_BACKLOG_BYTES", 1024 * 1024));
+export function createWsOps(ctx) {
+    /** In-flight durable ops, keyed by ackId. The ledger only learns the verdict
+     *  once the op settles, so without this a retry arriving DURING an async op
+     *  (a fan-out spends a while validating dirs and spawning) would find nothing
+     *  remembered and start the whole thing a second time. Memory only — a crash
+     *  mid-op must not leave a persisted "already did it" for work that never ran. */
+    const opsInFlight = new Map();
+    /**
+     * Verified compose deliveries in flight, keyed by ackId — the `session.input`
+     * twin of `opsInFlight`, and load-bearing for exactly the same reason.
+     *
+     * A raw input write is synchronous, so a duplicate ackId could never race it. A
+     * `submit` delivery takes SECONDS (boot wait, echo check, Return proof), which
+     * opens a window the phone's retry lands in constantly: the client's receipt
+     * deadline can expire while the host is still typing. Without this a retry would
+     * find nothing remembered (the ledger only learns the verdict once delivery
+     * settles) and start a SECOND deliverPrompt — two copies of the same prompt, the
+     * one outcome the whole ack scheme exists to prevent. A repeat joins the
+     * delivery already running and gets its verdict.
+     *
+     * Memory only, like `opsInFlight`: a crash mid-delivery must not leave a
+     * persisted "already did it" for a prompt that never ran.
+     */
+    const inputsInFlight = new Map();
+    function sendOpAck(ws, ackId, v) {
+        ctx.send(ws, { t: "op.ack", ackId, ok: v.ok, reason: v.reason, sessionId: v.sessionId, runId: v.runId, launchId: v.launchId, intentId: v.intentId, filed: v.filed });
+    }
+    /**
+     * Run a durable action AT MOST ONCE per ackId, and always answer the caller.
+     *
+     * The phone queues these the same way it queues text (web/outbox.ts) and
+     * re-sends the SAME ackId when it never saw the receipt — so "start a session
+     * here", "fan out to these 12 repos" and "run this build" need exactly the
+     * guarantee session.input already had. A repeat of a known ackId is re-ACKed
+     * with the STORED verdict and `exec` is not run again.
+     *
+     * Without an ackId nothing changes: `exec` runs, no receipt goes out, and a
+     * synchronous throw still surfaces as { t: "error" } via the socket's handler.
+     *
+     * A THROWN op is deliberately not remembered — that's a host fault, not a
+     * completed action, and a client retry should get a real second attempt rather
+     * than a permanent "no".
+     */
+    function durableOp(ws, ackId, exec, stamp) {
+        if (!ackId) {
+            void Promise.resolve(exec());
+            return;
+        }
+        const seen = ctx.acks.get(ackId);
+        if (seen) {
+            ctx.netstats.noteAckReplay();
+            sendOpAck(ws, ackId, { ok: seen.ok, reason: seen.reason, sessionId: seen.sessionId, runId: seen.runId, launchId: seen.launchId, intentId: seen.intentId, filed: seen.filed });
+            return;
+        }
+        const already = opsInFlight.get(ackId);
+        if (already) {
+            ctx.netstats.noteAckReplay();
+            void already.then((v) => sendOpAck(ws, ackId, v));
+            return;
+        }
+        // The ledger was lost at boot and this unknown ackId says it was first sent
+        // BEFORE that: it may already have run, and nothing here can tell. Refused,
+        // never run, and remembered so every retry hears the same (acks.ts).
+        const lostRefusal = ctx.acks.preLossRefusal(stamp);
+        if (lostRefusal) {
+            const v = { ok: false, reason: lostRefusal };
+            ctx.acks.remember(ackId, { ...v, op: true });
+            sendOpAck(ws, ackId, v);
+            return;
+        }
+        let started;
+        try {
+            started = Promise.resolve(exec());
+        }
+        catch (e) {
+            sendOpAck(ws, ackId, { ok: false, reason: String(e?.message || e) });
+            return;
+        }
+        const settled = started.then(
+        // `op: true` marks this as an expensive verdict: acks.ts persists it
+        // synchronously (a restart must not land inside a debounce window) and
+        // protects it from cap eviction by keystroke-frequency input receipts.
+        (v) => { ctx.acks.remember(ackId, { ...v, op: true }); return v; }, (e) => ({ ok: false, reason: String(e?.message || e) }));
+        opsInFlight.set(ackId, settled);
+        void settled.then((v) => sendOpAck(ws, ackId, v));
+        void settled.finally(() => opsInFlight.delete(ackId));
+    }
+    /**
+     * The one gate on a directory a CLIENT named.
+     *
+     * `session.create` spawns `claude` in this path and `build.run` executes a
+     * shell command in it — both are arbitrary code execution, which is exactly why
+     * the Tailscale boundary exists (SECURITY.md). But that boundary is about WHO
+     * may talk to the daemon and says nothing about WHERE: past `origin.ts` and
+     * `auth.ts` the cwd arrived as an opaque string and went straight to
+     * `sessions.create()`, so a LAN peer holding a token — or simply a client bug
+     * that sent a stale path — could start an agent in any directory on the
+     * machine. Every other path a client names is contained (`files.ts`, `git.ts`,
+     * `scaffold.ts`, and `fanout.run`, which validates its dirs against
+     * `discoverTargets()`); this was the one asymmetry.
+     *
+     * Two ways to pass, cheapest first:
+     *   • inside `ROOT` — one realpath compare, the ordinary case, costing nothing;
+     *   • otherwise a DISCOVERED worktree. `git worktree add /somewhere/else` is
+     *     legitimate and the repo listing already offers it, so refusing it outright
+     *     would break a path the app itself hands the user. The scan runs only for
+     *     the out-of-root minority.
+     *
+     * Returns the resolved directory, or null. Callers refuse rather than guess:
+     * the only safe answer to "I do not know where this is" is to start nothing
+     * there.
+     */
+    async function containRepoDir(dir) {
+        if (typeof dir !== "string" || !dir.trim())
+            return null;
+        const within = inRoot(ctx.ROOT, dir);
+        if (within && existsSync(within))
+            return within;
+        const resolved = realResolve(dir);
+        try {
+            const known = await discoverTargets(ctx.ROOT);
+            if (known.some((t) => realResolve(t.worktreePath) === resolved))
+                return resolved;
+        }
+        catch { /* no listing ⇒ no exception to the root rule */ }
+        return null;
+    }
+    /** The `connection` handler of each `/ws` server. The `new WebSocketServer(…)`
+     *  (and its permessage-deflate options) stays in `main()`'s `attachWs`, which
+     *  calls this right after constructing it; `net` is the facts `main()` read
+     *  about this machine's addresses before binding, handed out in `welcome`. */
+    function wireWsConnections(wss, net) {
+        const { ip, tsBin, tsDns, httpsUrl, boundLan } = net;
+        wss.on("connection", (ws, req) => {
+            // A WebSocket is exempt from the same-origin policy, so without this any
+            // web page open in a browser that can reach us could drive the daemon —
+            // and the daemon spawns `claude`. Refuse anything not from our own origin.
+            const originOk = checkRequestOrigin(req.headers, { proxied: isProxied(req.headers) });
+            if (!originOk.ok) {
+                console.warn(`${logTag} refused ws upgrade: ${originOk.reason}. If this is your own hostname, set ${envName("ALLOWED_HOSTS")}.`);
+                try {
+                    ws.close(1008, "origin not allowed");
+                }
+                catch { /* already closing */ }
+                return;
+            }
+            const kind = requestPeerKind(req.socket.remoteAddress, req.headers);
+            // Cookie (browser), else the `waterplane-tok.<tok>` subprotocol (the Android
+            // shell, whose cross-site cookie is withheld) — `tokenFromRequest`.
+            const tok = tokenFromRequest(req.headers);
+            const device = ctx.auth.deviceFor(tok, kind);
+            // Gate untrusted (LAN, or Tailscale when that toggle is on) sockets: without
+            // a valid token, tell the client it needs the password and drop the socket.
+            if (ctx.auth.needsToken(kind) && !device) {
+                ctx.send(ws, { t: "authRequired", enabled: ctx.auth.isEnabled(), kind });
+                try {
+                    ws.close();
+                }
+                catch { /* already closing */ }
+                return;
+            }
+            // A passive token never gets the socket (`passive.ts`): everything it may
+            // do is on the HTTP allowlist. Closed with a reason, not `authRequired` —
+            // a password would not help, the PIN does.
+            if (ctx.auth.passive.restricted(device)) {
+                try {
+                    ws.close(4403, "passive device");
+                }
+                catch { /* already closing */ }
+                return;
+            }
+            ctx.clients.add(ws);
+            ctx.netstats.noteSocketOpen(ws, kind);
+            ctx.attached.set(ws, new Set());
+            ctx.wsKind.set(ws, kind);
+            if (tok)
+                ctx.wsToken.set(ws, tok);
+            if (device)
+                ctx.wsDevice.set(ws, device.id);
+            // The APK's background link (OkHttp) is sent only what it acts on — from
+            // the very first frame, so `welcome` below is already filtered for it.
+            // An explicit `hello.role` overrides this; it is the fallback for APKs
+            // already installed, which declare nothing.
+            const role = roleFromUserAgent(req.headers["user-agent"]);
+            if (role)
+                ctx.wsRole.set(ws, role);
+            // `hostId` is the LAN identity's, so a phone can tell which desktop a
+            // socket landed on; `deviceId` only when this socket IS a ledger device.
+            let hostId;
+            try {
+                hostId = lanIdentity(ctx.ROOT).hostId;
+            }
+            catch { /* unwritable root ⇒ absent, never a made-up id */ }
+            ctx.send(ws, { t: "welcome", protocol: PROTOCOL_VERSION, bootId: ctx.BOOT_ID, tailscaleIp: ip, tailscaleBin: tsBin, tailscaleDns: tsDns, httpsUrl, lanIps: boundLan, port: ctx.PORT, root: ctx.ROOT, tmux: true, clientKind: kind, auth: ctx.authStateFor(kind), hostId, hostName: hostName(), deviceId: device?.id, startedAt: bootClock.startedAt, readyAt: bootClock.readyAt });
+            // Which binaries this host can drive, and what each of them can be ASKED.
+            // It rides beside `welcome` rather than in the `hello` arm because it is a
+            // fact about the HOST, like every field of that frame — and because the
+            // client's backend picker is GATED on this frame having arrived: a phone
+            // talking to an older host never receives it and therefore does not draw
+            // the picker at all (not greyed — absent). That gate is what stops a new
+            // phone asking an old host for a backend it cannot spawn, so the frame
+            // must not be conditional on anything the client sends first.
+            // Additive: `PROTOCOL_VERSION` did not move for it, and a client that has never heard
+            // of `backends` ignores an unknown `t` exactly as the wire requires.
+            ctx.send(ws, { t: "backends", list: backendInfos() });
+            // A backend that said "unavailable" at boot is asked again when a phone
+            // connects (at most every 10 s) and the list re-sent only if it changed.
+            void recheckUnavailableBackends(10_000).then((changed) => { if (changed)
+                ctx.broadcast({ t: "backends", list: backendInfos() }); });
+            ws.on("message", (raw) => {
+                // A revoke, a relock or a password change closes this socket
+                // asynchronously; a frame that still arrives from it is dropped before
+                // it is even decoded or logged (`clients.ts`, `socketAuthorized`).
+                if (!ctx.socketAuthorized(ws))
+                    return;
+                try {
+                    const msg = decode(raw.toString());
+                    if (WIRE)
+                        recordWireFrame("in", msg);
+                    // `null`, a string, `{}` — answered in words, never thrown at `msg.t`.
+                    // An unknown but well-formed `t` passes: the router ignores it.
+                    if (!isClientFrame(msg)) {
+                        ctx.send(ws, { t: "error", message: "not a client frame: expected a JSON object with a string \"t\"", context: "message" });
+                        return;
+                    }
+                    ctx.handleClientMessage(ws, msg);
+                }
+                catch (err) {
+                    ctx.send(ws, { t: "error", message: String(err), context: "message" });
+                }
+            });
+            // The host's own liveness check (`liveness.ts`): a protocol-level ping the
+            // phone's browser answers by itself, and `terminate()` — not `close()`,
+            // whose handshake a dead peer never completes — once two in a row go
+            // unanswered. That fires the close handler below, so the socket leaves
+            // `clients` and stops counting as somebody watching its sessions.
+            let missed = 0;
+            ws.on("pong", () => { missed = 0; });
+            const pinger = WS_PING_MS > 0 ? setInterval(() => {
+                const tick = pingTick(missed);
+                missed = tick.missed;
+                if (tick.action === "terminate") {
+                    clearInterval(pinger);
+                    ws.terminate();
+                    return;
+                }
+                try {
+                    ws.ping();
+                }
+                catch { /* not open any more; close/error clears this */ }
+            }, WS_PING_MS) : undefined;
+            // Close code first: 1006 (abnormal, no close frame) is the tunnel dying
+            // under the socket, 1001 is the phone backgrounding it. They look the same
+            // from the app and mean opposite things about the link.
+            // Its plugin streams end with it (cause "socket", nothing sent): the phone reopens on reconnect.
+            ws.on("close", (code) => { clearInterval(pinger); ctx.netstats.noteSocketClose(ws, code); ctx.clients.delete(ws); ctx.plugins.streams.socketGone(ws); ctx.recomputeWatched(); });
+            ws.on("error", () => { clearInterval(pinger); ctx.clients.delete(ws); ctx.plugins.streams.socketGone(ws); ctx.recomputeWatched(); });
+        });
+    }
+    return { opsInFlight, inputsInFlight, sendOpAck, durableOp, containRepoDir, wireWsConnections };
+}
+//# sourceMappingURL=wsops.js.map

package/packages/host/dist/server/wsops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wsops.js","sourceRoot":"","sources":["../../src/server/wsops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,aAAa,EAAkB,MAAM,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACjI,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAGhF,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAYzC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;AACpE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,sBAAsB,EAAE,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC;AAE7F,MAAM,UAAU,WAAW,CAAC,GAAc;IACxC;;;;sFAIkF;IAClF,MAAM,WAAW,GAAG,IAAI,GAAG,EAA8B,CAAC;IAE1D;;;;;;;;;;;;;;;OAeG;IACH,MAAM,cAAc,GAAG,IAAI,GAAG,EAAiC,CAAC;IAEhE,SAAS,SAAS,CAAC,EAAa,EAAE,KAAa,EAAE,CAAY;QAC3D,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IACvK,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,SAAS,SAAS,CAAC,EAAa,EAAE,KAAyB,EAAE,IAA0C,EAAE,KAAiB;QACxH,IAAI,CAAC,KAAK,EAAE,CAAC;YAAC,KAAK,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;YAAC,OAAO;QAAC,CAAC;QACrD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,IAAI,EAAE,CAAC;YAAC,GAAG,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;YAAC,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;YAAC,OAAO;QAAC,CAAC;QAClO,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,OAAO,EAAE,CAAC;YAAC,GAAG,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC;YAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;YAAC,OAAO;QAAC,CAAC;QACzG,4EAA4E;QAC5E,4EAA4E;QAC5E,qEAAqE;QACrE,MAAM,WAAW,GAAG,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QACnD,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,CAAC,GAAc,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;YACxD,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7C,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;YACxB,OAAO;QACT,CAAC;QACD,IAAI,OAA2B,CAAC;QAChC,IAAI,CAAC;YACH,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAE,CAAW,EAAE,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;YAChF,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI;QAC1B,qEAAqE;QACrE,uEAAuE;QACvE,uEAAuE;QACvE,CAAC,CAAC,EAAE,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAClE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAE,CAAW,EAAE,OAAO,IAAI,CAAC,CAAC,EAAE,CAAc,CAChF,CAAC;QACF,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAChC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;QAClD,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACxD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,KAAK,UAAU,cAAc,CAAC,GAAY;QACxC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;YAAE,OAAO,IAAI,CAAC;QACxD,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACrC,IAAI,MAAM,IAAI,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAC;QAChD,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC9C,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,QAAQ,CAAC;gBAAE,OAAO,QAAQ,CAAC;QACnF,CAAC;QAAC,MAAM,CAAC,CAAC,gDAAgD,CAAC,CAAC;QAC5D,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;kFAG8E;IAC9E,SAAS,iBAAiB,CAAC,GAAoB,EAAE,GAAe;QAC9D,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,GAAG,CAAC;QACrD,GAAG,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,EAAa,EAAE,GAAoB,EAAE,EAAE;YAC3D,yEAAyE;YACzE,wEAAwE;YACxE,2EAA2E;YAC3E,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACtF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,wBAAwB,QAAQ,CAAC,MAAM,uCAAuC,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;gBACjI,IAAI,CAAC;oBAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,qBAAqB,CAAC,CAAC;gBAC7E,OAAO;YACT,CAAC;YACD,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,aAAa,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;YACpE,6EAA6E;YAC7E,oEAAoE;YACpE,MAAM,GAAG,GAAG,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC1C,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAC7C,6EAA6E;YAC7E,4EAA4E;YAC5E,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACzC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;gBACzE,IAAI,CAAC;oBAAC,EAAE,CAAC,KAAK,EAAE,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,qBAAqB,CAAC,CAAC;gBACnD,OAAO;YACT,CAAC;YACD,0EAA0E;YAC1E,0EAA0E;YAC1E,2CAA2C;YAC3C,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBACxC,IAAI,CAAC;oBAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,qBAAqB,CAAC,CAAC;gBACzE,OAAO;YACT,CAAC;YACD,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACpB,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YACtC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;YAChC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YACzB,IAAI,GAAG;gBAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;YAClC,IAAI,MAAM;gBAAE,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;YAC5C,yEAAyE;YACzE,uEAAuE;YACvE,uEAAuE;YACvE,4CAA4C;YAC5C,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;YAC1D,IAAI,IAAI;gBAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YACnC,sEAAsE;YACtE,yEAAyE;YACzE,IAAI,MAA0B,CAAC;YAC/B,IAAI,CAAC;gBAAC,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,kDAAkD,CAAC,CAAC;YAC3G,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC;YACnX,0EAA0E;YAC1E,2EAA2E;YAC3E,wEAAwE;YACxE,yEAAyE;YACzE,yEAAyE;YACzE,yEAAyE;YACzE,uEAAuE;YACvE,8DAA8D;YAC9D,sFAAsF;YACtF,qEAAqE;YACrE,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,CAAC,CAAC;YACtD,wEAAwE;YACxE,yEAAyE;YACzE,KAAK,0BAA0B,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,GAAG,IAAI,OAAO;gBAAE,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACpI,EAAE,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE;gBACvB,6DAA6D;gBAC7D,uEAAuE;gBACvE,mEAAmE;gBACnE,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,EAAE,CAAC;oBAAE,OAAO;gBACtC,IAAI,CAAC;oBACH,MAAM,GAAG,GAAG,MAAM,CAAU,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;oBAC5C,IAAI,IAAI;wBAAE,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;oBACrC,uEAAuE;oBACvE,gEAAgE;oBAChE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;wBACxB,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,gEAAgE,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;wBAC5H,OAAO;oBACT,CAAC;oBACD,GAAG,CAAC,mBAAmB,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;gBACnC,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;gBACzE,CAAC;YACH,CAAC,CAAC,CAAC;YACH,2EAA2E;YAC3E,wEAAwE;YACxE,qEAAqE;YACrE,uEAAuE;YACvE,kEAAkE;YAClE,IAAI,MAAM,GAAG,CAAC,CAAC;YACf,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACrC,MAAM,MAAM,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE;gBAC/C,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;gBAC9B,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;gBACrB,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;oBAAC,aAAa,CAAC,MAAM,CAAC,CAAC;oBAAC,EAAE,CAAC,SAAS,EAAE,CAAC;oBAAC,OAAO;gBAAC,CAAC;gBACnF,IAAI,CAAC;oBAAC,EAAE,CAAC,IAAI,EAAE,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,gDAAgD,CAAC,CAAC;YAC/E,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC3B,wEAAwE;YACxE,2EAA2E;YAC3E,wDAAwD;YACxD,iGAAiG;YACjG,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAY,EAAE,EAAE,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YACzL,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACvI,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB,EAAE,CAAC;AAClG,CAAC"}

package/packages/host/dist/sessionSearch.d.ts

@@ -0,0 +1,46 @@
+import type { HistoryEntry, SessionSearchMatch, SessionSearchResult } from "@waterplane/shared";
+/** Context lines each side of a hit, so a match reads in place. */
+export declare const SEARCH_CONTEXT_LINES = 2;
+/** Hits kept per session. `total` still reports the real count. */
+export declare const SEARCH_HITS_PER_SESSION = 40;
+/** What the scan needs to know about a session, and nothing more. */
+export interface SearchTarget {
+    id: string;
+    title: string;
+    cwd: string;
+    running: boolean;
+}
+/**
+ * Find `query` in `body`, appending to `matches` and counting into `total`.
+ *
+ * Returns the new total. Matches stop being COLLECTED at the cap but keep being
+ * COUNTED, so the sheet can say "40 of 300" rather than quietly implying the
+ * search found forty things.
+ */
+export declare function scanText(body: string, query: string, matches: SessionSearchMatch[], total: number, turn?: SessionSearchMatch["turn"]): number;
+/** Every turn of a session's recorded history, prompt and output alike. */
+export declare function scanHistory(history: HistoryEntry[], query: string): {
+    matches: SessionSearchMatch[];
+    total: number;
+};
+/**
+ * The PROMPTS of a session's recorded history — what was sent INTO it, alone.
+ *
+ * Not `scanHistory` with a flag: the two answer different questions and the
+ * difference is the whole point. A turn's output is hundreds of lines the CLI
+ * wrote, so a word common to both ("test", a filename, a branch) buries the one
+ * or two lines a person typed under the reply to them. Searching what you asked
+ * for is the more common question of the two, which is why it is the sheet's
+ * default.
+ *
+ * Every recorded kind counts — a slash command and a filed backlog item were
+ * both sent into the session by a person — and each hit still carries its turn
+ * label, so the snippet says which kind it was.
+ */
+export declare function scanPrompts(history: HistoryEntry[], query: string): {
+    matches: SessionSearchMatch[];
+    total: number;
+};
+/** Wrap a scan's output as the result the wire carries. Null when nothing hit —
+ *  a session with no matches is absent from the list, not present and empty. */
+export declare function searchResult(t: SearchTarget, matches: SessionSearchMatch[], total: number): SessionSearchResult | null;