waterplane 0.0.1 → 0.1.11

package/packages/host/dist/echo.js

@@ -0,0 +1,439 @@
+/**
+ * "Is THIS text in that?" — the one comparison rule, and the one view it runs on.
+ *
+ * Three places ask the question and they must not answer it differently:
+ * `deliver.ts` asks it of the rendered screen while it is typing, `settle.ts`
+ * asks it of the same screen and of the CLI's conversation log minutes later,
+ * and the open-question sweep asks it of the log for as long as it takes. Two
+ * copies of the rule would eventually be two opinions about the same screen,
+ * and the failure that produces is invisible: a prompt reported as never
+ * delivered while it is sitting there in plain sight.
+ *
+ * The helpers lived in `deliver.ts` until the delivery path itself needed to
+ * consult the conversation log before giving up. That made `deliver.ts` depend
+ * on `settle.ts`, which already depended on `deliver.ts` — a cycle that happens
+ * to work in ESM today only because nothing touches these consts at module
+ * evaluation time, i.e. a trap armed for whoever next writes a top-level
+ * `PASTE_CHIT` somewhere. The rules are pure string logic with no session in
+ * them, so they get their own file and both sides import down.
+ */
+/**
+ * The comparison view: whitespace removed, lower-cased.
+ *
+ * The TUI positions characters individually, so rendered output can lose real
+ * spaces ("Isthisaprojectyou…"). Every comparison against a screen — and, for
+ * one rule, against the log — runs on this view rather than the raw text.
+ */
+export const squash = (s) => s.replace(/\s+/g, "").toLowerCase();
+/**
+ * How much of the head is used as the needle **on a screen**.
+ *
+ * Fourteen characters, and it stays fourteen. The bound is not a guess about
+ * collisions, it is the narrowest composer row this app may be rendering into:
+ * the PTY is sized by whoever is holding the phone, the composer wraps rather
+ * than truncates, and `onScreen()` looks for the needle WITHIN one rendered
+ * row. A longer needle straddles a wrap boundary and stops being found — and a
+ * needle that is not found files a running prompt as a gravestone, which is the
+ * failure this whole subsystem exists to end.
+ *
+ * It was also used against the CLI's conversation log until 2026-09-05, and
+ * there it was simply wrong. Two prompts sharing a fourteen-character head are
+ * indistinguishable by it, and the live run found all three ways that pays out:
+ * a prompt that never ran settled `landed` on another prompt's log entry (the
+ * row retires, the words are gone), two prompts that were nowhere settled
+ * `composer` ("press Return there, never retype it") against a stranger's echo,
+ * and `deliverPrompt` returned `ok` for a prompt that never ran — the worst of
+ * the three, because nothing ever revisits an `ok`. The trigger shape is not
+ * exotic either: **a re-send shares its entire head with the original**, and
+ * re-sending is exactly what a person does when this app tells them their
+ * prompt did not run.
+ *
+ * Lengthening the probe would have fixed none of that. It buys a little against
+ * two unrelated prompts and nothing at all against a re-send, while costing the
+ * one property the number was chosen for. So the fix is elsewhere, in two
+ * pieces:
+ *
+ *  - the LOG needs no prefix at all (`logEcho`) — the jsonl holds the whole user
+ *    turn, so it is compared whole;
+ *  - the SCREEN keeps the prefix but must say what KIND of match it made
+ *    (`screenEcho`), so a caller can refuse to act on one that another open
+ *    delivery could equally have produced (`echoAmbiguous`).
+ */
+export const PROBE_LEN = 14;
+/**
+ * How much of a composer's contents identifies the text it is a WINDOW onto.
+ *
+ * **The composer is a viewport, not a field, and on a phone it is a small
+ * one.** The CLI sizes the box off the terminal's height and SCROLLS the text
+ * inside it, so a prompt longer than that viewport is only ever partly drawn —
+ * and after a write the cursor is at the end, so the part drawn is the TAIL.
+ * Measured against the 2.1.267 binary at 56 columns: a 632-character prompt
+ * shows 3 rows at 12 terminal rows, 5 at 20, and all 14 at 40. The head — which
+ * `echoProbe` is cut from, and which every screen rule here asked for — is off
+ * the top of the box at exactly the sizes a phone reports.
+ *
+ * That is the whole of the failure this constant was added for: 45% of every
+ * delivery between 300 and 800 characters came back `unconfirmed` (the verdict
+ * that is never auto-retried) with the text sitting in plain sight in the
+ * composer, against 17% of the short ones. Under 800 characters the CLI does
+ * not collapse the text either (`PASTE_MIN_CHARS`), so the placeholder rule
+ * that rescues the long ones cannot speak about these at all.
+ *
+ * Forty characters, and the number is doing a different job from `PROBE_LEN`.
+ * That one is bounded ABOVE by the narrowest row we may be rendering into,
+ * because it must sit inside one wrapped row. This one is asked of the box's
+ * whole contents joined together, so wrapping cannot break it, and it is
+ * bounded BELOW by collision: it is the length at which "this window of
+ * characters is inside my text" stops being a coincidence. Forty is a short
+ * sentence — well past the point where two unrelated prompts agree, and well
+ * inside the three rows the smallest composer draws.
+ */
+export const SLICE_MIN = 40;
+/**
+ * **Is the prompt the CLI says it submitted the one we typed?**
+ *
+ * `UserPromptSubmit` hands the host the submitted text, which makes it the only
+ * submit proof that is about a DELIVERY rather than about a session (a turn
+ * starting says the CLI is busy; this says what it is busy with). The rule is
+ * deliberately STRICT — whole-string equality after normalising the two things
+ * a terminal round trip legitimately changes:
+ *
+ *  - line endings, because the PTY write carries `\r` and the CLI hands back
+ *    `\n`;
+ *  - trailing whitespace on the whole text, because a composer submits what it
+ *    holds and the last keystroke before Return is frequently a space.
+ *
+ * Nothing else. A prefix rule would match the re-send of a prompt that was
+ * itself a prefix, and a fuzzy one would let a delivery claim the turn started
+ * by somebody typing into the same session by hand — and the verdict this
+ * evidence upgrades (`unconfirmed` → `ok`) is the one that decides whether a
+ * prompt is ever sent again. Being wrong in that direction loses the words
+ * silently; being wrong in the other costs a settle pass that was going to run
+ * anyway.
+ *
+ * **…and a PASTED prompt comes back in its envelope** (measured on 2.1.300 and
+ * 2.1.301, the hook's own payload): `\n\n<pasted_content id="7ed2">\n` + the
+ * text + `\n</pasted_content id="7ed2">\n`, once per chunk the CLI read it in —
+ * and it reads a single write in ~1 KB pieces, each seam cutting mid-word, the
+ * seams' newlines varying with how the bytes arrived. `logEcho` was taught this
+ * on 2026-10-06; this rule was not, so every prompt over ~800 characters or
+ * three lines failed it. Where the screen also missed (several placeholders,
+ * no tail on screen), the hook was the only proof left, and it said "something
+ * other than your text" about the very words: 12 of 12 such deliveries between
+ * 2026-10-06 and 10-15 ran (`settle.ts`: `landed`), each reported `unconfirmed`.
+ *
+ * So the envelope is read the way `logEcho` reads it — tags off both sides —
+ * and, because the seams are the CLI's newlines and not ours, compared blind to
+ * whitespace. Still the WHOLE text, still case-exact, still equality: a prefix,
+ * a superset or another prompt in the same envelope does not match, and a hook
+ * payload with no tag in it never reaches this branch.
+ */
+export function samePromptText(hookPrompt, ours) {
+    const norm = (t) => t.replace(/\r\n?/g, "\n").replace(/[ \t]+$/gm, "").trim();
+    const a = norm(hookPrompt), b = norm(ours);
+    if (a.length > 0 && a === b)
+        return true;
+    if (!hookPrompt.includes("<pasted_content"))
+        return false;
+    const bare = (t) => unwrapPasted(t).replace(/\s+/g, "");
+    const x = bare(hookPrompt);
+    return x.length > 0 && x === bare(ours);
+}
+/**
+ * How much text this file will scan for a shared window before giving up.
+ *
+ * `echoAmbiguous` answers the scrolled rule by asking whether a rival could
+ * have produced the same window, which is a substring search over both texts.
+ * Past this size that stops being free, and the standing rule here is that a
+ * question we cannot answer is answered "I cannot tell" — so beyond it a rival
+ * is treated as confusable rather than scanned for. The cost of that is one
+ * `retry`, which types nothing and is safe to repeat; the cost of the other
+ * direction is pressing Return on somebody else's words.
+ */
+const SLICE_SCAN_MAX = 20000;
+/** Does `b` contain any `SLICE_MIN`-character window of `a`? */
+function sharesSlice(a, b) {
+    if (a.length < SLICE_MIN || b.length < SLICE_MIN)
+        return false;
+    if (a.length > SLICE_SCAN_MAX || b.length > SLICE_SCAN_MAX)
+        return true;
+    const [short, long] = a.length <= b.length ? [a, b] : [b, a];
+    for (let i = 0; i + SLICE_MIN <= short.length; i++) {
+        if (long.includes(short.slice(i, i + SLICE_MIN)))
+            return true;
+    }
+    return false;
+}
+/** The head of the text, squashed. */
+export const echoProbe = (text) => squash(text).slice(0, PROBE_LEN);
+/** The tail of the text, squashed — what is still drawn when the TUI has
+ *  collapsed the head behind a paste placeholder. */
+export const tailProbe = (text) => squash(text).slice(-PROBE_LEN);
+/**
+ * The claude TUI's collapsed-paste placeholder, against a `squash`ed haystack:
+ * `[Pasted text #1 +11 lines]` — or just `[Pasted text #1]`.
+ *
+ * **The line count is OPTIONAL and its absence is a fact, not a gap.** The CLI
+ * builds the placeholder from the NEWLINE count of what it swallowed, and it
+ * omits the clause entirely when that count is zero:
+ *
+ *     function(id, newlines) {
+ *       if (newlines === 0) return `[Pasted text #${id}]`;
+ *       return `[Pasted text #${id} +${newlines} lines]`;
+ *     }
+ *
+ * (measured against the 2.1.236 binary). So a LONG SINGLE-LINE prompt — the
+ * ordinary shape of a message typed on a phone, which has no reason to hold a
+ * newline at all — collapses to a placeholder that says nothing but "a paste
+ * with no newlines in it happened here". A regex that required `+N lines`
+ * matched none of them: every long one-line send echoed perfectly, read as
+ * never typed, came back `unconfirmed` (the verdict that is never auto-retried)
+ * and sat one keypress from running behind a gravestone. That is the same
+ * failure `e2e-pastechit.mjs` pins for the multi-line case, arriving through
+ * the half of the placeholder nobody had seen.
+ *
+ * The capture is therefore how many NEWLINES it is hiding, and an ABSENT
+ * capture means zero of them — which is the only thing the placeholder says
+ * about the text behind it, and, for a one-liner, the whole of the tie.
+ */
+export const PASTE_CHIT = /\[pastedtext#\d+(?:\+(\d+)lines?)?\]/;
+/**
+ * How long a write has to be before the TUI collapses it whatever its shape.
+ *
+ * The other half of the same measurement: the composer collapses on
+ * `text.length > 800 || newlines > 2`, so LENGTH is a collapse trigger in its
+ * own right and a single-line prompt is not exempt from it. Eight hundred
+ * characters is a paragraph — well inside what a person dictates into the
+ * compose bar, and far inside a "set up this repo" prompt.
+ *
+ * It is used only to decide whether a placeholder COULD be about this text.
+ * Getting it wrong in the loose direction costs a rival check; getting it wrong
+ * in the strict direction is the gravestone above, so it stays the CLI's own
+ * number rather than a safety margin off it.
+ */
+export const PASTE_MIN_CHARS = 800;
+/**
+ * Could the TUI have collapsed THIS text into a placeholder at all?
+ *
+ * Either trigger is enough: over `PASTE_MIN_CHARS` characters, or enough
+ * newlines in it. The line half keeps the three it has always used rather than
+ * the CLI's four, because that bound also moves with the terminal height
+ * (`min(rows - 10, 2)` newlines) and being one line loose here only ever hands
+ * the answer to the tie-breakers below.
+ */
+export const pasteCollapsible = (text) => text.length > PASTE_MIN_CHARS || text.split("\n").length >= 3;
+/**
+ * How many newlines the NEWEST run of placeholders is hiding, or null for none.
+ *
+ * **One write can be several pastes.** The CLI reads a burst in ~1 KB pieces
+ * and collapses each piece on its own, so a 5 KB prompt is drawn
+ * `[Pasted text #1 +2 lines][Pasted text #2 +2 lines]…[Pasted text #5]` —
+ * measured on 2.1.300/2.1.301 (`fixtures/screens/paste-chain.txt`). Reading
+ * only the FIRST chit said "2 of 11 lines hidden", no tail was drawn to tie it
+ * otherwise, and every such delivery read as never typed. The pieces cut
+ * mid-line, so the newlines hidden by the run are exactly the sum of its
+ * clauses.
+ *
+ * A RUN is chits that touch in the squashed haystack — the CLI draws them
+ * back to back, and only the last piece can be left uncollapsed (a middle piece
+ * is ~1 KB, past `PASTE_MIN_CHARS`). Only the last run on the haystack counts:
+ * the live composer is the bottom of the screen, and a placeholder from an
+ * earlier paste elsewhere on it is somebody else's count, not part of ours.
+ * An absent clause is zero newlines, as for one chit.
+ *
+ * `haystack` must already be `squash`ed.
+ */
+export function pastedNewlines(haystack) {
+    const chit = new RegExp(PASTE_CHIT.source, "g");
+    let sum = null, end = -1;
+    for (const m of haystack.matchAll(chit)) {
+        const n = m[1] === undefined ? 0 : Number(m[1]);
+        sum = m.index === end && sum !== null ? sum + n : n;
+        end = m.index + m[0].length;
+    }
+    return sum;
+}
+/**
+ * Does this haystack hold THIS text as a collapsed paste?
+ *
+ * A write of several lines — or of one long one — in a single chunk is
+ * indistinguishable from a paste, and the TUI collapses a paste to a
+ * placeholder plus whatever tail still fits, so the head, which every other
+ * probe is cut from, is nowhere to be found. The placeholder is therefore an
+ * echo like any other, but it names no text, so it only counts with a second
+ * fact tying it to THIS one: the tail still on screen, or a hidden-newline
+ * count that accounts for essentially all of it. A stale placeholder from an
+ * earlier, different paste satisfies neither — and note that the tie runs in
+ * BOTH directions now that the count can be absent: a bare `[Pasted text #5]`
+ * is a paste with no newlines in it, which is evidence FOR a one-line prompt
+ * and evidence AGAINST a twelve-line one.
+ *
+ * `haystack` must already be `squash`ed.
+ */
+export function collapsedPasteEcho(haystack, text) {
+    if (!pasteCollapsible(text))
+        return false;
+    const hidden = pastedNewlines(haystack);
+    if (hidden === null)
+        return false;
+    const lines = text.split("\n").length;
+    if (hidden > lines + 1)
+        return false; // far more than we ever wrote
+    if (hidden >= lines - 1)
+        return true; // it swallowed the lot
+    const tail = tailProbe(text);
+    return !!tail && haystack.includes(tail);
+}
+export function screenEcho(haystack, text) {
+    const probe = echoProbe(text);
+    if (!probe)
+        return "none";
+    if (haystack.includes(squash(text)))
+        return "exact";
+    if (haystack.includes(probe))
+        return "head";
+    if (collapsedPasteEcho(haystack, text))
+        return "paste";
+    return "none";
+}
+/**
+ * Does this haystack hold this text, by any of the screen rules?
+ *
+ * Kept as the yes/no form of `screenEcho` for the call sites that genuinely
+ * only want a boolean. Anything that will ACT on the answer should ask
+ * `screenEcho` and put the rule past `echoAmbiguous` first.
+ */
+export function textEcho(haystack, text) {
+    return screenEcho(haystack, text) !== "none";
+}
+/**
+ * Could this match just as easily have been one of those?
+ *
+ * The disambiguation rule, and the reason it exists at all: a screen match is a
+ * PREFIX match, and a prefix says "some text starting like this is here", not
+ * "your text is here". When something else that could be in that composer would
+ * have produced the identical match, the match is not evidence about ours, and
+ * this codebase's standing rule is to degrade to "I cannot tell" rather than to
+ * a confident wrong answer. `unknown` costs one more sweep; a wrong `composer`
+ * tells the user to press Return on somebody else's prompt, and a wrong
+ * `landed` retires the row and takes the words with it.
+ *
+ * Confusability is asked PER RULE, because each rule ties the match to the text
+ * by a different fact and a rival only counts if it satisfies the same one:
+ *
+ *   exact    — nothing is confusable. The whole text is there.
+ *   scrolled — a rival that contains a `SLICE_MIN`-long window of our text, so
+ *              the same drawn box could be a viewport onto either. Asked as
+ *              "do these two share any window at all" rather than "does the
+ *              rival hold THE window", because the window is a fact about the
+ *              screen and this function is only given the two texts. That is
+ *              the conservative direction: it can call a match ambiguous that
+ *              was not, and the cost of that is a `retry`, which types nothing.
+ *   head     — a rival sharing the fourteen-character head.
+ *   paste    — a rival that is also a collapsible multi-line text and shares
+ *              the tail, or is close enough in line count to satisfy the
+ *              "it swallowed the lot" branch of `collapsedPasteEcho`.
+ *
+ * A rival whose squashed text EQUALS ours is never confusable, and that is the
+ * important exemption rather than an optimisation: the common rival is a
+ * re-send of the same words, and if the composer holds our own words then
+ * submitting them runs our own words. Which ROW gets the credit is a separate
+ * question (`settle.ts` answers it by claiming the log turn); what is on the
+ * screen is not in doubt.
+ */
+export function echoAmbiguous(rule, text, others) {
+    if (rule === "none" || rule === "exact")
+        return false;
+    const me = squash(text);
+    const lines = text.split("\n").length;
+    return others.some((o) => {
+        const theirs = squash(o);
+        if (!theirs || theirs === me)
+            return false;
+        if (rule === "head")
+            return echoProbe(o) === echoProbe(text);
+        if (rule === "scrolled")
+            return sharesSlice(theirs, me);
+        // Never collapsible, never a rival here — and "collapsible" is length OR
+        // shape, so a long one-liner is in the running exactly like a long
+        // multi-line prompt is (`pasteCollapsible`).
+        if (!pasteCollapsible(o))
+            return false;
+        const theirLines = o.split("\n").length;
+        if (tailProbe(o) === tailProbe(text))
+            return true;
+        // The swallow branch is tied to nothing but a newline count, so any rival
+        // whose count the same placeholder could be reporting is a rival — and for
+        // two one-liners that count is zero on both sides, i.e. a bare
+        // `[Pasted text #5]` cannot tell them apart at all. That is the case this
+        // branch exists for: the evidence is real but it is not about anyone.
+        return Math.abs(theirLines - lines) <= 1;
+    });
+}
+/**
+ * How much of the text is compared against the CLI's own conversation log.
+ *
+ * Four thousand squashed characters — roughly 285 times the screen probe, and
+ * chosen as "past every collision, short of every truncation". Two distinct
+ * prompts that agree for four thousand characters and diverge after are the
+ * same instruction for every purpose this app has, while a cap keeps the needle
+ * clear of the two places a whole-text comparison could break in the dangerous
+ * direction: `transcript.ts` caps a stored prompt at 200 000 characters, and
+ * any future normalisation the CLI applies to a very long turn would land at
+ * its end. Falling short there answers `absent`, and `absent` is the verdict
+ * that authorises sending the prompt a second time — so the needle stops well
+ * before anything that could be trimmed.
+ */
+export const LOG_NEEDLE_MAX = 4000;
+/**
+ * Does this LOGGED user turn hold this text?
+ *
+ * The conversation log has no truncation problem to work around: the CLI wrote
+ * the whole turn down when it accepted the prompt, so the comparison is the
+ * whole text and not a fourteen-character head. That single change is what
+ * stops another prompt's log entry from proving ours ran — the one failure in
+ * this family that destroys words rather than merely delaying them.
+ *
+ * `logged` is the raw turn text; both sides are squashed here, because the
+ * caller has no reason to know that the log needs the same whitespace-blind
+ * view a screen does (a prompt typed with a trailing newline, a CRLF, or
+ * re-wrapped by the composer must still be recognised as itself).
+ *
+ * The collapsed-paste rule is kept as a second chance and NOT as the main one:
+ * if a CLI version ever records a pasted prompt as its placeholder rather than
+ * its content, removing this would turn every long prompt into `absent` and
+ * re-send it. It is the same tie-to-this-text rule as everywhere else.
+ *
+ * **A pasted prompt is logged WRAPPED and CHUNKED** (measured on 2.1.291): the
+ * turn reads `<pasted_content id="893a">` + ~1000 chars + `</pasted_content
+ * id="893a">`, repeated, each seam cutting mid-word. Compared raw, every long
+ * prompt past the first chunk read `absent` though it ran — and a person was
+ * told "nothing ran". The tags are stripped from BOTH sides, so a prompt that
+ * itself quotes one is still compared like for like.
+ */
+const PASTE_TAG = /<\/?pasted_content\b[^>]*>/g;
+export const unwrapPasted = (s) => s.replace(PASTE_TAG, "");
+export function logEcho(logged, text) {
+    const needle = squash(unwrapPasted(text)).slice(0, LOG_NEEDLE_MAX);
+    if (!needle)
+        return false;
+    const hay = squash(unwrapPasted(logged));
+    return hay.includes(needle) || collapsedPasteEcho(hay, text);
+}
+/**
+ * Is this a slash command — i.e. text whose fate the conversation log cannot
+ * report?
+ *
+ * The CLI does not write a slash command as a user turn. It writes an envelope
+ * (`<command-name>/foo</command-name>` and friends), and `transcript.ts`'s
+ * `promptOf` drops exactly those — deliberately, because a reader that showed
+ * them would label every archive row `<command-name>`. The consequence for
+ * anything reasoning from the log is absolute: for a slash command the log is
+ * silent whether or not it ran, so absence there is not evidence of anything.
+ * Saying "absent" about one would be saying "nothing ran, send it again" about
+ * a command that ran perfectly.
+ */
+export function isSlashText(text) {
+    return text.trimStart().startsWith("/");
+}
+//# sourceMappingURL=echo.js.map

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

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

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

@@ -0,0 +1,16 @@
+/** The code root: `<PREFIX>ROOT`, else the folder chosen on the phone, else the first usual code folder that exists, else `~/dev` (`branddirs.ts`' `resolveRoot`). */
+export declare const ROOT: string;
+/** True when nobody named or chose the root and it was derived (found or assumed) — the doctor says so. */
+export declare const ROOT_DEFAULTED: boolean;
+/** How the root came about: `named` (the knob), `chosen` (`rootchoice.ts`), `found` (an existing usual folder) or `fallback` (`~/dev`, which may not exist). */
+export declare const ROOT_PICKED: import("@waterplane/shared").RootPicked;
+/** The daemon's global state dir, outside the code root — `hostStateDir(ROOT)` answers it. */
+export declare const STATE_DIR: string;
+/**
+ * The knob readers: `env("PORT")` reads the current-brand name, then each
+ * legacy name (`shared/envresolve.ts`), and warns ONCE per legacy name it had
+ * to fall back to, naming the `.env` file that set it when one did. Read at
+ * CALL time from `process.env`, so a hot-reloaded secret is seen. Existing
+ * `process.env.<LEGACY>_X` reads keep working; the rename moves them here.
+ */
+export declare const env: (key: string) => string | undefined, envStr: (key: string, dflt: string) => string, envBool: (key: string, dflt: boolean) => boolean, envInt: (key: string, dflt: number) => number;

package/packages/host/dist/env.js

@@ -0,0 +1,190 @@
+/**
+ * The daemon's root directory, and the `.env` files loaded into `process.env`
+ * — BEFORE any other host module is evaluated.
+ *
+ * `main.ts` imports this FIRST. An ES import list is evaluated, depth-first, in
+ * order, before the importing module's body runs; so when the loop below sat in
+ * `main.ts`'s body, every module that reads an env knob at import
+ * (`sessions/knobs.ts`, `intents/contract.ts`'s `TICK_MS`, `backends/claude.ts`'s
+ * `CLAUDE_BIN` knob, …) had already read `process.env` — and a knob set only in
+ * one of these files was silently ignored by all of them. Being the first
+ * import is what makes the files mean what `.env.example` says they mean.
+ *
+ * Precedence, highest first: the process's own environment (the shell, launchd,
+ * every e2e script's pinned env), then the per-user config dir (where set-secret
+ * host scope writes, and hot-reloads into `process.env`), then the repo `.env`,
+ * then `<STATE_DIR>/.env`. `envfiles.ts`
+ * says why a later file wins and why `process.loadEnvFile` could not do it.
+ * Keep this module's own imports to ones that read nothing from the
+ * environment at import.
+ *
+ * Before any file is read, `branddirs.ts` moves the daemon's own directories
+ * from a legacy name to the current one (config, data, `<ROOT>/<state dir>`),
+ * leaving a symlink at the old name — and then moves `<ROOT>/<state dir>` OUT of
+ * the code root into the global state dir (`STATE_DIR`: `<PREFIX>STATE_DIR` →
+ * `$XDG_STATE_HOME/<name>` → `~/.local/state/<name>`). Both run in the daemon
+ * only. `bindHostStateDir` then makes `hostStateDir(ROOT)` answer that dir, so
+ * every store that opens after this module finds its data there.
+ */
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { logTag, makeEnvReader, nodeMeetsMin, nodeTooOldSentence, resolveEnv } from "@waterplane/shared";
+import { homedir } from "node:os";
+import { bindHostStateDir, liveStateDir, migrateHostDirs, migrateStateDir, pendingStateMove, realRootFs, resolveRoot, resolveStateDir, stateMoveRefusedSentence } from "./branddirs.js";
+import { readChosenRoot } from "./rootchoice.js";
+import { loadEnvFiles } from "./envfiles.js";
+import { hostSecretEnvPath } from "./secrets.js";
+// Before anything below reads import.meta.dirname (undefined before Node 20.11,
+// and `resolve(undefined)` throws) or envfiles.ts calls util.parseEnv (20.12):
+// one sentence instead of a TypeError. The bar is shared's NODE_MIN.
+if (!nodeMeetsMin(process.versions.node)) {
+    console.error(`${logTag} ${nodeTooOldSentence(process.versions.node)}`);
+    process.exit(1);
+}
+/** The files that may name the root and the state dir, into a scratch copy. The
+ *  root decides the state dir, which decides the first `.env`, so that one file
+ *  can never name either; the other two can, and until 2026-10-07 neither was
+ *  read before `resolveRoot` ran: a `<PREFIX>ROOT` set only in the repo `.env`
+ *  (what `.env.example` tells you to do) was silently ignored for the root. */
+const bootEnv = { ...process.env };
+loadHostEnv(null, bootEnv);
+// The knob, then the folder chosen in the phone's dialog (`rootchoice.ts`), then the guess.
+const rootPick = resolveRoot(bootEnv, homedir(), realRootFs, readChosenRoot());
+/** The code root: `<PREFIX>ROOT`, else the folder chosen on the phone, else the first usual code folder that exists, else `~/dev` (`branddirs.ts`' `resolveRoot`). */
+export const ROOT = rootPick.root;
+/** True when nobody named or chose the root and it was derived (found or assumed) — the doctor says so. */
+export const ROOT_DEFAULTED = rootPick.defaulted;
+/** How the root came about: `named` (the knob), `chosen` (`rootchoice.ts`), `found` (an existing usual folder) or `fallback` (`~/dev`, which may not exist). */
+export const ROOT_PICKED = rootPick.picked;
+/**
+ * True when this process IS the daemon — its entry script is this package's
+ * `main` — rather than a test or a tool that imports a host module (dozens of
+ * modules import this one for `env()`). Realpath'd, so the npm `bin` symlink
+ * counts; `.ts` under `tsx` and `.js` under node both match.
+ */
+function isDaemonEntry() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    let real;
+    try {
+        real = realpathSync(entry);
+    }
+    catch {
+        real = resolve(entry);
+    }
+    const here = (() => { try {
+        return realpathSync(import.meta.dirname);
+    }
+    catch {
+        return import.meta.dirname;
+    } })();
+    return dirname(real) === here && /^main\.(js|ts|mjs)$/.test(basename(real));
+}
+/** THE `.env` load, in its one precedence order — for real below, and into a
+ *  scratch copy by the boot-move guard, which needs the port before the state
+ *  dir (and so the first file) is final, and by the root pick above, which runs
+ *  before there is a state dir at all (`null`: that file is skipped). A function
+ *  so the order exists once. */
+function loadHostEnv(stateDir, target, origins) {
+    loadEnvFiles([
+        ...(stateDir === null ? [] : [join(stateDir, ".env")]),
+        resolve(import.meta.dirname, "../../../.env"),
+        hostSecretEnvPath(),
+    ], target, origins);
+}
+const realOr = (p) => { try {
+    return realpathSync(p);
+}
+catch {
+    return resolve(p);
+} };
+/**
+ * `host:port` of a running host whose root is ours, or null. The port is the
+ * one this boot will use, read through the same `.env` files the boot is about
+ * to load (into a scratch copy — nothing is loaded for real yet). 800 ms: a
+ * host that is up answers its health route in single milliseconds.
+ */
+async function otherDaemonFor(root, oldState) {
+    const peek = { ...process.env };
+    try {
+        loadHostEnv(oldState, peek);
+    }
+    catch { /* the default port */ }
+    const port = Number(resolveEnv(peek, "PORT").value) || 8770;
+    const at = `127.0.0.1:${port}`;
+    try {
+        const r = await fetch(`http://${at}/api/health`, { signal: AbortSignal.timeout(800) });
+        const body = (await r.json());
+        if (typeof body?.protocol !== "number")
+            return null; // not one of ours
+        return typeof body.root !== "string" || realOr(body.root) === realOr(root) ? at : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Rename legacy dirs to the current brand's names, once, before anything reads
+// them — ONLY in the daemon itself, never because a unit test imported a module
+// that reads a knob (that would move a person's real `~/.config` and `<ROOT>`
+// state under a test run). Never throws; what it did is one line each.
+// `--doctor` is the daemon's entry too, but a preflight only looks: it reads
+// wherever the state is now and reports a pending move instead of making it.
+// `doctor --json` owns stdout: the report is one JSON document there, so every
+// other line the boot prints (this module's own notes included) goes to stderr.
+if (process.argv.includes("--doctor") && process.argv.includes("--json")) {
+    console.log = console.info = console.error;
+}
+const statePick = resolveStateDir(bootEnv);
+let stateDir;
+if (isDaemonEntry()) {
+    for (const r of migrateHostDirs(ROOT))
+        if (r.note)
+            console.log(`${logTag} ${r.note}`);
+    if (process.argv.includes("--doctor"))
+        stateDir = liveStateDir(ROOT, statePick.dir);
+    else {
+        // A move is about to happen: refuse it while ANOTHER daemon for this root is
+        // still answering (a host from before the restart, an older build). It
+        // writes the old path; one write between the rename and the pointer would
+        // recreate a real dir there and split the state in two. Asked over the
+        // daemon's own health route, top-level await, only when there is a move to
+        // make — a boot with nothing to move never waits on the network.
+        const from = pendingStateMove(ROOT, statePick.dir);
+        const other = from ? await otherDaemonFor(ROOT, from) : null;
+        if (other) {
+            console.warn(`${logTag} ${stateMoveRefusedSentence(from, statePick.dir, other)}`);
+            stateDir = from;
+        }
+        else {
+            const m = migrateStateDir(ROOT, statePick.dir);
+            if (m.note)
+                (m.action === "failed" || (m.action === "merged" && m.kept?.length) ? console.warn : console.log)(`${logTag} ${m.note}`);
+            stateDir = m.dir;
+        }
+    }
+}
+else {
+    stateDir = liveStateDir(ROOT, statePick.dir);
+}
+/** The daemon's global state dir, outside the code root — `hostStateDir(ROOT)` answers it. */
+export const STATE_DIR = stateDir;
+bindHostStateDir(ROOT, STATE_DIR);
+// Load secrets/config from gitignored .env files. Lets the Gemini key live on
+// disk (e.g. synced from Bitwarden) instead of the shell. Lowest precedence
+// first: <STATE_DIR>/.env → repo .env → the fixed per-user config dir, so what
+// the phone set last is what runs after a restart. The old under-root
+// `<ROOT>/<state dir>/.env` is not read: after the move it is a symlink to this
+// same file; when both dirs held a `.env` the merge kept the new one and left
+// the old one beside a MOVED.txt; and when the move failed STATE_DIR IS the old dir.
+const envOrigins = new Map();
+loadHostEnv(STATE_DIR, process.env, envOrigins);
+/**
+ * The knob readers: `env("PORT")` reads the current-brand name, then each
+ * legacy name (`shared/envresolve.ts`), and warns ONCE per legacy name it had
+ * to fall back to, naming the `.env` file that set it when one did. Read at
+ * CALL time from `process.env`, so a hot-reloaded secret is seen. Existing
+ * `process.env.<LEGACY>_X` reads keep working; the rename moves them here.
+ */
+export const { env, envStr, envBool, envInt } = makeEnvReader(process.env, (text) => console.warn(text), (name) => envOrigins.get(name));
+//# sourceMappingURL=env.js.map