waterplane 0.0.1 → 0.1.6

package/packages/host/dist/passive.js

@@ -0,0 +1,187 @@
+/**
+ * Passive devices — the kids' phone (R-connection-011…014). Security boundary:
+ * described in docs/notes/protocol-and-security.md, never a skill.
+ *
+ * **The allowlist is default-deny.** A passive token (a `DeviceRow.scope ===
+ * "passive"` row that is not currently unlocked) reaches only what
+ * `passiveAllows` names: health, the web bundle the OTA update reads, the
+ * passive screen's own state, the theme, and the artifact download of an APK
+ * the auto-pull queue holds RIGHT NOW — not any file of any repo. A route added
+ * anywhere else in the host is refused to a passive token until somebody adds
+ * it here on purpose. The WebSocket is refused outright (`server/wsops.ts`), and
+ * `/api/auth/token` will not mint a full token for one (`server/http.ts`).
+ *
+ * **The PIN** is scrypt-hashed in `<STATE_DIR>/passive-pin.json` (0600), set
+ * only from a trusted caller that is not itself passive (unlocked or not), and
+ * checked here, rate-limited per device. A correct PIN lifts THAT device to
+ * full scope for `unlockMs` — in this process's memory only, so a host restart
+ * comes back locked too — and a timer closes the device's sockets when it runs
+ * out, so an open WebSocket does not outlive the unlock.
+ */
+import { randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { PASSIVE_UNLOCK_MS, isPassiveItem, normalizePin, passiveUnlockErrorText, } from "@waterplane/shared";
+import { hostStateDir } from "./branddirs.js";
+import { readJsonGuarded, writeJsonAtomic } from "./jsonstore.js";
+import { RateLimiter } from "./ratelimit.js";
+import { env } from "./env.js";
+/** `WATERPLANE_PASSIVE_UNLOCK_MS` shortens the unlock for e2e (floored at 1 s,
+ *  never longer than the 30 minutes the phone's sentence promises). */
+export function unlockMsFromEnv() {
+    const n = Number(env("PASSIVE_UNLOCK_MS"));
+    return Number.isFinite(n) && n > 0 ? Math.min(PASSIVE_UNLOCK_MS, Math.max(1000, n)) : PASSIVE_UNLOCK_MS;
+}
+const READ = new Set(["GET", "HEAD"]);
+/** Exact read-only paths a passive token may ask. Adding one is a decision. */
+const PASSIVE_READS = new Set(["/api/health", "/api/webbundle", "/api/webbundle/file", "/api/passive/state", "/api/theme"]);
+const ARTIFACT = /^\/api\/repos\/([^/]+)\/artifact$/;
+/**
+ * May a passive (locked) token make this `/api/` request? `queuedApk` answers
+ * "is (repoId, worktree-relative path) an APK in the auto-pull queue". Pure:
+ * `packages/host/test/passive.test.mjs` asks it directly.
+ */
+export function passiveAllows(method, path, query, queuedApk) {
+    if (!READ.has(method.toUpperCase()))
+        return false;
+    if (PASSIVE_READS.has(path))
+        return true;
+    const m = ARTIFACT.exec(path);
+    if (!m)
+        return false;
+    let repoId;
+    try {
+        repoId = decodeURIComponent(m[1]);
+    }
+    catch {
+        return false;
+    }
+    const rel = query.get("path");
+    return !!rel && queuedApk(repoId, rel);
+}
+/** Writes a passive row may NEVER make, unlocked or not. */
+const PASSIVE_NEVER_WRITES = new Set(["/api/pair/mint", "/api/devices/revoke"]);
+/**
+ * Auth MATERIAL is out of a passive row's reach even while it is unlocked: a
+ * pairing code (it mints a full token), a revoke, a peer pairing, the LAN
+ * identity secret. The unlock lifts the device to full scope for 30 minutes;
+ * each of these would outlive it as a credential or an auth change in its own
+ * right. `/api/auth/token` and `/api/auth/pin` refuse a passive row the same
+ * way in `server/http.ts`, and the WebSocket `auth.*` ops in `routes/system.ts`.
+ * Pure: `passive.test.mjs` asks it.
+ */
+export function passiveNeverAllows(method, path) {
+    if (path === "/api/lan/identity")
+        return true;
+    const write = !READ.has(method.toUpperCase());
+    if (path === "/api/peers" || path.startsWith("/api/peers/"))
+        return write;
+    return write && PASSIVE_NEVER_WRITES.has(path);
+}
+/** The auto-pull queue as a passive device may see it: APKs only. */
+export function passiveItems(items) {
+    return items.filter(isPassiveItem);
+}
+/** `passiveAllows`'s question over a queue. */
+export function queuedApkIn(items) {
+    return (repoId, relPath) => items.some((i) => isPassiveItem(i) && i.repoId === repoId && i.relPath === relPath);
+}
+export class PassiveGate {
+    file;
+    pin;
+    unlocked = new Map();
+    now;
+    unlockMs;
+    /** Set by `main.ts` once the socket registry exists (`closeDevice`). */
+    onRelock;
+    /** 5 tries in a burst, then one a minute, per device: a 4-digit PIN takes
+     *  days to walk, a child mistyping twice is never locked out. */
+    limit = new RateLimiter({ burst: 5, perSec: 1 / 60 });
+    constructor(root, opts = {}) {
+        this.file = join(hostStateDir(root), "passive-pin.json");
+        this.now = opts.now ?? Date.now;
+        this.unlockMs = opts.unlockMs ?? unlockMsFromEnv();
+        this.onRelock = opts.onRelock ?? (() => undefined);
+        const ok = (v) => !!v && typeof v.salt === "string" && typeof v.hash === "string";
+        this.pin = readJsonGuarded(this.file, null, ok);
+    }
+    pinSet() { return !!this.pin; }
+    /** Set (a valid PIN) or clear (`null`) the unlock PIN. Every live unlock ends. */
+    setPin(raw) {
+        if (raw === null) {
+            this.pin = null;
+            try {
+                rmSync(this.file, { force: true });
+            }
+            catch { /* nothing to remove */ }
+        }
+        else {
+            const pin = normalizePin(raw);
+            if (!pin)
+                throw new Error(passiveUnlockErrorText("bad-request"));
+            const salt = randomBytes(16).toString("hex");
+            this.pin = { salt, hash: scryptSync(pin, salt, 32).toString("hex") };
+            writeJsonAtomic(this.file, this.pin, { mode: 0o600 });
+        }
+        for (const id of [...this.unlocked.keys()])
+            this.lock(id);
+    }
+    pinMatches(pin) {
+        if (!this.pin)
+            return false;
+        const got = scryptSync(pin, this.pin.salt, 32);
+        const want = Buffer.from(this.pin.hash, "hex");
+        return got.length === want.length && timingSafeEqual(got, want);
+    }
+    /** A passive device asks to be lifted to full scope. */
+    unlock(row, raw) {
+        const fail = (error, retryAfterMs = 0) => ({ ok: false, error, message: passiveUnlockErrorText(error, retryAfterMs / 1000), ...(retryAfterMs ? { retryAfterMs } : {}) });
+        if (!row || row.scope !== "passive")
+            return fail("not-passive");
+        if (!this.pin)
+            return fail("no-pin");
+        const now = this.now();
+        if (!this.limit.take(row.id, now))
+            return fail("rate-limited", Math.max(1000, this.limit.retryAfterMs(row.id, now)));
+        const pin = normalizePin(raw);
+        if (!pin)
+            return fail("bad-request");
+        if (!this.pinMatches(pin))
+            return fail("wrong-pin");
+        this.lock(row.id, false);
+        const until = now + this.unlockMs;
+        const timer = setTimeout(() => this.lock(row.id), this.unlockMs);
+        timer.unref?.();
+        this.unlocked.set(row.id, { until, timer });
+        return { ok: true, unlockedUntil: until };
+    }
+    /** End a device's unlock ("Lock now", expiry, a PIN change). */
+    lock(id, notify = true) {
+        const u = this.unlocked.get(id);
+        if (!u)
+            return false;
+        clearTimeout(u.timer);
+        this.unlocked.delete(id);
+        if (notify)
+            this.onRelock(id);
+        return true;
+    }
+    /** Until when this device is unlocked, or null. The clock decides, not the timer. */
+    unlockedUntil(id) {
+        if (!id)
+            return null;
+        const u = this.unlocked.get(id);
+        if (!u)
+            return null;
+        if (u.until <= this.now()) {
+            this.lock(id);
+            return null;
+        }
+        return u.until;
+    }
+    /** Is this row a passive token that is NOT unlocked right now? */
+    restricted(row) {
+        return !!row && row.scope === "passive" && this.unlockedUntil(row.id) === null;
+    }
+}
+//# sourceMappingURL=passive.js.map

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

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

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

@@ -0,0 +1,67 @@
+/**
+ * The two containment guards, written once.
+ *
+ * Six files had hand-rolled the same three lines — `files.ts` twice, plus
+ * `git.ts`, `secrets.ts`, `tree.ts` and `builds.ts` — under six different
+ * names (`resolveInTree`, `pathInTree`, `inDir`, `inTree`, and twice inline).
+ * They agreed, which is the good case; the point of collapsing them is that
+ * nothing guarantees the seventh will.
+ *
+ * ── Why there are TWO of them, and not one ─────────────────────────────────
+ *
+ * `contained()` is LEXICAL: it normalises `..` and refuses anything that lands
+ * outside the root, and it does not resolve symlinks. `inRoot()` additionally
+ * resolves them (`realpathSync`). That difference is deliberate and neither is
+ * the "fixed" version of the other.
+ *
+ * `inRoot` guards the directories a client NAMES — `session.create` spawns
+ * `claude` in one, `build.run` executes a shell command in one — where the
+ * argument is an absolute path that arrives from outside and must be compared
+ * against `WATERPLANE_ROOT`. Both sides need realpath there or macOS's `/var` →
+ * `/private/var` makes an honest path look like an escape.
+ *
+ * `contained` guards a repo-RELATIVE path joined onto a worktree we already
+ * trust. Since the caller supplies the root, `..` is the whole attack surface
+ * and `resolve` handles it. It stays lexical because callers use it for paths
+ * that do not exist yet (a sweep of something already gone, a file to create).
+ *
+ * A symlink is NOT harmless, though: a COMMITTED `link -> ~/.ssh/id_rsa` is
+ * content from a clone, not something the person chose. So every path that
+ * READS or WRITES file bytes on a client's say-so goes through `containedReal`
+ * below, which realpaths an existing target and refuses one that resolves
+ * outside the worktree. In-repo symlinks (to elsewhere inside the worktree)
+ * keep working.
+ */
+export declare function contained(root: string, rel: string): string | null;
+/**
+ * `contained` plus the symlink rule: when the target exists, its realpath must
+ * lie inside the realpath of `root`. A dangling or looping link is refused too
+ * (nothing legitimate reads it). A target that does not exist is returned as
+ * `contained` would — creating is the caller's own check. Returns the LEXICAL
+ * path (what callers already display and relativise), not the resolved one.
+ *
+ * A target that does not exist yet is checked through its nearest existing
+ * ancestor (`evildir -> /tmp/x`, target `evildir/new.txt` is refused).
+ * TOCTOU: a symlink swapped in between this check and the open is not caught;
+ * only someone who already writes inside the worktree can race it.
+ */
+export declare function containedReal(root: string, rel: string): string | null;
+/**
+ * Keep a path inside the configured root — never write, and never SPAWN,
+ * outside it. Symlinks resolved on both sides; see above for why this one and
+ * `contained` differ.
+ *
+ * Pinned by `e2e-scaffold.mjs` and `e2e-rootguard.mjs`.
+ */
+export declare function inRoot(root: string, target: string): string | null;
+/**
+ * Resolve symlinks in a path that may not exist yet: realpath the deepest
+ * ancestor that does, then re-append the rest. Without this `inRoot` compares
+ * apples to oranges on macOS, where `/var` is a symlink to `/private/var` — the
+ * configured root stays `/var/…` while git hands back the resolved
+ * `/private/var/…`, and every path looks like an escape. A plain
+ * `realpathSync` with a lexical fallback is NOT equivalent: it falls all the
+ * way back for a leaf that does not exist yet, which is exactly the case a new
+ * worktree is in when it is named.
+ */
+export declare function realResolve(p: string): string;

package/packages/host/dist/paths.js

@@ -0,0 +1,135 @@
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { lstatSync, realpathSync } from "node:fs";
+/**
+ * The two containment guards, written once.
+ *
+ * Six files had hand-rolled the same three lines — `files.ts` twice, plus
+ * `git.ts`, `secrets.ts`, `tree.ts` and `builds.ts` — under six different
+ * names (`resolveInTree`, `pathInTree`, `inDir`, `inTree`, and twice inline).
+ * They agreed, which is the good case; the point of collapsing them is that
+ * nothing guarantees the seventh will.
+ *
+ * ── Why there are TWO of them, and not one ─────────────────────────────────
+ *
+ * `contained()` is LEXICAL: it normalises `..` and refuses anything that lands
+ * outside the root, and it does not resolve symlinks. `inRoot()` additionally
+ * resolves them (`realpathSync`). That difference is deliberate and neither is
+ * the "fixed" version of the other.
+ *
+ * `inRoot` guards the directories a client NAMES — `session.create` spawns
+ * `claude` in one, `build.run` executes a shell command in one — where the
+ * argument is an absolute path that arrives from outside and must be compared
+ * against `WATERPLANE_ROOT`. Both sides need realpath there or macOS's `/var` →
+ * `/private/var` makes an honest path look like an escape.
+ *
+ * `contained` guards a repo-RELATIVE path joined onto a worktree we already
+ * trust. Since the caller supplies the root, `..` is the whole attack surface
+ * and `resolve` handles it. It stays lexical because callers use it for paths
+ * that do not exist yet (a sweep of something already gone, a file to create).
+ *
+ * A symlink is NOT harmless, though: a COMMITTED `link -> ~/.ssh/id_rsa` is
+ * content from a clone, not something the person chose. So every path that
+ * READS or WRITES file bytes on a client's say-so goes through `containedReal`
+ * below, which realpaths an existing target and refuses one that resolves
+ * outside the worktree. In-repo symlinks (to elsewhere inside the worktree)
+ * keep working.
+ */
+export function contained(root, rel) {
+    const base = resolve(root);
+    const full = resolve(base, rel);
+    if (full !== base && !full.startsWith(base + sep))
+        return null;
+    return full;
+}
+/**
+ * `contained` plus the symlink rule: when the target exists, its realpath must
+ * lie inside the realpath of `root`. A dangling or looping link is refused too
+ * (nothing legitimate reads it). A target that does not exist is returned as
+ * `contained` would — creating is the caller's own check. Returns the LEXICAL
+ * path (what callers already display and relativise), not the resolved one.
+ *
+ * A target that does not exist yet is checked through its nearest existing
+ * ancestor (`evildir -> /tmp/x`, target `evildir/new.txt` is refused).
+ * TOCTOU: a symlink swapped in between this check and the open is not caught;
+ * only someone who already writes inside the worktree can race it.
+ */
+export function containedReal(root, rel) {
+    const full = contained(root, rel);
+    if (full === null)
+        return null;
+    let real = null;
+    let there = true;
+    try {
+        lstatSync(full);
+    }
+    catch {
+        there = false;
+    }
+    if (there) {
+        try {
+            real = realpathSync(full);
+        }
+        catch {
+            return null;
+        } // dangling or looping link
+    }
+    else {
+        // Not there yet: judge the nearest existing ancestor.
+        let anc = dirname(full);
+        for (;;) {
+            try {
+                real = realpathSync(anc);
+                break;
+            }
+            catch { /* keep climbing */ }
+            const up = dirname(anc);
+            if (up === anc)
+                return null;
+            anc = up;
+        }
+    }
+    const r = realResolve(root);
+    if (real !== r && !real.startsWith(r + sep))
+        return null;
+    return full;
+}
+/**
+ * Keep a path inside the configured root — never write, and never SPAWN,
+ * outside it. Symlinks resolved on both sides; see above for why this one and
+ * `contained` differ.
+ *
+ * Pinned by `e2e-scaffold.mjs` and `e2e-rootguard.mjs`.
+ */
+export function inRoot(root, target) {
+    const r = realResolve(root);
+    const t = realResolve(isAbsolute(target) ? target : resolve(root, target));
+    if (t !== r && !t.startsWith(r + sep))
+        return null;
+    return t;
+}
+/**
+ * Resolve symlinks in a path that may not exist yet: realpath the deepest
+ * ancestor that does, then re-append the rest. Without this `inRoot` compares
+ * apples to oranges on macOS, where `/var` is a symlink to `/private/var` — the
+ * configured root stays `/var/…` while git hands back the resolved
+ * `/private/var/…`, and every path looks like an escape. A plain
+ * `realpathSync` with a lexical fallback is NOT equivalent: it falls all the
+ * way back for a leaf that does not exist yet, which is exactly the case a new
+ * worktree is in when it is named.
+ */
+export function realResolve(p) {
+    let head = resolve(p);
+    const tail = [];
+    for (;;) {
+        try {
+            return join(realpathSync(head), ...tail.reverse());
+        }
+        catch { /* not there yet */ }
+        const parent = dirname(head);
+        if (parent === head)
+            return resolve(p); // hit the filesystem root
+        tail.push(head.slice(parent.length + 1));
+        head = parent;
+    }
+}
+//# sourceMappingURL=paths.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,GAAW;IACjD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAChC,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/D,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,GAAW;IACrD,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAClC,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,IAAI,IAAI,GAAkB,IAAI,CAAC;IAC/B,IAAI,KAAK,GAAG,IAAI,CAAC;IACjB,IAAI,CAAC;QAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,KAAK,GAAG,KAAK,CAAC;IAAC,CAAC;IACjD,IAAI,KAAK,EAAE,CAAC;QACV,IAAI,CAAC;YAAC,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,IAAI,CAAC;QAAC,CAAC,CAAG,2BAA2B;IACzF,CAAC;SAAM,CAAC;QACN,sDAAsD;QACtD,IAAI,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACxB,SAAS,CAAC;YACR,IAAI,CAAC;gBAAC,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;gBAAC,MAAM;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC;YACtE,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YACxB,IAAI,EAAE,KAAK,GAAG;gBAAE,OAAO,IAAI,CAAC;YAC5B,GAAG,GAAG,EAAE,CAAC;QACX,CAAC;IACH,CAAC;IACD,MAAM,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACzD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,MAAc;IACjD,MAAM,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,CAAC,GAAG,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3E,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,GAAG,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACnD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,IAAI,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtB,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,SAAS,CAAC;QACR,IAAI,CAAC;YAAC,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC;QACzF,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAG,0BAA0B;QACpE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;QACzC,IAAI,GAAG,MAAM,CAAC;IAChB,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,6 @@
+/** Expand a leading `~` or `~/` to the user's home dir; anything else is returned as is. */
+export declare function expandHome(p: string): string;
+/** An executable regular file. */
+export declare function isExecutable(p: string): boolean;
+/** The first executable `name` on `path`, then in `extra` dirs, or null. A file scan — no process is spawned. */
+export declare function onPath(name: string, path?: string, extra?: string[]): string | null;

package/packages/host/dist/pathx.js

@@ -0,0 +1,35 @@
+/**
+ * Path helpers shared across the host: `~` expansion and the PATH scan.
+ * Not `paths.ts` — that is the containment guard and stays small and separate.
+ */
+import { accessSync, constants, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+/** Expand a leading `~` or `~/` to the user's home dir; anything else is returned as is. */
+export function expandHome(p) {
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/"))
+        return join(homedir(), p.slice(2));
+    return p;
+}
+/** An executable regular file. */
+export function isExecutable(p) {
+    try {
+        accessSync(p, constants.X_OK);
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** The first executable `name` on `path`, then in `extra` dirs, or null. A file scan — no process is spawned. */
+export function onPath(name, path = process.env.PATH ?? "", extra = []) {
+    for (const d of [...path.split(delimiter).filter(Boolean), ...extra]) {
+        const p = join(d, name);
+        if (isExecutable(p))
+            return p;
+    }
+    return null;
+}
+//# sourceMappingURL=pathx.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pathx.js","sourceRoot":"","sources":["../src/pathx.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE5C,4FAA4F;AAC5F,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,OAAO,EAAE,CAAC;IAChC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,OAAO,CAAC,CAAC;AACX,CAAC;AAED,kCAAkC;AAClC,MAAM,UAAU,YAAY,CAAC,CAAS;IACpC,IAAI,CAAC;QAAC,UAAU,CAAC,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,KAAK,CAAC;IAAC,CAAC;AAC7F,CAAC;AAED,iHAAiH;AACjH,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,EAAE,QAAkB,EAAE;IACtF,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC;QACrE,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACxB,IAAI,YAAY,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/packages/host/dist/peers/agentpeer.d.ts

@@ -0,0 +1,58 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ServerCtx } from "../server/ctx.js";
+import { PeerJobs, type PeerJobRec } from "./jobs.js";
+export type GitRun = (cwd: string, args: string[]) => Promise<{
+    ok: boolean;
+    out: string;
+}>;
+export declare const runGit: GitRun;
+/**
+ * Is `commit` on `origin/<branch>`? The full sha, or why not. Asks the REMOTE (`ls-remote`), so a
+ * branch that was only committed locally is refused: the peer fetches from the shared remote.
+ */
+export declare function verifyPushed(cwd: string, branch: string, commit: string, git?: GitRun): Promise<{
+    ok: true;
+    commit: string;
+} | {
+    ok: false;
+    error: string;
+}>;
+export interface PeerAgentDeps {
+    jobs: Pick<PeerJobs, "get" | "list" | "submit" | "cancel">;
+    containRepoDir(dir: unknown): Promise<string | null>;
+    repoDir(id: string): Promise<string | null>;
+    sessionCwd(id: string): string | null;
+    /** The newest live session whose cwd is exactly `dir`. */
+    runningSessionFor(dir: string): string | null;
+    /** A session's label as a picker names it (`sessionPickLabel`); absent = unknown. */
+    sessionLabel?(id: string): string | null | undefined;
+    git?: GitRun;
+    now?: () => number;
+}
+export interface PeerAgentIo {
+    json(res: ServerResponse, data: unknown, status?: number): void;
+    readJson(req: IncomingMessage): Promise<any>;
+}
+/** A job as the agent reads it: the state, the peer's words, and — once it is in — the report. */
+export declare function peerJobView(r: PeerJobRec): {
+    cost?: import("@waterplane/shared").PeerJobCost | undefined;
+    reported?: boolean | undefined;
+    peerSession?: string | undefined;
+    detail?: string | undefined;
+    unreachableSince?: number | undefined;
+    waiting?: string | undefined;
+    closed?: boolean | undefined;
+    id: string;
+    peer: string;
+    state: import("@waterplane/shared").PeerJobLocalState;
+    branch: string;
+    commit: string;
+};
+/** `true` when the request was this route's (answered, or refused). */
+export declare function makePeerAgentHandler(d: PeerAgentDeps): (req: IncomingMessage, res: ServerResponse, path: string, _url: URL, io: PeerAgentIo) => Promise<boolean>;
+/** Mounted in `api.ts`; a no-op until `startPeerJobs` has run (and under `--doctor`, forever). */
+export declare function handlePeerAgent(req: IncomingMessage, res: ServerResponse, path: string, url: URL, io: PeerAgentIo): Promise<boolean>;
+/** The bytes of a peer's artifact into the repo's outbox as `peer-<peer>-<stem>`; the repo-relative path. */
+export declare function saveOutboxArtifact(cwd: string, peer: string, name: string, bytes: Buffer): string | null;
+/** Build the job machine from the host's parts, mount the route, resume open jobs. Called from `main.ts` after `intents.start()`. */
+export declare function startPeerJobs(ctx: ServerCtx): PeerJobs | null;