parawatch 0.3.15 → 0.3.16

package/README.md

@@ -46,6 +46,8 @@ parawatch sync setup ~/agent-sync/parawatch --device pc  --adapter syncthing
 
 Cards, answers and the list of running sessions then show on every machine, each marked with where it came from. Agent logs stay on the machine that wrote them. The details are in [More than one machine](docs/sync.md).
 
+Or run a [relay](docs/relay.md) of your own, a small server that carries the folder sealed end to end, so the server cannot read your cards or sessions: `parawatch relay setup <url> <folder>` on the first machine, `parawatch relay join <code> <folder>` on the others.
+
 ## How an answer gets back
 
 <picture>
@@ -133,6 +135,8 @@ This writes a short block that tells the agents in that project to say what they
 | [Pull requests](docs/pull-requests.md) | What is read from GitHub, and its settings |
 | [Observed agents](docs/observed-agents.md) | Which logs are read, run states, adding a runtime |
 | [More than one machine](docs/sync.md) | Cards and answers across machines through a synced folder |
+| [The relay](docs/relay.md) | Your own server that carries the shared folder, sealed end to end |
+| [The shared folder](docs/protocol.md) | The files machines exchange, for anyone writing a client |
 | [Storage](docs/storage.md) | Where everything is kept, notifications |
 | [Installing, updating, removing](docs/install.md) | The three parts in detail, updates, `parawatch doctor`, uninstalling |
 | [Building on it](docs/integrations.md) | `status --json`, `watch`, the panel package |

package/dist/bin/cli.js

@@ -7,10 +7,12 @@ import { githubConfig, readCache, resolvePrRef, syncGithub, prViews } from "../c
 import { recordPrompt } from "../core/prompts.js";
 import { callingSubagent } from "../adapters/claudeCode.js";
 import { digest, digestText, localDate } from "../core/digest.js";
-import { everywhere, readEvents } from "../core/store.js";
+import { everywhere, readConfig, readEvents, sharedDir, writeConfig } from "../core/store.js";
 import { followEvents } from "../core/follow.js";
 import { adapterNames, setRoot, setupSync, syncAdapter, syncStatus, touchDevice } from "../core/sync.js";
 import { syncText } from "../core/format.js";
+import { RelayClient, RelayMirror, joinCode, newKey, readJoinCode, relayConfig, takeMirrorLock } from "../core/relay.js";
+import { createRelayServer } from "../relay/server.js";
 import { collectRuns, shareRunsDue } from "../core/runs.js";
 import { askRows, cardDetail, cardLine, cardRows, inboxLine, prRows, runsTree, view } from "../core/format.js";
 import { hookContext, notify, removeInstructions, writeInstructions } from "../core/integrate.js";
@@ -648,6 +650,103 @@ sync
     const d = setRoot(name, folder, VERSION);
     process.stdout.write(Object.entries(d.roots ?? {}).map(([k, v]) => `${k}  ${v}`).join("\n") + (d.roots ? "\n" : "No named folders.\n"));
 });
+// ------------------------------------------------------------------ the relay
+const relay = program.command("relay").description("keep the shared folder in step through a parawatch relay server instead of a sync tool");
+/** Point this machine's shared folder at a relay, keeping what config.json already has. */
+function useRelay(folder, device, c) {
+    const r = setupSync({ dir: folder, device, adapter: "relay", version: VERSION });
+    const cfg = readConfig();
+    writeConfig({ ...cfg, sync: { ...(cfg.sync ?? {}), adapter: "relay", relay: c } });
+    return r;
+}
+relay
+    .command("setup <url> <folder>")
+    .description("make a space on a relay and share this machine's folder through it; prints the code for your other machines")
+    .option("-d, --device <name>", "this machine's name in the folder (a-z, 0-9, -); defaults to the host name")
+    .option("--invite <invite>", "the relay's invite (or set PARAWATCH_RELAY_INVITE)")
+    .action(async (url, folder, o) => {
+    const invite = o.invite ?? process.env.PARAWATCH_RELAY_INVITE;
+    if (!invite)
+        throw new UserError("the relay needs its invite to make a space: pass --invite or set PARAWATCH_RELAY_INVITE");
+    const base = url.replace(/\/+$/, "");
+    const made = await RelayClient.createSpace(base, invite);
+    const c = { url: base, space: made.space, token: made.token, key: newKey() };
+    const r = useRelay(folder, o.device, c);
+    process.stdout.write([
+        `This machine shares ${r.dir} as "${r.device}" through ${base}.`,
+        "On each of your other machines, run:",
+        "",
+        `  parawatch relay join <code> <folder> --device <its name>`,
+        "",
+        "with this code. It opens your space and its key: keep it to your own machines.",
+        "",
+        joinCode(c),
+        "",
+        "The folder is kept in step while the app runs, or while `parawatch relay run` does.",
+    ].join("\n") + "\n");
+});
+relay
+    .command("join <code> <folder>")
+    .description("share this machine's folder through the relay another machine set up")
+    .option("-d, --device <name>", "this machine's name in the folder (a-z, 0-9, -); defaults to the host name")
+    .action(async (code, folder, o) => {
+    const c = readJoinCode(code);
+    await new RelayClient(c).changes(0);
+    const r = useRelay(folder, o.device, c);
+    process.stdout.write(`This machine shares ${r.dir} as "${r.device}" through ${c.url}. The folder is kept in step while the app runs, or while \`parawatch relay run\` does.\n`);
+});
+relay
+    .command("code")
+    .description("print the code that lets another of your machines join (it holds the space key)")
+    .action(() => {
+    const c = relayConfig();
+    if (!c)
+        throw new UserError("this machine does not use a relay");
+    process.stdout.write(joinCode(c) + "\n");
+});
+relay
+    .command("run")
+    .description("keep the shared folder in step with the relay until stopped (the app does this while it runs)")
+    .option("--once", "bring it up to date once and stop")
+    .action(async (o) => {
+    const c = relayConfig();
+    const dir = sharedDir();
+    if (!c || !dir)
+        throw new UserError("this machine does not use a relay: run `parawatch relay setup` or `parawatch relay join` first");
+    const unlock = takeMirrorLock();
+    if (!unlock)
+        throw new UserError("another parawatch (the app, or another `relay run`) already keeps this folder in step");
+    const m = new RelayMirror({ dir, config: c, log: (l) => process.stderr.write(l + "\n") });
+    try {
+        if (o.once) {
+            const r = await m.once();
+            process.stdout.write(`brought down ${r.pulled}, sent up ${r.pushed}\n`);
+            return;
+        }
+        const stop = () => m.stop();
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+        process.stderr.write(`keeping ${dir} in step with ${c.url}; stop with Ctrl-C\n`);
+        await m.run();
+    }
+    finally {
+        unlock();
+    }
+});
+relay
+    .command("serve")
+    .description("run a relay server (for your own server; machines reach it over HTTPS through a proxy in front)")
+    .option("--port <n>", "port to listen on", "8787")
+    .option("--host <host>", "address to listen on", "127.0.0.1")
+    .option("--data <folder>", "where spaces are kept", "~/.parawatch-relay")
+    .action((o) => {
+    const invite = process.env.PARAWATCH_RELAY_INVITE;
+    const data = o.data.startsWith("~") ? o.data.replace(/^~/, process.env.HOME ?? process.env.USERPROFILE ?? "") : o.data;
+    const server = createRelayServer({ dataDir: data, invite, log: (l) => process.stdout.write(`${new Date().toISOString()} ${l}\n`) });
+    server.listen(Number(o.port), o.host, () => {
+        process.stdout.write(`relay on http://${o.host}:${o.port}, spaces in ${data}${invite ? "" : " (no PARAWATCH_RELAY_INVITE: no new spaces can be made)"}\n`);
+    });
+});
 program
     .command("hook <runtime>")
     .description("hook entry point; 'claude-code' reads the hook JSON on stdin")

package/dist/core/codexChat.js

@@ -132,6 +132,7 @@ export function readChatLines(head, tail, file = "") {
     const items = new Map();
     let started = -1;
     let ended = -1;
+    let turnAt;
     let structured = false;
     const fallback = [];
     tail.forEach((r, i) => {
@@ -148,8 +149,10 @@ export function readChatLines(head, tail, file = "") {
             return;
         }
         if (r.type === "event_msg") {
-            if (p.type === "task_started")
+            if (p.type === "task_started") {
                 started = i;
+                turnAt = at;
+            }
             else if (p.type === "task_complete")
                 ended = i;
             else if (p.type === "turn_aborted") {
@@ -186,6 +189,7 @@ export function readChatLines(head, tail, file = "") {
         ...(firstUser ? { title: firstUser.text.split("\n")[0].slice(0, 80) } : {}),
         settings,
         working: started > ended,
+        ...(started > ended && turnAt ? { turnStarted: turnAt } : {}),
         items: all.slice(-MAX_ITEMS),
         earlier: Math.max(0, all.length - MAX_ITEMS),
     };
@@ -230,7 +234,7 @@ export function findCodex(env = process.env, platform = process.platform) {
     const dirs = [
         ...(env.PATH ?? "").split(path.delimiter),
         ...(platform === "win32"
-            ? [env.APPDATA && path.join(env.APPDATA, "npm"), env.LOCALAPPDATA && path.join(env.LOCALAPPDATA, "Programs", "codex")]
+            ? [env.APPDATA && path.join(env.APPDATA, "npm"), env.LOCALAPPDATA && path.join(env.LOCALAPPDATA, "Programs", "OpenAI", "Codex", "bin"), env.LOCALAPPDATA && path.join(env.LOCALAPPDATA, "Programs", "codex")]
             : ["/opt/homebrew/bin", "/usr/local/bin", path.join(home, ".local", "bin"), path.join(home, ".npm-global", "bin"), path.join(home, ".volta", "bin"), path.join(home, ".bun", "bin")]),
     ].filter((d) => !!d);
     for (const d of dirs) {

package/dist/core/relay.js

@@ -0,0 +1,474 @@
+/**
+ * Keeping the shared folder in step through a relay server (src/relay/server.ts) instead of a sync
+ * tool. The folder stays where it is on every machine; this mirror uploads what changed here and
+ * writes what changed elsewhere, file by file.
+ *
+ * Everything is sealed on the machine with the space key, which the server never sees: a file's
+ * path and its bytes go in one AES-256-GCM box, and the server knows it only by a keyed hash of the
+ * path. The server sees how many files there are, their sizes and when they change.
+ *
+ * The join code carries the server, the space, its token and the key. Anyone with it can read and
+ * write the space, so it is passed between one's own machines by hand.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { UserError } from "./errors.js";
+import { homeDir, readConfig } from "./store.js";
+import { findConflicts, folderPeers } from "./sync.js";
+const CODE_PREFIX = "pwr1.";
+/** Files bigger than this stay on their machine (a long screen recording, say). */
+export const MIRROR_MAX_FILE = 200 * 1024 * 1024;
+function keysOf(key) {
+    const raw = Buffer.from(key, "base64url");
+    if (raw.length !== 32)
+        throw new UserError("the relay key is not 32 bytes; join again with a fresh code");
+    const derive = (info) => Buffer.from(crypto.hkdfSync("sha256", raw, Buffer.alloc(0), info, 32));
+    return { enc: derive("parawatch relay seal v1"), name: derive("parawatch relay name v1") };
+}
+/** The name the server knows a path by. */
+export function sealedName(keys, rel) {
+    return crypto.createHmac("sha256", keys.name).update(rel).digest("hex").slice(0, 40);
+}
+/** One box: version, nonce, tag, then the path and the bytes, encrypted together. */
+export function seal(keys, rel, data) {
+    const iv = crypto.randomBytes(12);
+    const c = crypto.createCipheriv("aes-256-gcm", keys.enc, iv);
+    const p = Buffer.from(rel, "utf8");
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(p.length);
+    const body = Buffer.concat([c.update(len), c.update(p), c.update(data), c.final()]);
+    return Buffer.concat([Buffer.from([1]), iv, c.getAuthTag(), body]);
+}
+export function open(keys, box) {
+    if (box.length < 29 || box[0] !== 1)
+        throw new Error("not a sealed parawatch file");
+    const d = crypto.createDecipheriv("aes-256-gcm", keys.enc, box.subarray(1, 13));
+    d.setAuthTag(box.subarray(13, 29));
+    const plain = Buffer.concat([d.update(box.subarray(29)), d.final()]);
+    const n = plain.readUInt32BE(0);
+    return { rel: plain.subarray(4, 4 + n).toString("utf8"), data: plain.subarray(4 + n) };
+}
+export function newKey() {
+    return crypto.randomBytes(32).toString("base64url");
+}
+// ------------------------------------------------------------------ join codes
+export function joinCode(c) {
+    return CODE_PREFIX + Buffer.from(JSON.stringify({ u: c.url, s: c.space, t: c.token, k: c.key })).toString("base64url");
+}
+export function readJoinCode(code) {
+    const t = code.trim();
+    if (!t.startsWith(CODE_PREFIX))
+        throw new UserError("that is not a parawatch relay code (it starts with pwr1.)");
+    try {
+        const o = JSON.parse(Buffer.from(t.slice(CODE_PREFIX.length), "base64url").toString("utf8"));
+        if (typeof o.u !== "string" || typeof o.s !== "string" || typeof o.t !== "string" || typeof o.k !== "string")
+            throw new Error("missing parts");
+        keysOf(o.k);
+        return { url: o.u.replace(/\/+$/, ""), space: o.s, token: o.t, key: o.k };
+    }
+    catch (err) {
+        if (err instanceof UserError)
+            throw err;
+        throw new UserError("that relay code is cut short or changed; copy it again");
+    }
+}
+/** The relay this machine uses, from config.json, when its sync adapter is the relay. */
+export function relayConfig() {
+    const s = readConfig().sync;
+    if (s?.adapter !== "relay")
+        return undefined;
+    const r = s.relay;
+    return r && r.url && r.space && r.token && r.key ? r : undefined;
+}
+export class RelayClient {
+    c;
+    f;
+    constructor(c, f = fetch) {
+        this.c = c;
+        this.f = f;
+    }
+    base() {
+        return `${this.c.url}/v1/spaces/${this.c.space}`;
+    }
+    async call(pathname, init = {}, signal) {
+        const res = await this.f(`${this.base()}${pathname}`, { ...init, signal, headers: { ...(init.headers ?? {}), authorization: `Bearer ${this.c.token}` } });
+        if (!res.ok) {
+            let why = `${res.status}`;
+            try {
+                why = (await res.json()).error ?? why;
+            }
+            catch {
+                // not JSON
+            }
+            throw new Error(`relay ${init.method ?? "GET"} ${pathname.split("/")[1]}: ${why}`);
+        }
+        return res;
+    }
+    async changes(after, wait = 0, signal) {
+        return (await (await this.call(`/changes?after=${after}&wait=${wait}`, {}, signal)).json());
+    }
+    async get(name) {
+        return Buffer.from(await (await this.call(`/files/${name}`)).arrayBuffer());
+    }
+    async put(name, body) {
+        return (await (await this.call(`/files/${name}`, { method: "PUT", body: new Uint8Array(body), headers: { "content-type": "application/octet-stream" } })).json()).seq;
+    }
+    async remove(name) {
+        return (await (await this.call(`/files/${name}`, { method: "DELETE" })).json()).seq;
+    }
+    static async createSpace(url, invite, f = fetch) {
+        const res = await f(`${url.replace(/\/+$/, "")}/v1/spaces`, { method: "POST", headers: { authorization: `Bearer ${invite}` } });
+        if (!res.ok) {
+            let why = `${res.status}`;
+            try {
+                why = (await res.json()).error ?? why;
+            }
+            catch {
+                // not JSON
+            }
+            throw new UserError(`the relay would not make a space: ${why}`);
+        }
+        return (await res.json());
+    }
+}
+export function mirrorStatePath() {
+    return path.join(homeDir(), "relay-state.json");
+}
+export function readMirrorState(space, file = mirrorStatePath()) {
+    try {
+        const s = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (s.v === 1 && s.space === space && s.files)
+            return s;
+    }
+    catch {
+        // none yet
+    }
+    return { v: 1, space, cursor: 0, files: {} };
+}
+/** Files the mirror leaves alone: hidden and temporary files, and copies a sync tool made. */
+function ignored(rel) {
+    return rel.split("/").some((p) => p.startsWith(".") || p.endsWith(".tmp") || /\.sync-conflict-/.test(p) || p === "~syncthing~");
+}
+/** Is `rel` a safe relative path inside the folder? A sealed file names its own path. */
+function safeRel(rel) {
+    return !!rel && !rel.startsWith("/") && !/^[a-zA-Z]:/.test(rel) && !rel.split("/").some((p) => p === ".." || p === "" || p === ".") && !rel.includes("\\");
+}
+const hashOf = (b) => crypto.createHash("sha256").update(b).digest("hex");
+export class RelayMirror {
+    o;
+    keys;
+    client;
+    state;
+    names = new Map();
+    stopped = false;
+    abort;
+    pushing = false;
+    constructor(o) {
+        this.o = o;
+        this.keys = keysOf(o.config.key);
+        this.client = new RelayClient(o.config, o.fetch);
+        this.state = readMirrorState(o.config.space, o.stateFile);
+        for (const rel of Object.keys(this.state.files))
+            this.names.set(sealedName(this.keys, rel), rel);
+    }
+    save() {
+        try {
+            const file = this.o.stateFile ?? mirrorStatePath();
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(`${file}.tmp`, JSON.stringify(this.state) + "\n");
+            fs.renameSync(`${file}.tmp`, file);
+        }
+        catch {
+            // kept in memory; the next save writes it
+        }
+    }
+    log(line) {
+        this.o.log?.(line);
+    }
+    /** Every file in the folder, as relative paths with forward slashes. */
+    scan() {
+        const out = new Map();
+        const walk = (dir, rel) => {
+            let entries = [];
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const e of entries) {
+                const r = rel ? `${rel}/${e.name}` : e.name;
+                if (ignored(r))
+                    continue;
+                const p = path.join(dir, e.name);
+                if (e.isDirectory())
+                    walk(p, r);
+                else if (e.isFile()) {
+                    try {
+                        const st = fs.statSync(p);
+                        out.set(r, { size: st.size, mtime: st.mtimeMs });
+                    }
+                    catch {
+                        // gone meanwhile
+                    }
+                }
+            }
+        };
+        walk(this.o.dir, "");
+        return out;
+    }
+    /** Bring down what changed on the server since the last look; `wait` holds until something does. */
+    async pull(wait = 0) {
+        this.abort = new AbortController();
+        const { head, changes } = await this.client.changes(this.state.cursor, wait, this.abort.signal);
+        let n = 0;
+        for (const ch of changes) {
+            const known = this.names.get(ch.name);
+            if (ch.deleted) {
+                if (known) {
+                    const p = path.join(this.o.dir, ...known.split("/"));
+                    const k = this.state.files[known];
+                    // only a file this machine has not changed since goes away
+                    try {
+                        const buf = fs.readFileSync(p);
+                        if (k && hashOf(buf) === k.hash)
+                            fs.rmSync(p, { force: true });
+                    }
+                    catch {
+                        // already gone
+                    }
+                    delete this.state.files[known];
+                    this.names.delete(ch.name);
+                    n++;
+                }
+                continue;
+            }
+            if ((ch.size ?? 0) > MIRROR_MAX_FILE + 1024)
+                continue;
+            let rel;
+            let data;
+            try {
+                ({ rel, data } = open(this.keys, await this.client.get(ch.name)));
+            }
+            catch (err) {
+                this.log(`could not open a file from the relay: ${err.message}`);
+                continue;
+            }
+            if (!safeRel(rel) || ignored(rel) || sealedName(this.keys, rel) !== ch.name) {
+                this.log(`left out a file with a path it may not have: ${JSON.stringify(rel)}`);
+                continue;
+            }
+            const p = path.join(this.o.dir, ...rel.split("/"));
+            const hash = hashOf(data);
+            const k = this.state.files[rel];
+            let here;
+            try {
+                here = fs.readFileSync(p);
+            }
+            catch {
+                // not here yet
+            }
+            const hereHash = here ? hashOf(here) : undefined;
+            // a change made here that has not gone up yet wins; it goes up on the next push
+            if (here && k && hereHash !== k.hash && hereHash !== hash)
+                continue;
+            if (hereHash !== hash) {
+                fs.mkdirSync(path.dirname(p), { recursive: true });
+                const tmp = path.join(path.dirname(p), `.${path.basename(p)}.relay.tmp`);
+                fs.writeFileSync(tmp, data);
+                fs.renameSync(tmp, p);
+                n++;
+            }
+            const st = fs.statSync(p);
+            this.state.files[rel] = { hash, size: st.size, mtime: st.mtimeMs };
+            this.names.set(ch.name, rel);
+        }
+        this.state.cursor = head;
+        this.state.lastOk = new Date().toISOString();
+        this.state.error = undefined;
+        this.save();
+        return n;
+    }
+    /** Send up what changed here since the last look. */
+    async push() {
+        if (this.pushing)
+            return 0;
+        this.pushing = true;
+        try {
+            if (!fs.existsSync(this.o.dir))
+                throw new Error(`the shared folder ${this.o.dir} is not there`);
+            const seen = this.scan();
+            let n = 0;
+            let pending = 0;
+            const skipped = [];
+            for (const [rel, st] of seen) {
+                const k = this.state.files[rel];
+                if (k && k.size === st.size && k.mtime === st.mtime)
+                    continue;
+                if (st.size > MIRROR_MAX_FILE) {
+                    skipped.push(rel);
+                    continue;
+                }
+                let data;
+                try {
+                    data = fs.readFileSync(path.join(this.o.dir, ...rel.split("/")));
+                }
+                catch {
+                    continue;
+                }
+                const hash = hashOf(data);
+                if (k && k.hash === hash) {
+                    this.state.files[rel] = { ...k, size: st.size, mtime: st.mtime };
+                    continue;
+                }
+                pending++;
+                const name = sealedName(this.keys, rel);
+                await this.client.put(name, seal(this.keys, rel, data));
+                this.state.files[rel] = { hash, size: st.size, mtime: st.mtime };
+                this.names.set(name, rel);
+                pending--;
+                n++;
+            }
+            // a folder that reads as empty while files were here is more likely unmounted than emptied
+            const vanished = Object.keys(this.state.files).filter((rel) => !seen.has(rel) && !ignored(rel));
+            if (vanished.length && !seen.size)
+                throw new Error(`the shared folder ${this.o.dir} reads as empty; nothing was deleted on the relay`);
+            for (const rel of vanished) {
+                const name = sealedName(this.keys, rel);
+                await this.client.remove(name);
+                delete this.state.files[rel];
+                this.names.delete(name);
+                n++;
+            }
+            this.state.pending = pending;
+            this.state.skipped = skipped.length ? skipped.slice(0, 20) : undefined;
+            if (n)
+                this.save();
+            return n;
+        }
+        finally {
+            this.pushing = false;
+        }
+    }
+    /** Pull first so a machine joining late takes what is there instead of sending it back. */
+    async once() {
+        const pulled = await this.pull(0);
+        const pushed = await this.push();
+        return { pulled, pushed };
+    }
+    /** Keep the folder in step until stopped: a held request for changes there, a look here every second. */
+    async run() {
+        let backoff = 1000;
+        const pushLoop = async () => {
+            while (!this.stopped) {
+                try {
+                    await this.push();
+                }
+                catch (err) {
+                    this.fail(err);
+                }
+                await sleep(1000);
+            }
+        };
+        try {
+            await this.pull(0);
+        }
+        catch (err) {
+            this.fail(err);
+        }
+        void pushLoop();
+        while (!this.stopped) {
+            try {
+                await this.pull(25);
+                backoff = 1000;
+            }
+            catch (err) {
+                if (this.stopped)
+                    break;
+                this.fail(err);
+                await sleep(backoff);
+                backoff = Math.min(backoff * 2, 60_000);
+            }
+        }
+    }
+    fail(err) {
+        const msg = err.message ?? String(err);
+        if (this.state.error !== msg)
+            this.log(`relay: ${msg}`);
+        this.state.error = msg;
+        this.save();
+    }
+    stop() {
+        this.stopped = true;
+        this.abort?.abort();
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Only one mirror per machine: the app and `parawatch relay run` would otherwise race. */
+export function takeMirrorLock() {
+    const file = path.join(homeDir(), "relay.pid");
+    try {
+        const pid = Number(fs.readFileSync(file, "utf8"));
+        if (pid && pid !== process.pid) {
+            try {
+                process.kill(pid, 0);
+                return undefined;
+            }
+            catch (err) {
+                if (err.code === "EPERM")
+                    return undefined;
+            }
+        }
+    }
+    catch {
+        // no lock
+    }
+    fs.mkdirSync(homeDir(), { recursive: true });
+    fs.writeFileSync(file, String(process.pid));
+    return () => {
+        try {
+            if (fs.readFileSync(file, "utf8").trim() === String(process.pid))
+                fs.rmSync(file, { force: true });
+        }
+        catch {
+            // gone
+        }
+    };
+}
+// ------------------------------------------------------------------ status
+/** How the mirror is doing, for `parawatch sync`, `doctor` and the app. */
+export const relayAdapter = {
+    name: "relay",
+    about: "a parawatch relay server, sealed end to end",
+    async status(ctx) {
+        const c = relayConfig();
+        const peers = folderPeers(ctx.dir, ctx.device);
+        if (!c)
+            return { adapter: "relay", dir: ctx.dir, device: ctx.device, ok: false, peers, conflicts: [], error: "no relay is set up: run `parawatch relay setup` or `parawatch relay join`" };
+        const st = readMirrorState(c.space);
+        let reachable = true;
+        let error = st.error;
+        try {
+            const res = await (ctx.fetch ?? fetch)(`${c.url}/healthz`, { signal: AbortSignal.timeout(ctx.timeoutMs ?? 3000) });
+            reachable = res.ok;
+        }
+        catch (err) {
+            reachable = false;
+            error = `cannot reach ${c.url}: ${err.message}`;
+        }
+        const fresh = !!st.lastOk && Date.now() - Date.parse(st.lastOk) < 2 * 60_000;
+        return {
+            adapter: "relay",
+            dir: ctx.dir,
+            device: ctx.device,
+            ok: reachable && fresh && !st.error,
+            lastSync: st.lastOk,
+            peers,
+            conflicts: findConflicts(ctx.dir),
+            ...(st.pending ? { pending: st.pending } : {}),
+            ...(error ? { error } : !fresh ? { error: "nothing is keeping the folder in step: open the app, or run `parawatch relay run`" } : {}),
+        };
+    },
+};
+//# sourceMappingURL=relay.js.map

package/dist/core/remoteChat.js

@@ -0,0 +1,212 @@
+/**
+ * Codex conversations of another machine. The log and the codex command stay on the machine the
+ * session ran on (the host); the machine showing it (the viewer) asks through the shared folder:
+ *
+ *   chats/<viewer>/watching.json   the sessions the viewer has open, rewritten while they are
+ *   chats/<viewer>/asks.jsonl      messages to send and stops, written by the viewer only
+ *   chats/<host>/<session>.json    the conversation as the host reads it, rewritten as it changes
+ *
+ * Every file has one writer, so the sync tool never has two versions of one to reconcile.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { DEVICE_NAME, deviceName, sharedDir } from "./store.js";
+/** How often a viewer says it still has its chats open, and when a host stops serving one. */
+export const WATCH_EVERY_MS = 20_000;
+export const WATCH_GONE_MS = 75_000;
+/** How often a host rewrites a watched chat that did not change, and when the viewer gives up on it. */
+export const HOST_BEAT_MS = 30_000;
+export const HOST_QUIET_MS = 100_000;
+/** A message that took longer than this to reach the host is not sent: the person has moved on. */
+export const ASK_LATE_MS = 2 * 60_000;
+/** How long asks and their results are kept. */
+export const ASK_KEEP_MS = 10 * 60_000;
+/** The most conversation items a host shares; the rest count as earlier. */
+export const SHARED_ITEMS = 150;
+/** The first version whose app answers for its Codex sessions. */
+export const REMOTE_CHAT_SINCE = "0.3.16";
+const SESSION_ID = /^[A-Za-z0-9_-]{1,80}$/;
+export function validSession(id) {
+    return SESSION_ID.test(id);
+}
+function chatsDir(shared = sharedDir()) {
+    return shared ? path.join(shared, "chats") : undefined;
+}
+function writeAtomic(file, body) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.tmp`);
+    fs.writeFileSync(tmp, body);
+    fs.renameSync(tmp, file);
+}
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The machines with a folder under `chats/`, other than this one. */
+function otherDevices(dir, me) {
+    try {
+        return fs.readdirSync(dir).filter((n) => DEVICE_NAME.test(n) && n !== me);
+    }
+    catch {
+        return [];
+    }
+}
+// ------------------------------------------------------------------ viewer
+/** Say which sessions of other machines this one has open. */
+export function writeWatching(open, now = Date.now(), shared = sharedDir()) {
+    const dir = chatsDir(shared);
+    if (!dir)
+        return;
+    const me = deviceName();
+    const body = { v: 1, device: me, at: new Date(now).toISOString(), open };
+    try {
+        writeAtomic(path.join(dir, me, "watching.json"), JSON.stringify(body) + "\n");
+    }
+    catch {
+        // the folder may be busy syncing; the next beat writes it again
+    }
+}
+/** Add a message or a stop for a host, dropping asks old enough that no host still needs them. */
+export function appendAsk(a, now = Date.now(), shared = sharedDir()) {
+    const dir = chatsDir(shared);
+    if (!dir)
+        throw new Error("This machine shares no folder with others.");
+    const me = deviceName();
+    const ask = { id: `${me}-${now.toString(36)}-${crypto.randomBytes(3).toString("hex")}`, at: new Date(now).toISOString(), ...a };
+    const file = path.join(dir, me, "asks.jsonl");
+    const kept = readAskLines(file).filter((x) => now - Date.parse(x.at) < ASK_KEEP_MS);
+    writeAtomic(file, [...kept, ask].map((x) => JSON.stringify(x) + "\n").join(""));
+    return ask;
+}
+/** What the host last wrote about a session, if anything. */
+export function readHosted(host, id, shared = sharedDir()) {
+    const dir = chatsDir(shared);
+    if (!dir || !DEVICE_NAME.test(host) || !validSession(id))
+        return undefined;
+    const h = readJson(path.join(dir, host, `${id}.json`));
+    return h && h.v === 1 && h.id === id ? h : undefined;
+}
+export function hostedPath(host, id, shared = sharedDir()) {
+    const dir = chatsDir(shared);
+    return dir && DEVICE_NAME.test(host) && validSession(id) ? path.join(dir, host, `${id}.json`) : undefined;
+}
+// ------------------------------------------------------------------ host
+/** The sessions of this machine that another machine has open now, and which machines. */
+export function watchedHere(now = Date.now(), shared = sharedDir()) {
+    const dir = chatsDir(shared);
+    const out = new Map();
+    if (!dir)
+        return out;
+    const me = deviceName();
+    for (const d of otherDevices(dir, me)) {
+        const w = readJson(path.join(dir, d, "watching.json"));
+        if (!w || !Array.isArray(w.open) || now - Date.parse(w.at) > WATCH_GONE_MS)
+            continue;
+        for (const o of w.open) {
+            if (o?.host !== me || typeof o.id !== "string" || !validSession(o.id))
+                continue;
+            out.set(o.id, [...(out.get(o.id) ?? []), d]);
+        }
+    }
+    return out;
+}
+function readAskLines(file) {
+    let text = "";
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const a = JSON.parse(line);
+            if (typeof a.id === "string" && typeof a.session === "string" && Number.isFinite(Date.parse(a.at)) && (a.op === "send" || a.op === "stop"))
+                out.push(a);
+        }
+        catch {
+            // a line half written by the sync tool; it is whole next time
+        }
+    }
+    return out;
+}
+/** Asks other machines left for this one, oldest first. */
+export function asksHere(shared = sharedDir()) {
+    const dir = chatsDir(shared);
+    if (!dir)
+        return [];
+    const me = deviceName();
+    const out = [];
+    for (const d of otherDevices(dir, me)) {
+        for (const a of readAskLines(path.join(dir, d, "asks.jsonl"))) {
+            // an ask names its own machine in its id, so one machine cannot answer for another
+            if (a.host === me && a.id.startsWith(`${d}-`) && validSession(a.session))
+                out.push(a);
+        }
+    }
+    return out.sort((a, b) => a.at.localeCompare(b.at));
+}
+/** The conversation with only its latest items, so the shared file stays small. */
+export function slimState(s, max = SHARED_ITEMS) {
+    if (!s.view || s.view.items.length <= max)
+        return s;
+    const cut = s.view.items.length - max;
+    return { ...s, view: { ...s.view, items: s.view.items.slice(cut), earlier: s.view.earlier + cut } };
+}
+export function writeHosted(h, shared = sharedDir()) {
+    const me = deviceName();
+    const file = hostedPath(me, h.id, shared);
+    if (!file)
+        return;
+    const body = { v: 1, host: me, ...h, state: slimState(h.state) };
+    try {
+        writeAtomic(file, JSON.stringify(body) + "\n");
+    }
+    catch {
+        // the folder may be busy syncing; the next change or beat writes it again
+    }
+}
+export function removeHosted(id, shared = sharedDir()) {
+    const file = hostedPath(deviceName(), id, shared);
+    if (!file)
+        return;
+    try {
+        fs.rmSync(file, { force: true });
+    }
+    catch {
+        // gone or busy; nobody reads it once it is not watched
+    }
+}
+/** Asks this machine already handled, read back from what it wrote, so a restart does not send twice. */
+export function handledHere(shared = sharedDir()) {
+    const dir = chatsDir(shared);
+    const out = new Map();
+    if (!dir)
+        return out;
+    const mine = path.join(dir, deviceName());
+    let names = [];
+    try {
+        names = fs.readdirSync(mine);
+    }
+    catch {
+        return out;
+    }
+    for (const n of names) {
+        const m = /^(.+)\.json$/.exec(n);
+        if (!m || m[1] === "watching" || !validSession(m[1]))
+            continue;
+        const h = readJson(path.join(mine, n));
+        if (h?.asks)
+            out.set(m[1], h.asks);
+    }
+    return out;
+}
+//# sourceMappingURL=remoteChat.js.map

package/dist/core/sync.js

@@ -15,6 +15,7 @@ import path from "node:path";
 import { UserError } from "./errors.js";
 import { DEVICE_NAME, configPath, deviceName, eventFiles, expandHome, homeDir, parseEventLines, readConfig, sharedDir, withLock, writeConfig, } from "./store.js";
 import { syncthingAdapter } from "./syncthing.js";
+import { relayAdapter } from "./relay.js";
 function devicesDir(shared) {
     return path.join(shared, "devices");
 }
@@ -209,6 +210,7 @@ function adapters() {
     registry ??= new Map([
         [folderAdapter.name, folderAdapter],
         [syncthingAdapter.name, syncthingAdapter],
+        [relayAdapter.name, relayAdapter],
     ]);
     return registry;
 }

package/dist/relay/server.js

@@ -0,0 +1,234 @@
+/**
+ * The relay: a small server that carries the shared folder between machines in place of a sync
+ * tool. It keeps sealed files and hands out what changed. It never sees what is in them: every
+ * machine seals a file and its path with a key the server is never given (see core/relay.ts).
+ *
+ * A space is the folder of one person (or one group). Each space has a token; anyone with it can
+ * read and write the space's sealed files. Making a space needs the server's invite, so a public
+ * server is not open to everyone.
+ *
+ *   POST   /v1/spaces                       invite → { space, token }
+ *   GET    /v1/spaces/:space/changes?after=N&wait=S   { head, changes: [{ name, seq, size?, deleted? }] }
+ *   PUT    /v1/spaces/:space/files/:name    the sealed bytes → { seq }
+ *   GET    /v1/spaces/:space/files/:name    the sealed bytes
+ *   DELETE /v1/spaces/:space/files/:name    → { seq }
+ *   GET    /healthz
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+export const RELAY_MAX_FILE = 256 * 1024 * 1024;
+const MAX_WAIT_S = 30;
+const SPACE = /^[a-f0-9]{24}$/;
+const NAME = /^[a-f0-9]{40}$/;
+const sha = (s) => crypto.createHash("sha256").update(s).digest();
+function sameSecret(given, hash) {
+    if (!given)
+        return false;
+    return crypto.timingSafeEqual(sha(given), hash);
+}
+class Store {
+    root;
+    spaces = new Map();
+    constructor(root) {
+        this.root = root;
+        fs.mkdirSync(root, { recursive: true });
+    }
+    create() {
+        const id = crypto.randomBytes(12).toString("hex");
+        const token = crypto.randomBytes(32).toString("base64url");
+        const dir = path.join(this.root, id);
+        fs.mkdirSync(path.join(dir, "files"), { recursive: true });
+        fs.writeFileSync(path.join(dir, "space.json"), JSON.stringify({ v: 1, token: sha(token).toString("hex"), at: new Date().toISOString() }) + "\n");
+        return { space: id, token };
+    }
+    open(id) {
+        if (!SPACE.test(id))
+            return undefined;
+        const had = this.spaces.get(id);
+        if (had)
+            return had;
+        const dir = path.join(this.root, id);
+        let meta;
+        try {
+            meta = JSON.parse(fs.readFileSync(path.join(dir, "space.json"), "utf8"));
+        }
+        catch {
+            return undefined;
+        }
+        const s = { id, dir, tokenHash: Buffer.from(meta.token, "hex"), head: 0, files: new Map(), journalLines: 0, waiters: new Set() };
+        let text = "";
+        try {
+            text = fs.readFileSync(path.join(dir, "journal.jsonl"), "utf8");
+        }
+        catch {
+            // a new space
+        }
+        for (const line of text.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const e = JSON.parse(line);
+                if (!NAME.test(e.name) || !Number.isInteger(e.seq))
+                    continue;
+                s.files.set(e.name, e.deleted ? { seq: e.seq, deleted: true } : { seq: e.seq, size: e.size });
+                s.head = Math.max(s.head, e.seq);
+                s.journalLines++;
+            }
+            catch {
+                // a line cut short by a crash; the file it named is written again by its machine
+            }
+        }
+        this.spaces.set(id, s);
+        if (s.journalLines > 4 * s.files.size + 100)
+            this.compact(s);
+        return s;
+    }
+    compact(s) {
+        const lines = [...s.files].sort((a, b) => a[1].seq - b[1].seq).map(([name, e]) => JSON.stringify({ name, ...e }) + "\n");
+        const tmp = path.join(s.dir, "journal.jsonl.tmp");
+        fs.writeFileSync(tmp, lines.join(""));
+        fs.renameSync(tmp, path.join(s.dir, "journal.jsonl"));
+        s.journalLines = lines.length;
+    }
+    record(s, name, e) {
+        const seq = ++s.head;
+        const entry = { seq, ...e };
+        s.files.set(name, entry);
+        fs.appendFileSync(path.join(s.dir, "journal.jsonl"), JSON.stringify({ name, ...entry }) + "\n");
+        s.journalLines++;
+        if (s.journalLines > 4 * s.files.size + 100)
+            this.compact(s);
+        for (const w of [...s.waiters])
+            w();
+        return seq;
+    }
+    filePath(s, name) {
+        return path.join(s.dir, "files", name);
+    }
+    changes(s, after) {
+        const changes = [...s.files].filter(([, e]) => e.seq > after).map(([name, e]) => ({ name, ...e }));
+        return { head: s.head, changes: changes.sort((a, b) => a.seq - b.seq) };
+    }
+}
+function send(res, status, body) {
+    const text = body === undefined ? "" : JSON.stringify(body);
+    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+    res.end(text);
+}
+function bearer(req) {
+    const h = req.headers.authorization;
+    return h?.startsWith("Bearer ") ? h.slice(7).trim() : undefined;
+}
+/** A relay server; call `.listen(port)` on it. */
+export function createRelayServer(opts) {
+    const store = new Store(opts.dataDir);
+    const log = opts.log ?? (() => { });
+    const inviteHash = opts.invite ? sha(opts.invite) : undefined;
+    return http.createServer((req, res) => {
+        const url = new URL(req.url ?? "/", "http://relay");
+        const parts = url.pathname.split("/").filter(Boolean);
+        const fail = (status, error) => send(res, status, { error });
+        try {
+            if (req.method === "GET" && url.pathname === "/healthz")
+                return send(res, 200, { ok: true });
+            if (parts[0] !== "v1" || parts[1] !== "spaces")
+                return fail(404, "not found");
+            if (parts.length === 2 && req.method === "POST") {
+                if (!inviteHash || !sameSecret(bearer(req), inviteHash))
+                    return fail(403, "this server needs its invite to make a space");
+                const made = store.create();
+                log(`space ${made.space} made`);
+                return send(res, 201, made);
+            }
+            const s = parts[2] ? store.open(parts[2]) : undefined;
+            // an unknown space and a wrong token look the same from outside
+            if (!s || !sameSecret(bearer(req), s.tokenHash))
+                return fail(401, "unknown space or wrong token");
+            if (parts.length === 4 && parts[3] === "changes" && req.method === "GET") {
+                const after = Math.max(0, Number(url.searchParams.get("after") ?? 0) || 0);
+                const wait = Math.min(MAX_WAIT_S, Math.max(0, Number(url.searchParams.get("wait") ?? 0) || 0));
+                const now = store.changes(s, after);
+                if (now.changes.length || !wait)
+                    return send(res, 200, now);
+                // nothing new: hold the request until something changes or the wait runs out
+                let done = false;
+                const finish = () => {
+                    if (done)
+                        return;
+                    done = true;
+                    clearTimeout(timer);
+                    s.waiters.delete(finish);
+                    if (!res.writableEnded)
+                        send(res, 200, store.changes(s, after));
+                };
+                const timer = setTimeout(finish, wait * 1000);
+                s.waiters.add(finish);
+                req.on("close", () => {
+                    done = true;
+                    clearTimeout(timer);
+                    s.waiters.delete(finish);
+                });
+                return;
+            }
+            if (parts.length === 5 && parts[3] === "files") {
+                const name = parts[4];
+                if (!NAME.test(name))
+                    return fail(400, "bad file name");
+                const file = store.filePath(s, name);
+                if (req.method === "GET") {
+                    const e = s.files.get(name);
+                    if (!e || e.deleted)
+                        return fail(404, "no such file");
+                    res.writeHead(200, { "content-type": "application/octet-stream", "cache-control": "no-store", "x-seq": String(e.seq) });
+                    fs.createReadStream(file).on("error", () => res.destroy()).pipe(res);
+                    return;
+                }
+                if (req.method === "DELETE") {
+                    fs.rmSync(file, { force: true });
+                    return send(res, 200, { seq: store.record(s, name, { deleted: true }) });
+                }
+                if (req.method === "PUT") {
+                    const declared = Number(req.headers["content-length"] ?? NaN);
+                    if (Number.isFinite(declared) && declared > RELAY_MAX_FILE)
+                        return fail(413, "file too large");
+                    const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+                    const out = fs.createWriteStream(tmp);
+                    let size = 0;
+                    let tooBig = false;
+                    req.on("data", (chunk) => {
+                        size += chunk.length;
+                        if (size > RELAY_MAX_FILE && !tooBig) {
+                            tooBig = true;
+                            out.destroy();
+                            fs.rmSync(tmp, { force: true });
+                            fail(413, "file too large");
+                            req.destroy();
+                        }
+                    });
+                    req.pipe(out);
+                    out.on("finish", () => {
+                        if (tooBig)
+                            return;
+                        fs.renameSync(tmp, file);
+                        send(res, 200, { seq: store.record(s, name, { size }) });
+                    });
+                    out.on("error", () => {
+                        fs.rmSync(tmp, { force: true });
+                        if (!res.headersSent)
+                            fail(500, "could not store the file");
+                    });
+                    return;
+                }
+            }
+            return fail(404, "not found");
+        }
+        catch (err) {
+            log(`error: ${err.message}`);
+            if (!res.headersSent)
+                fail(500, "server error");
+        }
+    });
+}
+//# sourceMappingURL=server.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parawatch",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "description": "A control tower for people running many AI coding agents in parallel: see what is running, what needs you, and wake the right agent when you answer.",
   "keywords": [
     "ai-agents",