parawatch 0.2.0 → 0.3.1

package/dist/core/sync.js

@@ -0,0 +1,317 @@
+/**
+ * Sharing the log between machines. Parawatch only reads and writes files in a shared folder:
+ * each machine appends to `events/<device>.jsonl` and reads them all. Moving that folder between
+ * machines is the job of a sync tool, and a sync adapter only reports how that tool is doing.
+ *
+ * Layout of the shared folder:
+ *   events/<device>.jsonl   each machine's own log; only that machine writes it
+ *   devices/<device>.json   each machine's paths, version and last sign of life
+ *   listeners/              waits running on any machine
+ *   attachments/            pasted images, so every machine can open them
+ */
+import fs from "node:fs";
+import os from "node:os";
+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";
+function devicesDir(shared) {
+    return path.join(shared, "devices");
+}
+function hostPrint() {
+    return `${os.hostname()}:${os.homedir()}`;
+}
+export function readDevice(name, shared = sharedDir()) {
+    if (!shared)
+        return undefined;
+    try {
+        return JSON.parse(fs.readFileSync(path.join(devicesDir(shared), `${name}.json`), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readDevices(shared = sharedDir()) {
+    if (!shared)
+        return [];
+    let names = [];
+    try {
+        names = fs.readdirSync(devicesDir(shared)).filter((n) => /^[a-z0-9][a-z0-9-]*\.json$/.test(n));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const n of names) {
+        const d = readDevice(n.slice(0, -5), shared);
+        if (d)
+            out.push(d);
+    }
+    return out;
+}
+const DEVICE_REFRESH_MS = 10 * 60_000;
+/** Write this machine's device file when something changed or it is getting old. */
+export function touchDevice(version, opts = {}) {
+    const shared = sharedDir();
+    if (!shared)
+        return undefined;
+    const name = deviceName();
+    const before = readDevice(name, shared);
+    const me = {
+        name,
+        platform: process.platform,
+        host: hostPrint(),
+        home: os.homedir(),
+        shared,
+        roots: { ...(before?.host === hostPrint() ? before.roots : {}), ...(opts.roots ?? {}) },
+        version: version ?? before?.version,
+        at: new Date().toISOString(),
+    };
+    if (!Object.keys(me.roots).length)
+        delete me.roots;
+    const same = before &&
+        before.host === me.host &&
+        before.shared === me.shared &&
+        before.version === me.version &&
+        JSON.stringify(before.roots ?? {}) === JSON.stringify(me.roots ?? {}) &&
+        Date.now() - Date.parse(before.at) < DEVICE_REFRESH_MS;
+    if (same && !opts.force)
+        return before;
+    try {
+        const dir = devicesDir(shared);
+        fs.mkdirSync(dir, { recursive: true });
+        const file = path.join(dir, `${name}.json`);
+        const tmp = path.join(dir, `.${name}.${process.pid}.tmp`);
+        fs.writeFileSync(tmp, JSON.stringify(me, null, 2) + "\n");
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        // the shared folder may be read only for a moment; try again next time
+    }
+    return me;
+}
+// ------------------------------------------------------------------ paths
+function splitPath(p) {
+    return p.split(/[\\/]+/).filter(Boolean);
+}
+function startsWithPath(p, root, caseless) {
+    const a = splitPath(p);
+    const b = splitPath(root);
+    if (!b.length || a.length < b.length)
+        return undefined;
+    for (let i = 0; i < b.length; i++) {
+        const x = caseless ? a[i].toLowerCase() : a[i];
+        const y = caseless ? b[i].toLowerCase() : b[i];
+        if (x !== y)
+            return undefined;
+    }
+    return a.slice(b.length);
+}
+function joinOn(platform, root, rest) {
+    const p = platform === "win32" ? path.win32 : path.posix;
+    return rest.length ? p.join(root, ...rest) : root;
+}
+/**
+ * A path from another machine, as the same place on this one: under that machine's shared
+ * folder, a named root, or its home. The longest match wins; anything else is left as it is.
+ */
+export function mapPath(p, from, me) {
+    if (!from || !me || from.name === me.name || /^[a-z]+:\/\//i.test(p))
+        return p;
+    const caseless = from.platform === "win32";
+    const pairs = [[from.shared, me.shared]];
+    for (const [k, v] of Object.entries(from.roots ?? {})) {
+        const mine = me.roots?.[k];
+        if (mine)
+            pairs.push([v, mine]);
+    }
+    pairs.push([from.home, me.home]);
+    let best;
+    for (const [theirs, mine] of pairs) {
+        const rest = startsWithPath(p, theirs, caseless);
+        const len = splitPath(theirs).length;
+        if (rest && (!best || len > best.len))
+            best = { rest, root: mine, len };
+    }
+    return best ? joinOn(me.platform, best.root, best.rest) : p;
+}
+/** The path map for reading the shared log on this machine, or undefined when nothing is shared. */
+export function pathMap() {
+    const shared = sharedDir();
+    if (!shared)
+        return undefined;
+    const devices = new Map(readDevices(shared).map((d) => [d.name, d]));
+    const name = deviceName();
+    const me = devices.get(name) ?? { name, platform: process.platform, host: hostPrint(), home: os.homedir(), shared, at: "" };
+    if (devices.size <= 1)
+        return undefined;
+    return (p, from) => (from ? mapPath(p, devices.get(from), me) : p);
+}
+const CONFLICT = /\.sync-conflict-|conflicted copy|\(conflict\)|\.conflict\d*$/i;
+/** Conflict copies anywhere in the shared folder (sync tools name them in their own ways). */
+export function findConflicts(dir, depth = 3) {
+    const out = [];
+    const walk = (d, left) => {
+        let names = [];
+        try {
+            names = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            const p = path.join(d, n.name);
+            if (CONFLICT.test(n.name))
+                out.push(p);
+            else if (n.isDirectory() && left > 0 && !n.name.startsWith(".st"))
+                walk(p, left - 1);
+        }
+    };
+    walk(dir, depth);
+    return out.sort();
+}
+/** Other machines as the shared folder shows them: their device files and their logs. */
+export function folderPeers(dir, me) {
+    const peers = new Map();
+    for (const d of readDevices(dir))
+        if (d.name !== me)
+            peers.set(d.name, { name: d.name, lastSeen: d.at, version: d.version });
+    try {
+        for (const n of fs.readdirSync(path.join(dir, "events"))) {
+            const m = /^([a-z0-9][a-z0-9-]*)\.jsonl$/.exec(n);
+            if (!m || m[1] === me)
+                continue;
+            const at = fs.statSync(path.join(dir, "events", n)).mtime.toISOString();
+            const p = peers.get(m[1]) ?? { name: m[1] };
+            if (!p.lastSeen || at > p.lastSeen)
+                p.lastSeen = at;
+            peers.set(m[1], p);
+        }
+    }
+    catch {
+        // no logs yet
+    }
+    return [...peers.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Any folder something else keeps in step: a cloud drive, a network share, a git checkout. */
+export const folderAdapter = {
+    name: "folder",
+    about: "a folder kept in step by something else (a cloud drive, a network share)",
+    async status(ctx) {
+        const peers = folderPeers(ctx.dir, ctx.device);
+        const newest = peers.map((p) => p.lastSeen ?? "").sort().pop() || undefined;
+        return { adapter: "folder", dir: ctx.dir, device: ctx.device, ok: fs.existsSync(ctx.dir), lastSync: newest, peers, conflicts: findConflicts(ctx.dir) };
+    },
+};
+let registry;
+// built on first use: the Syncthing module imports helpers from this one
+function adapters() {
+    registry ??= new Map([
+        [folderAdapter.name, folderAdapter],
+        [syncthingAdapter.name, syncthingAdapter],
+    ]);
+    return registry;
+}
+/** Add an adapter (another sync tool). The name is what `sync.adapter` in config.json picks. */
+export function registerAdapter(a) {
+    adapters().set(a.name, a);
+}
+export function adapterNames() {
+    return [...adapters().keys()];
+}
+export function syncAdapter(name) {
+    return adapters().get(name ?? "folder") ?? folderAdapter;
+}
+/** How sharing is doing, or undefined when this machine keeps its log to itself. */
+export async function syncStatus(opts = {}) {
+    const dir = sharedDir();
+    if (!dir)
+        return undefined;
+    const cfg = readConfig().sync ?? {};
+    const a = syncAdapter(typeof cfg.adapter === "string" ? cfg.adapter : undefined);
+    const own = cfg[a.name];
+    const ctx = { dir, device: deviceName(), config: own && typeof own === "object" ? own : {}, fetch: opts.fetch, timeoutMs: opts.timeoutMs };
+    try {
+        return await a.status(ctx);
+    }
+    catch (err) {
+        return { adapter: a.name, dir, device: ctx.device, ok: false, peers: folderPeers(dir, ctx.device), conflicts: findConflicts(dir), error: err.message };
+    }
+}
+/** The line left in the old single-machine log, so an older parawatch refuses to write there. */
+export function movedMarker(to, seq) {
+    return JSON.stringify({ v: 2, seq, ts: new Date().toISOString(), type: "store.moved", to }) + "\n";
+}
+/**
+ * Start writing to a shared folder. This machine's log moves there as `events/<device>.jsonl`,
+ * keeping every event and seq as it was, so ids, cursors and answers stay valid. The old file is
+ * kept as a backup and replaced by a marker that makes older copies stop writing to it.
+ * Running it again with the same folder and name changes nothing.
+ */
+export function setupSync(input) {
+    const dir = path.resolve(expandHome(input.dir.trim()));
+    const cfg = readConfig();
+    const device = (input.device ?? (typeof cfg.device === "string" ? cfg.device : undefined) ?? deviceName()).trim();
+    if (!DEVICE_NAME.test(device))
+        throw new UserError(`device name "${device}" may only use a-z, 0-9 and -, up to 32 characters`);
+    const adapter = input.adapter ?? (typeof cfg.sync?.adapter === "string" ? cfg.sync.adapter : "folder");
+    if (!adapters().has(adapter))
+        throw new UserError(`unknown sync adapter "${adapter}" (known: ${adapterNames().join(", ")})`);
+    const current = sharedDir();
+    if (current && current !== dir)
+        throw new UserError(`this machine already shares ${current}. Moving to another folder is not supported yet.`);
+    return withLock(() => {
+        fs.mkdirSync(path.join(dir, "events"), { recursive: true });
+        const target = path.join(dir, "events", `${device}.jsonl`);
+        const theirs = readDevice(device, dir);
+        if (theirs && theirs.host !== hostPrint()) {
+            throw new UserError(`another machine (${theirs.host}) already writes as "${device}" in ${dir}. Pick another name with --device.`);
+        }
+        const legacy = path.join(homeDir(), "events.jsonl");
+        let moved = 0;
+        let backup;
+        const text = fs.existsSync(legacy) ? fs.readFileSync(legacy, "utf8") : "";
+        const events = parseEventLines(text).filter((e) => e.type !== "store.moved");
+        if (events.length) {
+            const already = fs.existsSync(target) ? parseEventLines(fs.readFileSync(target, "utf8")) : [];
+            if (already.length)
+                throw new UserError(`${target} already has ${already.length} events and this machine has its own log too. Pick another --device name.`);
+            const tmp = path.join(dir, "events", `.${device}.${process.pid}.tmp`);
+            fs.writeFileSync(tmp, events.map((e) => JSON.stringify(e) + "\n").join(""));
+            fs.renameSync(tmp, target);
+            backup = `${legacy}.before-sync`;
+            fs.copyFileSync(legacy, backup);
+            fs.writeFileSync(legacy, movedMarker(target, (events[events.length - 1]?.seq ?? 0) + 1));
+            moved = events.length;
+        }
+        const sync = { ...(cfg.sync ?? {}), dir: input.dir.trim().startsWith("~") ? input.dir.trim() : dir, adapter };
+        writeConfig({ ...cfg, device, sync });
+        touchDevice(input.version, { force: true });
+        const others = eventFiles()
+            .map((f) => f.device)
+            .filter((d) => d !== device);
+        return { dir, device, adapter, moved, backup, others };
+    });
+}
+/** Name a folder on this machine so paths under it map to the same name on other machines. */
+export function setRoot(name, folder, version) {
+    if (!sharedDir())
+        throw new UserError("this machine does not share its log yet: run `parawatch sync setup <folder>` first");
+    if (!/^[a-z0-9][a-z0-9_-]{0,31}$/i.test(name) || name === "home" || name === "shared")
+        throw new UserError(`root name "${name}" may use letters, digits, _ and -, and cannot be home or shared`);
+    const before = readDevice(deviceName());
+    const roots = { ...(before?.roots ?? {}) };
+    if (folder)
+        roots[name] = path.resolve(expandHome(folder));
+    else
+        delete roots[name];
+    const shared = sharedDir();
+    const me = { name: deviceName(), platform: process.platform, host: hostPrint(), home: os.homedir(), shared, roots, version: version ?? before?.version, at: new Date().toISOString() };
+    if (!Object.keys(roots).length)
+        delete me.roots;
+    fs.mkdirSync(devicesDir(shared), { recursive: true });
+    fs.writeFileSync(path.join(devicesDir(shared), `${me.name}.json`), JSON.stringify(me, null, 2) + "\n");
+    return me;
+}
+export { configPath };
+//# sourceMappingURL=sync.js.map

package/dist/core/syncthing.js

@@ -0,0 +1,121 @@
+/**
+ * The Syncthing adapter: asks the local Syncthing (its REST API) how the shared folder is doing.
+ * The API key is read from Syncthing's own config.xml and never printed or stored by parawatch.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { findConflicts, folderPeers } from "./sync.js";
+/** Where Syncthing keeps config.xml on this machine, newest layout first. */
+export function syncthingHomes() {
+    const home = os.homedir();
+    if (process.platform === "win32") {
+        const local = process.env.LOCALAPPDATA || path.join(home, "AppData", "Local");
+        return [path.join(local, "Syncthing")];
+    }
+    const state = process.env.XDG_STATE_HOME || path.join(home, ".local", "state");
+    const out = [path.join(state, "syncthing")];
+    if (process.platform === "darwin")
+        out.push(path.join(home, "Library", "Application Support", "Syncthing"));
+    out.push(path.join(process.env.XDG_CONFIG_HOME || path.join(home, ".config"), "syncthing"));
+    return out;
+}
+/** The GUI address and API key from config.xml (`home` overrides where to look). */
+export function readSyncthingGui(home) {
+    const dirs = home ? [home] : syncthingHomes();
+    for (const d of dirs) {
+        const file = path.join(d, "config.xml");
+        let xml;
+        try {
+            xml = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const gui = /<gui\b([^>]*)>([\s\S]*?)<\/gui>/.exec(xml);
+        const attrs = gui?.[1] ?? "";
+        const body = gui?.[2] ?? "";
+        const address = /<address>([^<]+)<\/address>/.exec(body)?.[1]?.trim() || "127.0.0.1:8384";
+        const tls = /\btls="true"/.test(attrs);
+        const apiKey = /<apikey>([^<]+)<\/apikey>/.exec(body)?.[1]?.trim();
+        const host = address.replace(/^0\.0\.0\.0(?=:)/, "127.0.0.1").replace(/^\[::\](?=:)/, "[::1]");
+        return { url: `${tls ? "https" : "http"}://${host}`, apiKey, configFile: file };
+    }
+    return { url: "http://127.0.0.1:8384" };
+}
+function inside(child, parent) {
+    const rel = path.relative(path.resolve(parent), path.resolve(child));
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+export const syncthingAdapter = {
+    name: "syncthing",
+    about: "Syncthing on this machine (its REST API on localhost)",
+    async status(ctx) {
+        const base = { adapter: "syncthing", dir: ctx.dir, device: ctx.device, ok: false, peers: folderPeers(ctx.dir, ctx.device), conflicts: findConflicts(ctx.dir) };
+        const gui = readSyncthingGui(typeof ctx.config.home === "string" ? ctx.config.home : undefined);
+        const url = typeof ctx.config.url === "string" ? ctx.config.url : gui.url;
+        const key = process.env.PARAWATCH_SYNCTHING_KEY || gui.apiKey;
+        if (!key)
+            return { ...base, error: "no Syncthing API key found (is Syncthing set up on this machine?)" };
+        const f = ctx.fetch ?? fetch;
+        const timeout = ctx.timeoutMs ?? 2000;
+        const get = async (p) => {
+            const res = await f(`${url}${p}`, { headers: { "X-API-Key": key }, signal: AbortSignal.timeout(timeout) });
+            if (!res.ok)
+                throw new Error(`Syncthing answered ${res.status} for ${p.split("?")[0]}`);
+            return (await res.json());
+        };
+        let folders;
+        try {
+            folders = await get("/rest/config/folders");
+        }
+        catch (err) {
+            const msg = err.message;
+            return { ...base, error: /fetch failed|ECONNREFUSED|abort|timeout/i.test(msg) ? `Syncthing is not running at ${url}` : msg };
+        }
+        const folder = folders
+            .map((x) => ({ ...x, path: x.path.replace(/^~(?=[\\/]|$)/, os.homedir()) }))
+            .filter((x) => inside(ctx.dir, x.path))
+            .sort((a, b) => b.path.length - a.path.length)[0];
+        if (!folder)
+            return { ...base, ok: true, error: `no Syncthing folder holds ${ctx.dir}` };
+        const [sys, devices, conns, stats, db, fstats] = await Promise.all([
+            get("/rest/system/status"),
+            get("/rest/config/devices"),
+            get("/rest/system/connections"),
+            get("/rest/stats/device"),
+            get(`/rest/db/status?folder=${encodeURIComponent(folder.id)}`),
+            get("/rest/stats/folder"),
+        ]);
+        const names = new Map(devices.map((d) => [d.deviceID, d.name || d.deviceID.slice(0, 7)]));
+        const known = new Map(base.peers.map((p) => [p.name, p]));
+        const peers = [];
+        for (const d of folder.devices ?? []) {
+            if (d.deviceID === sys.myID)
+                continue;
+            const c = conns.connections[d.deviceID];
+            const seen = stats[d.deviceID]?.lastSeen;
+            const name = names.get(d.deviceID) ?? d.deviceID.slice(0, 7);
+            const fromFolder = known.get(name);
+            peers.push({
+                name,
+                connected: !!c?.connected,
+                lastSeen: c?.connected ? new Date().toISOString() : seen && !seen.startsWith("1970") ? seen : fromFolder?.lastSeen,
+                address: c?.connected ? c.address : undefined,
+                version: fromFolder?.version,
+            });
+        }
+        const idle = db.state === "idle" && !db.needFiles;
+        const pending = db.needFiles ?? 0;
+        const errors = (db.errors ?? 0) + (db.pullErrors ?? 0);
+        return {
+            ...base,
+            ok: true,
+            peers,
+            pending: pending || undefined,
+            lastSync: idle ? db.stateChanged : fstats[folder.id]?.lastFile?.at,
+            error: errors ? `${errors} file(s) could not be synced (see Syncthing)` : !peers.length ? `folder "${folder.label || folder.id}" is not shared with another device yet` : undefined,
+        };
+    },
+};
+//# sourceMappingURL=syncthing.js.map

package/dist/core/types.js

@@ -1,4 +1,11 @@
+/** The version of the JSON that commands print (`--json`) and panels read. */
 export const SCHEMA_VERSION = 1;
+/**
+ * The newest event-log format this copy reads and writes. 1: one machine. 2: per-device logs in a
+ * shared folder (prefixed ids, answers that record what they saw). A copy refuses to write to a
+ * log with a newer format than it knows.
+ */
+export const STORE_FORMAT = 2;
 export const CARD_KINDS = ["decide", "try", "block", "todo"];
 export const PR_CHANGES = ["review", "approved", "changes_requested", "commented", "ci_failed", "ci_passed", "queued", "queue_removed", "conflict", "merged", "closed", "note"];
 /** Who counts as a human when deciding what wakes an agent. */

package/dist/core/update.js

@@ -0,0 +1,87 @@
+/**
+ * Whether a newer parawatch is out, for the command line. It asks the npm registry at most once a
+ * day and remembers the answer; it never blocks a command for long and never fails one. Turn it off
+ * with `"updates": { "check": false }` in config.json or PARAWATCH_UPDATE_CHECK=0 (also off in CI).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { homeDir } from "./store.js";
+import { compareVersions } from "./semver.js";
+export const REGISTRY_URL = "https://registry.npmjs.org/parawatch/latest";
+const DAY_MS = 24 * 3_600_000;
+const RETRY_MS = 3_600_000;
+const TIMEOUT_MS = 2_000;
+function cachePath() {
+    return path.join(homeDir(), "update.json");
+}
+export function updateChecksOn() {
+    if (process.env.PARAWATCH_UPDATE_CHECK === "0")
+        return false;
+    if (process.env.PARAWATCH_UPDATE_CHECK !== "1" && process.env.CI)
+        return false;
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(homeDir(), "config.json"), "utf8"));
+        return raw.updates?.check !== false;
+    }
+    catch {
+        return true;
+    }
+}
+export function readUpdateCache() {
+    try {
+        return JSON.parse(fs.readFileSync(cachePath(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeUpdateCache(c) {
+    try {
+        fs.mkdirSync(homeDir(), { recursive: true });
+        const tmp = `${cachePath()}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(c) + "\n");
+        fs.renameSync(tmp, cachePath());
+    }
+    catch {
+        // the next run asks again
+    }
+}
+function info(current, c) {
+    return { current, latest: c.latest, newer: !!c.latest && compareVersions(c.latest, current) > 0, checkedAt: c.checkedAt, error: c.error };
+}
+/**
+ * The newest published version, from the cache while it is fresh. `force` asks now. Returns
+ * undefined when update checks are off.
+ */
+export async function checkUpdate(current, opts = {}) {
+    if (!opts.force && !updateChecksOn())
+        return undefined;
+    const now = opts.now ?? Date.now();
+    const cache = readUpdateCache();
+    const age = cache.checkedAt ? now - Date.parse(cache.checkedAt) : Infinity;
+    if (!opts.force && age < (cache.error ? RETRY_MS : DAY_MS))
+        return info(current, cache);
+    const get = opts.fetch ?? globalThis.fetch;
+    let next;
+    try {
+        const res = await get(REGISTRY_URL, { signal: AbortSignal.timeout(TIMEOUT_MS), headers: { accept: "application/json" } });
+        if (!res.ok)
+            throw new Error(`the npm registry answered ${res.status}`);
+        const body = (await res.json());
+        if (typeof body.version !== "string")
+            throw new Error("the npm registry gave no version");
+        next = { checkedAt: new Date(now).toISOString(), latest: body.version };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? (err.name === "TimeoutError" ? "the npm registry did not answer in time" : err.message) : String(err);
+        next = { checkedAt: new Date(now).toISOString(), latest: cache.latest, error: msg };
+    }
+    writeUpdateCache(next);
+    return info(current, next);
+}
+export function updateLine(u) {
+    if (!u?.newer)
+        return undefined;
+    return `parawatch ${u.latest} is out (this is ${u.current}): npm i -g parawatch@latest`;
+}
+//# sourceMappingURL=update.js.map

package/dist/core/version.js

@@ -0,0 +1,20 @@
+/** The package's own version, read from package.json so it is written in one place. */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+let cached;
+/** The version of this package (works from src/ and from dist/). */
+export function packageVersion() {
+    if (cached)
+        return cached;
+    try {
+        const file = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+        cached = String(JSON.parse(fs.readFileSync(file, "utf8")).version ?? "0.0.0");
+    }
+    catch {
+        cached = "0.0.0";
+    }
+    return cached;
+}
+export { compareVersions } from "./semver.js";
+//# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parawatch",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",

package/skills/parawatch/SKILL.md

@@ -123,6 +123,10 @@ The session then shows as done, not as idle, and the line goes into the human's
 - Tell workers in their brief what to return to you, so the lead can turn it into one clear card.
 - Before ending a session, close cards you handled, end runs you started, and claim `--done`.
 
+## On more than one machine
+
+When `parawatch sync` shows other machines, the human may answer from any of them. Nothing changes in how you ask or wait. Ids then carry the machine (`pc-c3`); use the id the command printed. Attach files under your home folder or the shared folder (or a folder named with `parawatch sync root`), so the human's machine can open them. An app path given to `try --open` only opens on the machine that has it, so say in the body which machine to try it on.
+
 ## Quick reference
 
 ```