waterplane 0.0.1 → 0.1.6

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

@@ -0,0 +1,36 @@
+/** Where the preset lands, repo-relative. Named in full everywhere it is mentioned. */
+export declare const VISUAL_SKILL_REL = ".claude/skills/visual-check/SKILL.md";
+/**
+ * The preset's text.
+ *
+ * The port is templated at write time rather than hardcoded, because the
+ * one-liner in it is the whole point of the section it sits in: an agent that
+ * has to guess the port goes and looks at the image instead, which is the
+ * expensive thing this file exists to avoid. When the port IS the documented
+ * default we say so, so a reader who moved their host knows the number came from
+ * somewhere rather than from nowhere.
+ *
+ * ── Why the frontmatter says who wrote it ──────────────────────────────────
+ *
+ * `generated-by:` is not decoration. A repo may hold a check over its own
+ * `.claude/skills/` — waterplane's `tools/claudemd.test.mjs` asserts that every
+ * directory there is named in the "which skill to load" table — and this preset
+ * lands in exactly that directory. It is not a routing entry for an area of that
+ * codebase; it is a machine-written artifact aimed at the agent working in the
+ * repo. So it SAYS it is one, and such a check exempts it on that marker. A
+ * marker on the artifact still works the day a second preset exists; a list of
+ * names inside the checker does not.
+ */
+export declare function visualSkillText(port?: number): string;
+/**
+ * Write the preset into a worktree if it is not already there.
+ *
+ * Additive and idempotent, like every other fix: an existing file is left
+ * exactly as it is — someone may have edited the measured baseline into it, and
+ * overwriting that would delete the one part of the file that was ever true
+ * about this machine.
+ */
+export declare function writeVisualCheckSkill(worktree: string): {
+    written: boolean;
+    relPath: string;
+};

package/packages/host/dist/visualskill.js

@@ -0,0 +1,230 @@
+/**
+ * The instruction preset the capture loop ships with: how an agent working in a
+ * repo should LOOK at a screenshot without leaving it resident in a conversation
+ * that will re-send it on every remaining turn.
+ *
+ * Why this is a file written into a repo rather than a paragraph somewhere in
+ * waterplane: the agent that needs the rule is the `claude` process running in THAT
+ * repo, and it reads that repo's `.claude/skills/`. A rule kept on the host is a
+ * rule the agent never sees.
+ *
+ * Why it is a compliance FIX and not a scaffold: `scaffold.ts` only ever seeds a
+ * NEW repo and `setupwatch.ts` never writes into one at all, so the only
+ * sanctioned path that puts a file into an existing repo is a fix the user taps
+ * — additive, idempotent, and never a delete (`compliance.ts`'s header). This
+ * follows the `gemini-script` fix exactly: mkdir, write only when absent, and
+ * say which of the two happened.
+ *
+ * Why it is offered only where capture is configured: configuring a capture
+ * target IS the opt-in. A repo with no `.waterplane/capture.json` targets has nothing
+ * to look at and must never be nagged about how to look at it.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { env } from "./env.js";
+import { BRAND, envName } from "@waterplane/shared";
+/** Where the preset lands, repo-relative. Named in full everywhere it is mentioned. */
+export const VISUAL_SKILL_REL = ".claude/skills/visual-check/SKILL.md";
+/** The port this daemon answers on — same resolution as `main.ts`. */
+const DEFAULT_PORT = 8770;
+function hostPort() {
+    const n = Number(env("PORT") || DEFAULT_PORT);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_PORT;
+}
+/**
+ * The preset's text.
+ *
+ * The port is templated at write time rather than hardcoded, because the
+ * one-liner in it is the whole point of the section it sits in: an agent that
+ * has to guess the port goes and looks at the image instead, which is the
+ * expensive thing this file exists to avoid. When the port IS the documented
+ * default we say so, so a reader who moved their host knows the number came from
+ * somewhere rather than from nowhere.
+ *
+ * ── Why the frontmatter says who wrote it ──────────────────────────────────
+ *
+ * `generated-by:` is not decoration. A repo may hold a check over its own
+ * `.claude/skills/` — waterplane's `tools/claudemd.test.mjs` asserts that every
+ * directory there is named in the "which skill to load" table — and this preset
+ * lands in exactly that directory. It is not a routing entry for an area of that
+ * codebase; it is a machine-written artifact aimed at the agent working in the
+ * repo. So it SAYS it is one, and such a check exempts it on that marker. A
+ * marker on the artifact still works the day a second preset exists; a list of
+ * names inside the checker does not.
+ */
+export function visualSkillText(port = hostPort()) {
+    const portNote = port === DEFAULT_PORT
+        ? `${DEFAULT_PORT} is ${BRAND.name}'s documented default port; \`${envName("PORT")}\` moves it.`
+        : `This host answers on ${port} (\`${envName("PORT")}\`); the documented default is ${DEFAULT_PORT}.`;
+    return `---
+name: visual-check
+description: How to look at a screenshot during a development loop without permanently polluting the conversation's context — what a frame actually costs on every remaining turn, and the five-rung ladder from a deterministic check, through a text verdict and the phone's gallery, to looking at the image yourself. Load BEFORE asking to see a screenshot, before assembling a contact sheet, and before handing frames to a subagent.
+generated-by: ${BRAND.name} capture (packages/host/src/visualskill.ts) — a machine-written preset, not one of this repo's hand-authored skills. Edit it freely; nothing overwrites it.
+---
+
+# Looking at a screen without paying for it on every turn
+
+This repo has capture targets configured, so frames are cheap to produce. Frames
+are not cheap to KEEP. This file is about the difference.
+
+## The cost, stated once
+
+Every turn re-sends the whole conversation. An image is therefore not paid for
+once — it is paid for again on every remaining turn of the session.
+
+An image costs roughly \`(width x height) / 750\` tokens:
+
+| frame | approx. tokens |
+| --- | --- |
+| 390x844 phone | ~440 |
+| 1440x900 desktop | ~1,730 |
+| a six-frame viewport/theme matrix | ~6,000 |
+
+Multiply by the turns that come after it. A 6k matrix dropped at turn 10 of a
+40-turn session costs about 180k tokens, not 6k. That is the number to have in
+mind, and it is the reason the rest of this file is a ladder rather than a
+preference.
+
+## The ladder
+
+Five rungs. Use the cheapest one that actually answers the question you have.
+
+### 1. A deterministic check — zero tokens, and it cannot hallucinate
+
+Most questions in a development loop are mechanical, not aesthetic, and this
+rung answers all of them:
+
+- **Pixel diff** — did anything change at all?
+- **Blank/variance floor and shot-score** — is this a real frame, or a white
+  rectangle?
+- **DOM / uiautomator / OCR anchor** — is the expected text on the screen?
+- **Console and network sidecar** — did it error while rendering?
+
+"Did my change take effect", "is the button there", "did it blow up" are all
+answered here, for nothing, by something that cannot be wrong in the confident
+way a model can.
+
+### 2. A text verdict into the conversation (~50 tokens)
+
+\`\`\`
+verified:anchor · score 91 · 390x844 dark · console: clean · net: clean
+\`\`\`
+
+That line is capture's DEFAULT output, and it is the rung to prefer. It carries
+the level of verification, whether the frame scored as a real screen, the
+geometry, and whether anything errored — at roughly one percent of the price of
+the frame it describes.
+
+### 3. The human's eyes, through the phone gallery — zero model tokens
+
+Artifacts written to \`.claude/outbox/\` are looked at over HTTP. **They never
+enter a conversation at all.** The person asking for this work is already
+holding the phone, and their judgement on "does this look right" beats any
+model's.
+
+A contact sheet belongs HERE and never in a conversation: six tiles still cost
+about 1,730 tokens as one image, and each tile is then too small to read
+anything on. A grid is a thing for a human to scan, not a thing to pay context
+for.
+
+### 4. A subagent
+
+A subagent burns the image in its own window and returns a sentence. Worth it
+when there are many frames, or the parent session is long-lived, or the
+judgement is specifiable in a prompt.
+
+Break-even is roughly:
+
+\`\`\`
+subagent_baseline / (image_tokens x remaining_turns)
+\`\`\`
+
+A single 440-token phone frame late in a session does not clear it. A six-frame
+matrix early in one clears it easily.
+
+Two costs the rule usually forgets:
+
+- **A subagent pays a fresh system prompt and tool schemas before it looks at
+  anything.** That baseline is the numerator above and it is not small. Measure
+  it (see below) rather than assuming it.
+- **A subagent that is not told what changed answers vaguely but confidently**,
+  which is worse than not asking. Give it the diff, the expectation, and the
+  question — not just the frame.
+
+### 5. Look at it yourself
+
+Legitimate for one small frame in a short session, or inside a tight visual loop
+— look, nudge 4px, look. This is not a sin; it is simply the most expensive rung,
+and it should be a choice rather than a reflex.
+
+### Never
+
+An image left resident in a long session with no active reason. Once it has
+answered its question it goes on costing the same as it did when it was useful.
+
+## Naming a file so it resolves
+
+Name any artifact by its FULL path every time you mention it —
+\`.claude/outbox/capture-home-2026-09-13-a1b2.png\`, never a bare filename and
+never "the PNG in the outbox". That path is what the reader turns into the
+picture; a bare name only resolves when the listing holds exactly one media file
+by that name, and never in prose.
+
+## Triggering a capture without spending tokens on it
+
+Ask the host for the run and read the verdict out of the response body. Nothing
+here puts an image in the conversation:
+
+\`\`\`bash
+curl -sS -X POST http://127.0.0.1:${port}/api/repos/<repoId>/capture/run \\
+  -H 'content-type: application/json' \\
+  -d '{"target":"<targetId>","wait":true}'
+\`\`\`
+
+${portNote}
+
+\`<repoId>\` comes from \`GET http://127.0.0.1:${port}/api/repos\`; \`<targetId>\` is the \`id\` of an
+entry in this repo's \`${BRAND.stateDirName}/capture.json\`.
+
+With \`"wait":true\` the response carries the verdict line, the sidecar path and
+the frame paths. That is rung 2 for the price of an HTTP round trip: you get the
+~50-token sentence, and the image stays on disk where rung 3 can reach it.
+
+## Measure the baseline before trusting the arithmetic
+
+**The numbers above are estimates, and this repo checks rather than remembers.**
+Before leaning on the rung-4 break-even, measure the real subagent baseline on
+THIS machine: start a fresh subagent and read its FIRST-turn input tokens, which
+is the whole cost it pays before it has looked at anything.
+
+Two places already hold that number:
+
+- ${BRAND.name}'s token-stats document (\`packages/host/src/tokenstats.ts\`, served over the
+  API) — every conversation on this desktop, with subagents counted.
+- \`packages/shared/src/sessioncost.ts\` — the per-session baseline, the same
+  arithmetic the UI says out loud.
+
+Then **edit the measured figure into this file**, and say that it was measured
+and when. A number nobody checked is how the estimate above becomes folklore.
+
+> **Measured baseline:** not yet measured on this machine. Until someone does,
+> treat the break-even above as an estimate and prefer rungs 1-3.
+`;
+}
+/**
+ * Write the preset into a worktree if it is not already there.
+ *
+ * Additive and idempotent, like every other fix: an existing file is left
+ * exactly as it is — someone may have edited the measured baseline into it, and
+ * overwriting that would delete the one part of the file that was ever true
+ * about this machine.
+ */
+export function writeVisualCheckSkill(worktree) {
+    const path = join(worktree, VISUAL_SKILL_REL);
+    if (existsSync(path))
+        return { written: false, relPath: VISUAL_SKILL_REL };
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, visualSkillText());
+    return { written: true, relPath: VISUAL_SKILL_REL };
+}
+//# sourceMappingURL=visualskill.js.map

package/packages/host/dist/visualskill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualskill.js","sourceRoot":"","sources":["../src/visualskill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAEpD,uFAAuF;AACvF,MAAM,CAAC,MAAM,gBAAgB,GAAG,sCAAsC,CAAC;AAEvE,sEAAsE;AACtE,MAAM,YAAY,GAAG,IAAI,CAAC;AAC1B,SAAS,QAAQ;IACf,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,CAAC;IAC9C,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;AACpE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAAC,IAAI,GAAG,QAAQ,EAAE;IAC/C,MAAM,QAAQ,GAAG,IAAI,KAAK,YAAY;QACpC,CAAC,CAAC,GAAG,YAAY,OAAO,KAAK,CAAC,IAAI,iCAAiC,OAAO,CAAC,MAAM,CAAC,cAAc;QAChG,CAAC,CAAC,wBAAwB,IAAI,OAAO,OAAO,CAAC,MAAM,CAAC,kCAAkC,YAAY,GAAG,CAAC;IACxG,OAAO;;;gBAGO,KAAK,CAAC,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oCAqHU,IAAI;;;;;EAKtC,QAAQ;;iDAEuC,IAAI;yBAC5B,KAAK,CAAC,YAAY;;;;;;;;;;;;;;;IAevC,KAAK,CAAC,IAAI;;;;;;;;;;CAUb,CAAC;AACF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;IAC9C,IAAI,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC3E,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC;IACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;AACtD,CAAC"}

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

@@ -0,0 +1,47 @@
+/** Why a dist with no `build-id.txt` is refused, and what to do in either kind
+ *  of install: a checkout builds it; a release tarball ships it, so one without
+ *  it is a damaged install. */
+export declare const NO_BUILD_ID_REASON: string;
+/**
+ * Where the built PWA lives. Exported because `main.ts` serves static files from
+ * the same directory — one definition, so the manifest can never describe a
+ * different tree than the one being served.
+ */
+export declare const WEB_DIST: string;
+export interface BundleFile {
+    /** Posix-style path relative to the bundle root, e.g. `assets/index-abc.js`. */
+    path: string;
+    size: number;
+    sha256: string;
+}
+export interface BundleManifest {
+    ok: boolean;
+    /** Content hash of the build, or null when it could not be determined. */
+    buildId: string | null;
+    files: BundleFile[];
+    /** Sum of `size`, so the client can show "12.3 MB to download" before starting. */
+    total: number;
+    /** Present when `ok` is false — safe to show to the user. */
+    reason?: string;
+}
+/**
+ * The manifest for the bundle currently on disk.
+ *
+ * Hashes are cached against a paths+sizes+mtimes fingerprint: the phone polls
+ * this, and re-reading ~1 MB per poll to produce a value that changes a few
+ * times a day is waste. A rebuild moves an mtime, so the cache cannot go stale.
+ */
+export declare function webBundleManifest(): BundleManifest;
+/**
+ * Resolve one bundle-relative path to a real file, or null.
+ *
+ * The path comes from the phone, so it is contained the same way every other
+ * file route in this daemon is: resolved, then required to still be inside the
+ * bundle root. A `..` that climbs out lands outside `WEB_DIST` and is refused
+ * even though it would resolve to a perfectly real file.
+ */
+export declare function webBundleFile(relPath: string): {
+    abs: string;
+    size: number;
+    mtimeMs: number;
+} | null;

package/packages/host/dist/webbundle.js

@@ -0,0 +1,155 @@
+/**
+ * Serve the built web bundle as a *downloadable* thing, not just as pages.
+ *
+ * Why this exists: the Android shell (`packages/app`) carries the UI inside the
+ * APK, which is the entire point — a dead tunnel can no longer take the app
+ * away. The cost is that the UI is then frozen at APK build time, so every web
+ * change would need a new APK pushed to the phone. That is the wrong trade: the
+ * shell is what must be local, not the *version* of it.
+ *
+ * So the daemon publishes what it is serving — a build id plus a per-file
+ * manifest — and the shell downloads the difference into its own storage and
+ * points its WebView at it (Capacitor's `WebView.setServerBasePath`, which the
+ * bridge restores on boot and resets by itself when a new APK is installed). The
+ * APK's built-in copy stays as the floor that always works offline.
+ *
+ * Three properties this file is responsible for:
+ *
+ *  - **The id is content-derived** (`dist/build-id.txt`, written by the web
+ *    build's `buildStamp` plugin). `npm run restart` rebuilds constantly, and an
+ *    id that changed per build would have the phone re-downloading ~900 KB over
+ *    a roaming link to arrive at a byte-identical bundle.
+ *  - **Per-file `sha256`**, so the client can verify each piece before it
+ *    replaces a working app. This guards against a truncated transfer on a bad
+ *    link — it is NOT a defence against a hostile host, which is already able to
+ *    run arbitrary code on your machine (see SECURITY.md); the bundle is only
+ *    ever fetched from the host the user paired with.
+ *  - **Degrade, never break.** No `dist`, no `build-id.txt`, or a bundle past the
+ *    caps ⇒ `ok: false` with a reason, and the shell simply says updating is
+ *    unavailable and keeps running what it has.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { BRAND } from "@waterplane/shared";
+/** Why a dist with no `build-id.txt` is refused, and what to do in either kind
+ *  of install: a checkout builds it; a release tarball ships it, so one without
+ *  it is a damaged install. */
+export const NO_BUILD_ID_REASON = "web build has no build-id.txt — in a git checkout, rebuild with `npm run build`; " +
+    `in a release install it ships with the release, so reinstall it (or \`${BRAND.slug} update\`)`;
+/**
+ * Where the built PWA lives. Exported because `main.ts` serves static files from
+ * the same directory — one definition, so the manifest can never describe a
+ * different tree than the one being served.
+ */
+export const WEB_DIST = resolve(import.meta.dirname, "../../web/dist");
+/** Bundle files are the app itself: a few hundred KB across a handful of files. */
+const MAX_FILES = 500;
+const MAX_TOTAL = 64 * 1024 * 1024;
+/** Cheap fingerprint of the tree (paths + sizes + mtimes), to skip re-hashing. */
+let cacheKey = "";
+let cached = null;
+/**
+ * The manifest for the bundle currently on disk.
+ *
+ * Hashes are cached against a paths+sizes+mtimes fingerprint: the phone polls
+ * this, and re-reading ~1 MB per poll to produce a value that changes a few
+ * times a day is waste. A rebuild moves an mtime, so the cache cannot go stale.
+ */
+export function webBundleManifest() {
+    let files;
+    try {
+        files = walk(WEB_DIST).sort();
+    }
+    catch {
+        return { ok: false, buildId: null, files: [], total: 0, reason: "no web build on the host" };
+    }
+    if (!files.length) {
+        return { ok: false, buildId: null, files: [], total: 0, reason: "no web build on the host" };
+    }
+    if (files.length > MAX_FILES) {
+        return { ok: false, buildId: null, files: [], total: 0, reason: `bundle has ${files.length} files (max ${MAX_FILES})` };
+    }
+    const stats = files.map((f) => {
+        const s = statSync(f);
+        return { abs: f, rel: rel(f), size: s.size, mtimeMs: s.mtimeMs };
+    });
+    const total = stats.reduce((n, s) => n + s.size, 0);
+    if (total > MAX_TOTAL) {
+        return { ok: false, buildId: null, files: [], total, reason: `bundle is ${Math.round(total / 1e6)} MB (max ${Math.round(MAX_TOTAL / 1e6)} MB)` };
+    }
+    const key = stats.map((s) => `${s.rel}:${s.size}:${Math.floor(s.mtimeMs)}`).join("|");
+    if (key === cacheKey && cached)
+        return cached;
+    let buildId = null;
+    try {
+        buildId = readFileSync(join(WEB_DIST, "build-id.txt"), "utf8").trim() || null;
+    }
+    catch {
+        buildId = null;
+    }
+    if (!buildId) {
+        // An old or hand-made dist. Refusing is better than inventing an id: the
+        // client keys "do I already have this?" on it, and a made-up one would
+        // either re-download forever or, worse, look unchanged when it wasn't.
+        const out = { ok: false, buildId: null, files: [], total, reason: NO_BUILD_ID_REASON };
+        cacheKey = key;
+        cached = out;
+        return out;
+    }
+    const out = {
+        ok: true,
+        buildId,
+        total,
+        files: stats.map((s) => ({
+            path: s.rel,
+            size: s.size,
+            sha256: createHash("sha256").update(readFileSync(s.abs)).digest("hex"),
+        })),
+    };
+    cacheKey = key;
+    cached = out;
+    return out;
+}
+/**
+ * Resolve one bundle-relative path to a real file, or null.
+ *
+ * The path comes from the phone, so it is contained the same way every other
+ * file route in this daemon is: resolved, then required to still be inside the
+ * bundle root. A `..` that climbs out lands outside `WEB_DIST` and is refused
+ * even though it would resolve to a perfectly real file.
+ */
+export function webBundleFile(relPath) {
+    const raw = (relPath || "").trim();
+    if (!raw || raw.startsWith("/") || raw.includes("\0"))
+        return null;
+    const abs = resolve(WEB_DIST, raw);
+    if (abs !== WEB_DIST && !abs.startsWith(WEB_DIST + sep))
+        return null;
+    try {
+        const s = statSync(abs);
+        if (!s.isFile())
+            return null;
+        return { abs, size: s.size, mtimeMs: s.mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}
+function rel(abs) {
+    return relative(WEB_DIST, abs).split(sep).join("/");
+}
+function walk(dir) {
+    const out = [];
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const p = join(dir, e.name);
+        // Never follow a symlink out of the bundle: `isDirectory()`/`isFile()` on a
+        // Dirent describe the link itself, so a symlink is simply skipped.
+        if (e.isDirectory())
+            out.push(...walk(p));
+        else if (e.isFile())
+            out.push(p);
+    }
+    return out;
+}
+//# sourceMappingURL=webbundle.js.map

package/packages/host/dist/webbundle.js.map

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

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

@@ -0,0 +1,5 @@
+export declare const WIRE: boolean;
+/** A frame as the host sent (`out`) or received (`in`) it. */
+export declare function recordWireFrame(dir: "out" | "in", msg: unknown): void;
+/** One `/api` JSON response (body parsed back so the file stays line-per-record). */
+export declare function recordWireHttp(method: string, path: string, status: number, body: Buffer): void;

package/packages/host/dist/wirerecord.js

@@ -0,0 +1,128 @@
+/**
+ * Record mode: `WATERPLANE_WIRE_RECORD=<file>` appends one JSON line per WebSocket
+ * frame (both directions) and per `/api` JSON response. It is the SOURCE of the
+ * demo scenarios (docs/analysis/demo-mode-plan.md §3): `tools/demo-scenario.mjs`
+ * turns a recording of the stub-driven host into a scenario skeleton.
+ *
+ * Zero-cost when unset: `WIRE` is a constant `false`, every call site is
+ * `if (WIRE) recordWire…`, and nothing here runs. A recording is RAW — real
+ * roots, prompts, numbers — and is never to be shipped; only the tool's
+ * fail-closed scrub makes it fit to.
+ *
+ * Because it is raw, how the file is WRITTEN is a security property, not a
+ * detail (adversarial review, 2026-10):
+ * - owner-only: created 0600 and an existing file tightened to 0600 before the
+ *   first append; opened `O_NOFOLLOW` and refused unless it is a regular file
+ *   this user owns — a path in a shared `/tmp` must not become a way to append
+ *   to someone's file through a planted symlink, or into a file another user
+ *   created to read;
+ * - secrets never reach disk even raw: a value under a secret-named key (an
+ *   `auth.set` password, a token in a response body) and a secret-named query
+ *   parameter are replaced with `[redacted]` here, at the source;
+ * - capped: recording stops at `CAP_BYTES` with one line on stderr — a knob
+ *   left on in a `.env` must not fill the disk;
+ * - loud: turning it on prints a line on stderr at start, because the knob can
+ *   come from any of the `.env` files `env.ts` reads, not only the shell.
+ */
+import { closeSync, constants, fchmodSync, fstatSync, openSync, writeSync } from "node:fs";
+import { envName, logTag } from "@waterplane/shared";
+import { env } from "./env.js";
+const FILE = env("WIRE_RECORD") ?? "";
+export const WIRE = FILE !== "";
+/** Recording stops here; a stub demo session is a few hundred KB. */
+const CAP_BYTES = 256 * 1024 * 1024;
+const SECRET_KEY = /^(token|password|passwd|passphrase|secret|clientSecret|cookie|authorization|apikey|api_key|accessToken|refreshToken|idToken|privateKey|credentials?)$/i;
+const SECRET_PARAM = /^(token|access_token|auth|key|apikey|api_key|sig|signature|password|pw|secret|code)$/i;
+const REDACTED = "[redacted]";
+if (WIRE)
+    console.warn(`${logTag} ${envName("WIRE_RECORD")} is ON: every frame and /api response is appended, raw, to ${FILE} — unset it unless you are recording a demo`);
+let fd; // undefined = not opened yet, null = refused or stopped
+let size = 0;
+function stop(why) {
+    console.warn(`${logTag} wire recording stopped: ${why}`);
+    if (typeof fd === "number") {
+        try {
+            closeSync(fd);
+        }
+        catch { /* already */ }
+    }
+    fd = null;
+    return null;
+}
+function open() {
+    try {
+        const f = openSync(FILE, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | (constants.O_NOFOLLOW ?? 0), 0o600);
+        fd = f;
+        const st = fstatSync(f);
+        if (!st.isFile())
+            return stop(`${FILE} is not a regular file`);
+        if (typeof process.getuid === "function" && st.uid !== process.getuid())
+            return stop(`${FILE} belongs to another user`);
+        fchmodSync(f, 0o600);
+        size = st.size;
+        return f;
+    }
+    catch (e) {
+        return stop(`cannot open ${FILE} (${e.code ?? String(e)}; a symlink is refused)`);
+    }
+}
+/** A copy with every secret-named key's value replaced. */
+function redact(v, depth = 0) {
+    if (depth > 64 || v === null || typeof v !== "object")
+        return v;
+    if (Array.isArray(v))
+        return v.map((x) => redact(x, depth + 1));
+    const o = {};
+    for (const [k, x] of Object.entries(v)) {
+        o[k] = SECRET_KEY.test(k) && x !== null && x !== "" && x !== undefined && x !== false ? REDACTED : redact(x, depth + 1);
+    }
+    return o;
+}
+function redactPath(path) {
+    const q = path.indexOf("?");
+    if (q < 0)
+        return path;
+    const params = path.slice(q + 1).split("&").map((kv) => {
+        const eq = kv.indexOf("=");
+        if (eq < 0)
+            return kv;
+        let name = kv.slice(0, eq);
+        try {
+            name = decodeURIComponent(name);
+        }
+        catch { /* keep raw */ }
+        return SECRET_PARAM.test(name) ? `${kv.slice(0, eq)}=${REDACTED}` : kv;
+    });
+    return path.slice(0, q + 1) + params.join("&");
+}
+function write(line) {
+    try {
+        const f = fd === undefined ? open() : fd;
+        if (f === null)
+            return;
+        const buf = Buffer.from(JSON.stringify(line) + "\n", "utf8");
+        if (size + buf.length > CAP_BYTES) {
+            stop(`the ${CAP_BYTES / 1024 / 1024} MB cap on ${FILE} is reached`);
+            return;
+        }
+        writeSync(f, buf);
+        size += buf.length;
+    }
+    catch { /* a recording must never break the host */ }
+}
+/** A frame as the host sent (`out`) or received (`in`) it. */
+export function recordWireFrame(dir, msg) {
+    write({ at: Date.now(), dir, msg: redact(msg) });
+}
+/** One `/api` JSON response (body parsed back so the file stays line-per-record). */
+export function recordWireHttp(method, path, status, body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body.toString("utf8"));
+    }
+    catch {
+        parsed = null;
+    }
+    write({ at: Date.now(), dir: "http", method, path: redactPath(path), status, body: redact(parsed) });
+}
+//# sourceMappingURL=wirerecord.js.map

package/packages/host/dist/wirerecord.js.map

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

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

@@ -0,0 +1,27 @@
+import type { SessionInfo, WorktreeLeftover } from "@waterplane/shared";
+/**
+ * How long a worktree must have sat untouched before it is offered for removal.
+ * A wave of agents gets its worktrees a moment before the agents start, and a
+ * fresh one is clean by definition — every other check passes on it. An hour of
+ * no git activity is what separates "about to be used" from "left behind".
+ */
+export declare const LEFTOVER_IDLE_MIN = 60;
+export interface LeftoverInput {
+    wt: string;
+    branch: string;
+    sessions: Pick<SessionInfo, "cwd">[];
+    /** `worktreeOwners()` names a live session for this worktree. */
+    ownerLive: boolean;
+}
+export declare function worktreeLeftover({ wt, branch, sessions, ownerLive }: LeftoverInput): Promise<WorktreeLeftover>;
+export type RemoveResult = {
+    ok: true;
+    leftover: WorktreeLeftover;
+    branchDeleted: boolean;
+    note?: string;
+} | {
+    ok: false;
+    leftover?: WorktreeLeftover;
+    error: string;
+};
+export declare function removeLeftover(input: LeftoverInput): Promise<RemoveResult>;