parawatch 0.2.0 → 0.3.1

package/README.md

@@ -65,7 +65,27 @@ parawatch skill install
 
 It links [`skills/parawatch`](skills/parawatch/SKILL.md) into `~/.claude/skills` and `~/.codex/skills`. The installed skill is a link to the copy in the package, so updating parawatch updates the skill.
 
-**The desktop app**, to see and answer cards without a terminal. On macOS, download the DMG from the [latest release](https://github.com/penspanic/parawatch/releases/latest): `arm64` for Apple silicon, `x64` for Intel. It is signed and notarized, so it opens without warnings. Elsewhere, [build it from source](apps/desktop/README.md#run-from-source).
+**The desktop app**, to see and answer cards without a terminal. On macOS, download the DMG from the [latest release](https://github.com/penspanic/parawatch/releases/latest): `arm64` for Apple silicon, `x64` for Intel. It is signed and notarized, so it opens without warnings. From 0.2.1 on it updates itself: it downloads a new version in the background and asks you to restart (Parawatch > Check for Updates, or Settings > Update automatically). Elsewhere, [build it from source](apps/desktop/README.md#run-from-source).
+
+**Checking the setup.** `parawatch doctor` shows the versions of the CLI and the app and whether they differ, the store, the skill links, the instruction files in this folder, the hook, and GitHub, with what to run for anything that needs work. Paste it into bug reports. `status` also says, at its end, when a newer CLI is out or when the app and the CLI are different versions.
+
+### Updating and removing
+
+```
+npm install -g parawatch@latest     # the CLI; the linked skill follows it
+```
+
+The CLI asks the npm registry for the latest version at most once a day, only when you run `status` or `doctor` at a terminal. `"updates": { "check": false }` in `config.json` or `PARAWATCH_UPDATE_CHECK=0` turns that off; it is off in CI. The app looks at GitHub Releases every few hours unless you turn Update automatically off.
+
+To remove parawatch:
+
+```
+parawatch skill uninstall           # the skill links
+parawatch init --remove -f AGENTS.md   # the block in each instruction file you added it to
+npm uninstall -g parawatch
+```
+
+Take the `parawatch hook` lines out of your Claude Code settings if you added them, drag Parawatch.app to the Trash, and delete `~/.local/state/parawatch` (your cards and history) and `~/Library/Logs/Parawatch` if you want those gone too.
 
 ### Platforms
 
@@ -247,10 +267,43 @@ parawatch watch --from 120       # starting after event 120
 
 ## Storage
 
-Everything lives in one append-only file, `~/.local/state/parawatch/events.jsonl` (`$PARAWATCH_HOME`, or `$XDG_STATE_HOME/parawatch`). Writers take a short lock, so several agents can write at once. Next to it: cursors in `cursors/`, running waits in `listeners/`, the last GitHub reading in `github.json`, and the optional `config.json`. Delete the folder to start over.
+Everything lives in one append-only file, `~/.local/state/parawatch/events.jsonl` (`$PARAWATCH_HOME`, or `$XDG_STATE_HOME/parawatch`). Writers take a short lock, so several agents can write at once. Next to it: cursors in `cursors/`, running waits in `listeners/`, the last GitHub reading in `github.json`, the last update check in `update.json`, the version each copy (CLI, app) last ran in `clients/`, and the optional `config.json`. Delete the folder to start over. A shared log lives in the shared folder instead; see [More than one machine](#more-than-one-machine).
+
+Every event carries a format number. A copy of parawatch reads a log that a newer copy wrote, skipping what it does not know, but refuses to write to it and says to update. The desktop app's own log is in `~/Library/Logs/Parawatch/main.log` (Help > Show Log File).
 
 Desktop notifications for new cards use `osascript` on macOS and `notify-send` on Linux. `PARAWATCH_NOTIFY=0` turns them off. While the desktop app runs it notifies instead, and the CLI stays quiet. To-dos never notify.
 
+## More than one machine
+
+Agents on a second machine (a desktop PC, a build box) can ask and be answered like the ones on your laptop. Parawatch does not move files between machines itself: point it at a folder that something else keeps in step, and each machine writes only its own log there.
+
+```sh
+# on each machine, once, with its own name
+parawatch sync setup ~/agent-sync/parawatch --device mac --adapter syncthing
+parawatch sync setup ~/agent-sync/parawatch --device pc  --adapter syncthing
+parawatch sync            # this machine, the others, how the sync tool is doing
+```
+
+- **Nothing moves until you run `sync setup`.** A machine on its own keeps today's single file and format.
+- **`sync setup` moves this machine's log into the folder.** It becomes `events/<device>.jsonl` with every event, id and seq as it was, so cursors and open cards carry on. The old file is kept beside it as `events.jsonl.before-sync`. A copy of parawatch older than 0.3 on that machine stops writing until it is updated.
+- **Each machine reads every log and writes only its own.** The logs merge in time order. Two machines never write one file, so a sync tool has nothing to merge.
+- **Ids carry the machine once a log is shared:** `pc-c3`, `mac-r2`. Commands take the short form (`parawatch close c3`) while only one machine has that number. Cards from before the move keep their ids.
+- **When two machines answer one card before either has seen the other's answer, the earlier answer stands.** The other one stays on the card, marked as not used, and does not wake the agent. An answer given after seeing the first one counts as usual.
+- **Paths follow the machine.** Attachments, things to open and project folders written on another machine are read as the same place here, under its home folder or the shared folder. Name other folders that sit in different places on each machine (a cloud drive, say): `parawatch sync root gdrive "G:\My Drive"` on one machine and `parawatch sync root gdrive ~/Library/CloudStorage/…/My\ Drive` on the other. Pasted pictures are saved in the shared folder, so every machine can open them.
+- **Waits are seen everywhere.** A card on your laptop says whether an agent on the PC is waiting for it.
+- **Every machine reads GitHub for itself.** The same news is delivered once.
+
+The shared folder holds `events/`, `devices/` (each machine's paths, version and last sign of life), `listeners/` and `attachments/`. Cursors, the lock, the GitHub reading and settings stay on each machine.
+
+**Sync adapters** are how parawatch asks the sync tool how it is doing, for `parawatch sync`, `doctor` and the app's settings. Pick one with `--adapter` (or `"sync": { "adapter": … }` in `config.json`):
+
+| Adapter | Reports |
+|---|---|
+| `syncthing` | Asks the local Syncthing through its REST API (address and API key from its `config.xml`; `PARAWATCH_SYNCTHING_KEY` or `"sync": { "syncthing": { "url", "home" } }` override): connected devices, when the folder was last in step, files on the way, errors. |
+| `folder` | Anything else that keeps a folder in step (a cloud drive, a network share): the other machines' last writes and conflict copies. |
+
+An adapter is one object with a `status()` method (`src/core/sync.ts`, `registerAdapter`). Another tool, such as a git checkout or a small server, fits the same shape.
+
 ## Not goals
 
 - Starting or steering agents. Use whatever you already use; parawatch only watches and carries answers back.

package/dist/bin/cli.js

@@ -2,16 +2,21 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import { Command } from "commander";
-import { UserError, addProject, answerCard, beatRun, claimSession, closeCard, commentCard, consumerName, editCard, endRun, linkPr, listeners, listenersFor, noteRun, openCard, prEvent, readInbox, removeProject, startListening, startRun, unlinkPr, waitInbox, } from "../core/ops.js";
+import { UserError, addProject, answerCard, beatRun, claimSession, closeCard, commentCard, consumerName, editCard, endRun, linkPr, listeners, listenersFor, noteRun, openCard, prEvent, findCard, readInbox, readState, removeProject, startListening, startRun, unlinkPr, waitInbox, } from "../core/ops.js";
 import { githubConfig, readCache, resolvePrRef, syncGithub, prViews } from "../core/github.js";
 import { digest, digestText, localDate } from "../core/digest.js";
-import { readEvents } from "../core/store.js";
+import { everywhere, readEvents } from "../core/store.js";
 import { followEvents } from "../core/follow.js";
-import { fold } from "../core/state.js";
+import { adapterNames, setRoot, setupSync, syncAdapter, syncStatus, touchDevice } from "../core/sync.js";
+import { syncText } from "../core/format.js";
 import { collectRuns } from "../core/runs.js";
 import { askRows, cardDetail, cardLine, cardRows, inboxLine, prRows, runsTree, view } from "../core/format.js";
-import { hookContext, notify, writeInstructions } from "../core/integrate.js";
-import { installSkill, skillSource, skillTargets } from "../core/skill.js";
+import { hookContext, notify, removeInstructions, writeInstructions } from "../core/integrate.js";
+import { installSkill, skillSource, skillTargets, uninstallSkill } from "../core/skill.js";
+import { recordClient, runningDesktop, versionSkew } from "../core/clients.js";
+import { doctor, doctorText } from "../core/doctor.js";
+import { checkUpdate, updateLine } from "../core/update.js";
+import { packageVersion } from "../core/version.js";
 import { cardContextLine, resolveGoto } from "../core/desktop.js";
 import { snapshot } from "../core/snapshot.js";
 import { SCHEMA_VERSION } from "../core/types.js";
@@ -27,15 +32,27 @@ const print = (x) => process.stdout.write(JSON.stringify(x) + "\n");
 function currentSession() {
     return process.env.CLAUDE_CODE_SESSION_ID || process.env.CODEX_THREAD_ID || undefined;
 }
+const VERSION = packageVersion();
+/** Where this command line is installed, for the note other copies read. */
+function binPath() {
+    try {
+        return fs.realpathSync(process.argv[1] ?? "");
+    }
+    catch {
+        return process.argv[1];
+    }
+}
+recordClient({ name: "cli", version: VERSION, path: binPath() });
+touchDevice(VERSION);
 const program = new Command();
 program
     .name("parawatch")
     .description("See what your agents are doing, what needs you, and wake the right agent when you answer.")
-    .version("0.2.0");
+    .version(VERSION);
 /** Read GitHub when the last reading is old; never fails the command. */
 async function refreshGithub(force = false) {
     try {
-        await syncGithub({ state: fold(readEvents()), force });
+        await syncGithub({ state: readState(), force });
     }
     catch (err) {
         if (force)
@@ -114,7 +131,7 @@ program
     .option("--copy", "also put a line about the card on the clipboard, to paste into that session")
     .option("--print", "print the link instead of opening it")
     .action((target, o) => {
-    const g = resolveGoto(target, fold(readEvents()));
+    const g = resolveGoto(target, readState());
     if (o.copy && g.card) {
         const line = cardContextLine(g.card);
         try {
@@ -156,7 +173,7 @@ program
     .description("show one card with its answers")
     .option("--json", "JSON output")
     .action((id, o) => {
-    const card = fold(readEvents()).cards.get(id);
+    const card = findCard(readState(), id);
     if (!card)
         throw new UserError(`no card "${id}"`);
     if (o.json) {
@@ -178,7 +195,7 @@ program
     .option("-a, --all", "include closed cards")
     .option("--json", "JSON output")
     .action((o) => {
-    const cards = [...fold(readEvents()).cards.values()].filter((c) => (o.all || c.status !== "closed") && (!o.project || c.project === o.project));
+    const cards = [...readState().cards.values()].filter((c) => (o.all || c.status !== "closed") && (!o.project || c.project === o.project));
     if (o.json)
         print({ v: SCHEMA_VERSION, cards });
     else
@@ -224,9 +241,9 @@ inboxOptions(program.command("inbox").description("print unhandled answers witho
 program
     .command("watch")
     .description("stream every new event as one JSON line (for plugins and monitors)")
-    .option("--from <seq>", "replay events after this sequence number first", int)
+    .option("--from <seq>", "replay events after this sequence number first (in every machine's log)", int)
     .action(async (o) => {
-    followEvents(print, o.from);
+    followEvents(print, o.from === undefined ? undefined : everywhere(o.from, readEvents()));
     await new Promise(() => { });
 });
 // ------------------------------------------------------------------ runs
@@ -241,7 +258,7 @@ program
     .option("-w, --wide", "show runtime and ids")
     .option("--json", "JSON output")
     .action((o) => {
-    const runs = collectRuns(fold(readEvents()), { sinceHours: o.since, project: o.project, includeEnded: o.all, runtimes: o.runtime, keepRepeats: o.every });
+    const runs = collectRuns(readState(), { sinceHours: o.since, project: o.project, includeEnded: o.all, runtimes: o.runtime, keepRepeats: o.every });
     if (o.json)
         print({ v: SCHEMA_VERSION, runs });
     else
@@ -307,7 +324,7 @@ pr.command("list")
     .action(async (o) => {
     if (!o.offline)
         await refreshGithub();
-    const state = fold(readEvents());
+    const state = readState();
     const runs = collectRuns(state, { sinceHours: 72 });
     let prs = prViews(readCache(), state, runs);
     if (o.project)
@@ -320,7 +337,7 @@ pr.command("list")
 pr.command("sync")
     .description("read GitHub now")
     .action(async () => {
-    const c = await syncGithub({ state: fold(readEvents()), force: true });
+    const c = await syncGithub({ state: readState(), force: true });
     if (c.error)
         process.stderr.write(`parawatch: ${c.error}\n`);
     process.stdout.write(`${c.prs.filter((p) => p.state === "open").length} open pull requests on ${(c.hosts ?? []).join(", ") || "no host"}\n`);
@@ -360,6 +377,8 @@ program
     .option("-w, --wide", "show runtime and ids")
     .option("--json", "JSON output")
     .action(async (o) => {
+    // the update check runs beside the GitHub reading, and only for a person at a terminal
+    const asking = !o.offline && !o.json && process.stdout.isTTY ? checkUpdate(VERSION).catch(() => undefined) : undefined;
     if (!o.offline)
         await refreshGithub();
     const snap = snapshot({ sinceHours: o.since, project: o.project });
@@ -375,16 +394,16 @@ program
     const open = cards.filter((c) => c.status === "open" && c.kind !== "todo");
     const todo = cards.filter((c) => c.status === "open" && c.kind === "todo");
     const answered = cards.filter((c) => c.status === "answered");
-    const asking = runs.filter((r) => r.asks);
+    const askers = runs.filter((r) => r.asks);
     const reviews = prs.filter((p) => p.reviewRequested && !p.mine);
     const waiting = prs.filter((p) => !(p.reviewRequested && !p.mine));
     const ls = snap.listeners ?? [];
     const out = [];
     out.push(head("NEEDS YOU", open.length || "nothing"));
     out.push(...cardRows(open, v, now, "  "));
-    if (asking.length) {
-        out.push("", head("ASKED IN CHAT, NO CARD", asking.length, "  (read from the log)"));
-        out.push(...askRows(asking, v, now, "  "));
+    if (askers.length) {
+        out.push("", head("ASKED IN CHAT, NO CARD", askers.length, "  (read from the log)"));
+        out.push(...askRows(askers, v, now, "  "));
     }
     if (reviews.length) {
         out.push("", head("REVIEWS ASKED OF YOU", reviews.length));
@@ -411,8 +430,18 @@ program
     out.push("", head("AGENTS", runs.length ? `${working} working` : "nothing running"));
     if (runs.length)
         out.push(runsTree(runs, v));
+    const dim = (t) => (v.color ? `\x1b[2m${t}\x1b[0m` : t);
+    const notes = [];
     if (snap.github?.error && snap.github.enabled)
-        out.push("", v.color ? `\x1b[2mGitHub: ${snap.github.error}\x1b[0m` : `GitHub: ${snap.github.error}`);
+        notes.push(`GitHub: ${snap.github.error}`);
+    const skew = versionSkew(VERSION, runningDesktop()?.version);
+    if (skew)
+        notes.push(skew.text);
+    const update = updateLine(await asking);
+    if (update)
+        notes.push(update);
+    if (notes.length)
+        out.push("", ...notes.map(dim));
     process.stdout.write(out.join("\n") + "\n");
 });
 // ------------------------------------------------------------------ skill
@@ -433,6 +462,15 @@ skill
         process.stdout.write(`${r.runtime.padEnd(12)} ${r.result.padEnd(15)} ${r.path}${r.note ? `  (${r.note})` : ""}\n`);
     }
 });
+skill
+    .command("uninstall")
+    .description("remove the skill links that install made")
+    .option("--runtime <name>", "only this runtime: claude-code or codex (repeatable)", collect)
+    .action((o) => {
+    for (const r of uninstallSkill(skillTargets(), { only: o.runtime })) {
+        process.stdout.write(`${r.runtime.padEnd(12)} ${r.result.padEnd(14)} ${r.path}${r.note ? `  (${r.note})` : ""}\n`);
+    }
+});
 // ------------------------------------------------------------------ setup
 const project = program.command("project").description("projects you work on");
 project
@@ -444,7 +482,7 @@ project
     .command("list")
     .option("--json", "JSON output")
     .action((o) => {
-    const ps = [...fold(readEvents()).projects.values()];
+    const ps = [...readState().projects.values()];
     if (o.json)
         print({ v: SCHEMA_VERSION, projects: ps });
     else
@@ -455,10 +493,63 @@ program
     .description("add parawatch instructions for agents to an instruction file")
     .option("-f, --file <path>", "file to write", "AGENTS.md")
     .option("-p, --project <name>", "project name to put in the examples")
+    .option("--remove", "take the parawatch block out of the file instead")
     .action((o) => {
+    if (o.remove) {
+        process.stdout.write(removeInstructions(o.file) ? `Removed the parawatch block from ${o.file}\n` : `${o.file} has no parawatch block\n`);
+        return;
+    }
     const changed = writeInstructions(o.file, o.project);
     process.stdout.write(changed ? `Updated ${o.file}\n` : `${o.file} already up to date\n`);
 });
+program
+    .command("doctor")
+    .description("how parawatch is set up here: versions, store, desktop app, skill, GitHub; paste it into bug reports")
+    .option("--offline", "do not ask the npm registry for the latest version")
+    .option("--json", "JSON output")
+    .action(async (o) => {
+    const update = o.offline ? undefined : await checkUpdate(VERSION, { force: true }).catch(() => undefined);
+    const checks = await doctor({ version: VERSION, bin: binPath(), update });
+    if (o.json)
+        print({ v: SCHEMA_VERSION, version: VERSION, platform: `${process.platform}-${process.arch}`, checks });
+    else
+        process.stdout.write(`${doctorText(checks, view({}).color)}\n`);
+});
+// ------------------------------------------------------------------ sharing between machines
+const sync = program.command("sync").description("share cards and answers with your other machines through a synced folder");
+sync
+    .command("status", { isDefault: true })
+    .description("how sharing is doing: this machine, the others, the sync tool")
+    .option("--json", "JSON output")
+    .action(async (o) => {
+    const st = await syncStatus();
+    if (o.json)
+        print({ v: SCHEMA_VERSION, sync: st ?? null });
+    else
+        process.stdout.write(syncText(st, view({}).color) + "\n");
+});
+sync
+    .command("setup <folder>")
+    .description("start writing to a shared folder; this machine's log moves there, nothing is lost")
+    .option("-d, --device <name>", "this machine's name in the folder (a-z, 0-9, -); defaults to the host name")
+    .option("-a, --adapter <name>", `the tool that carries the folder: ${adapterNames().join(", ")}`)
+    .action((folder, o) => {
+    const r = setupSync({ dir: folder, device: o.device, adapter: o.adapter, version: VERSION });
+    const lines = [
+        `This machine writes to ${r.dir} as "${r.device}" (adapter: ${r.adapter}, ${syncAdapter(r.adapter).about}).`,
+        r.moved ? `Moved ${r.moved} events from this machine's log; the old file is kept at ${r.backup}.` : "",
+        r.others.length ? `Other machines already here: ${r.others.join(", ")}.` : "No other machine has written here yet. Run the same command on the next one with its own --device.",
+        "Older parawatch copies (before 0.3) on this machine stop writing until they are updated.",
+    ];
+    process.stdout.write(lines.filter(Boolean).join("\n") + "\n");
+});
+sync
+    .command("root <name> [folder]")
+    .description("name a folder on this machine (a cloud drive, say) so paths under it open on the others; no folder removes it")
+    .action((name, folder) => {
+    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"));
+});
 program
     .command("hook <runtime>")
     .description("hook entry point; 'claude-code' reads the hook JSON on stdin")

package/dist/core/clients.js

@@ -0,0 +1,69 @@
+/**
+ * Which copies of parawatch use this store. The command line and the desktop app each carry their
+ * own copy of the code and are updated apart, so each leaves a note of its version here; the other
+ * reads it and says when they differ.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { homeDir } from "./store.js";
+import { compareVersions } from "./semver.js";
+/** A note older than this is rewritten even when nothing changed, so `at` stays roughly current. */
+const REFRESH_MS = 6 * 3_600_000;
+function clientPath(name) {
+    return path.join(homeDir(), "clients", `${name}.json`);
+}
+export function readClient(name) {
+    try {
+        const c = JSON.parse(fs.readFileSync(clientPath(name), "utf8"));
+        return typeof c.version === "string" ? c : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Leave this copy's note. Cheap when nothing changed; never throws. */
+export function recordClient(info, now = Date.now()) {
+    try {
+        const old = readClient(info.name);
+        const same = old && old.version === info.version && old.path === info.path && old.pid === info.pid && old.log === info.log;
+        if (same && now - Date.parse(old.at) < REFRESH_MS)
+            return;
+        const file = clientPath(info.name);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify({ ...info, at: new Date(now).toISOString() }, null, 2) + "\n");
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        // a note for other copies; nothing depends on it
+    }
+}
+export function processAlive(pid) {
+    if (!pid || !Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** The desktop app's note while it runs. */
+export function runningDesktop() {
+    const d = readClient("desktop");
+    return d && processAlive(d.pid) ? d : undefined;
+}
+export const CLI_UPDATE = "npm i -g parawatch@latest";
+/** When the command line and the app are different versions, which one to update. */
+export function versionSkew(cli, desktop) {
+    if (!cli || !desktop)
+        return undefined;
+    const c = compareVersions(cli, desktop);
+    if (c === 0)
+        return undefined;
+    const older = c < 0 ? "cli" : "desktop";
+    const fix = older === "cli" ? CLI_UPDATE : "update the app (Check for Updates in its menu)";
+    return { cli, desktop, older, text: `The desktop app is ${desktop} and the command line is ${cli}: ${fix}.` };
+}
+//# sourceMappingURL=clients.js.map

package/dist/core/doctor.js

@@ -0,0 +1,165 @@
+/**
+ * `parawatch doctor`: one look at how parawatch is set up on this machine, for setting it up on a
+ * new one and for bug reports. It only reads; every line that needs work says what to run.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { CLI_UPDATE, readClient, runningDesktop, versionSkew } from "./clients.js";
+import { ghHosts, githubConfig, readCache, runGh } from "./github.js";
+import { instructionState } from "./integrate.js";
+import { listeners } from "./ops.js";
+import { fold } from "./state.js";
+import { deviceName, eventFiles, homeDir, readEvents, sharedDir, storeFormat } from "./store.js";
+import { readDevice, syncStatus } from "./sync.js";
+import { skillState, skillTargets } from "./skill.js";
+import { STORE_FORMAT } from "./types.js";
+import { updateChecksOn } from "./update.js";
+function claudeSettingsFiles() {
+    const dir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+    return [path.join(dir, "settings.json"), path.join(dir, "settings.local.json")];
+}
+function bytes(n) {
+    return n < 1024 ? `${n} B` : n < 1024 * 1024 ? `${(n / 1024).toFixed(0)} KB` : `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+export async function doctor(input) {
+    const out = [];
+    const add = (area, state, text, fix) => out.push({ area, state, text, ...(fix ? { fix } : {}) });
+    // the command line
+    add("cli", "ok", `parawatch ${input.version} on node ${process.versions.node}${input.bin ? ` at ${input.bin}` : ""}`);
+    const u = input.update;
+    if (!u)
+        add("updates", "off", updateChecksOn() ? "not checked" : "update checks are off");
+    else if (u.newer)
+        add("updates", "warn", `${u.latest} is out`, CLI_UPDATE);
+    else if (u.error)
+        add("updates", "info", `could not check: ${u.error}`);
+    else
+        add("updates", "ok", `up to date${u.latest ? ` (latest ${u.latest})` : ""}`);
+    // the store
+    const events = readEvents();
+    let size = 0;
+    for (const f of eventFiles()) {
+        try {
+            size += fs.statSync(f.file).size;
+        }
+        catch {
+            // no events yet
+        }
+    }
+    const format = storeFormat(events);
+    const shared = sharedDir();
+    const where = shared ? `${shared} (shared) · this machine ${homeDir()}` : homeDir();
+    if (format > STORE_FORMAT)
+        add("store", "warn", `${where} has format ${format}, newer than this copy reads (${STORE_FORMAT})`, CLI_UPDATE);
+    else
+        add("store", "ok", `${where} · ${events.length} events, ${bytes(size)}`);
+    // other machines
+    const st = input.sync === undefined ? await syncStatus().catch(() => undefined) : input.sync ?? undefined;
+    if (!shared)
+        add("sync", "off", "this machine only", "to share with another machine: parawatch sync setup <folder> --device <name>");
+    else {
+        const me = deviceName();
+        const mine = readDevice(me);
+        if (mine && mine.host !== `${os.hostname()}:${os.homedir()}`)
+            add("sync", "warn", `another machine (${mine.host}) also writes as "${me}"`, "give each machine its own name: parawatch sync setup <folder> --device <name>");
+        if (!st)
+            add("sync", "info", `${me} · ${shared}`);
+        else {
+            const peers = st.peers.map((p) => `${p.name} ${p.connected === true ? "connected" : p.connected === false ? "not connected" : "seen"}`).join(", ");
+            add("sync", st.error || !st.ok ? "warn" : "ok", `${me} · ${st.adapter} · ${peers || "no other machine yet"}${st.error ? ` · ${st.error}` : ""}`);
+            if (st.conflicts.length)
+                add("sync", "warn", `${st.conflicts.length} conflict copy(ies): ${st.conflicts.slice(0, 3).join(", ")}`, "each machine writes only its own file; look for two machines using one device name");
+        }
+    }
+    const state = fold(events);
+    add("projects", state.projects.size ? "ok" : "info", state.projects.size ? [...state.projects.keys()].join(", ") : "none registered (claims still work)");
+    // the desktop app
+    const desktop = runningDesktop();
+    const seen = desktop ?? readClient("desktop");
+    if (desktop)
+        add("desktop", "ok", `Parawatch ${desktop.version} is running${desktop.log ? ` · log ${desktop.log}` : ""}`);
+    else if (seen)
+        add("desktop", "info", `not running (last seen ${seen.version}, ${seen.at.slice(0, 10)})${seen.log ? ` · log ${seen.log}` : ""}`);
+    else
+        add("desktop", "info", "not used on this machine (the command line works alone)");
+    const skew = versionSkew(input.version, desktop?.version);
+    if (skew)
+        add("versions", "warn", skew.text, skew.older === "cli" ? CLI_UPDATE : "Parawatch > Check for Updates");
+    // what agents are told
+    for (const t of input.targets ?? skillTargets()) {
+        const s = skillState(t);
+        const where = path.join(t.dir, "parawatch");
+        if (s.state === "linked")
+            add(`skill:${t.runtime}`, "ok", where);
+        else if (s.state === "linked elsewhere")
+            add(`skill:${t.runtime}`, "warn", `${where} links to ${s.target}, not to this copy`, "parawatch skill install");
+        else if (s.state === "folder")
+            add(`skill:${t.runtime}`, "info", `${where} is a copy; it will not follow updates`, "parawatch skill install --force");
+        else if (s.state === "missing")
+            add(`skill:${t.runtime}`, "warn", "not installed", "parawatch skill install");
+        else
+            add(`skill:${t.runtime}`, "off", `${t.runtime} not found (${t.home})`);
+    }
+    const cwd = input.cwd ?? process.cwd();
+    const files = ["AGENTS.md", "CLAUDE.md"].map((f) => path.join(cwd, f));
+    const found = files.map((f) => ({ f, s: instructionState(f) })).filter((x) => x.s !== "absent");
+    if (!found.length)
+        add("instructions", "info", `no parawatch block in AGENTS.md or CLAUDE.md in ${cwd}`, "parawatch init");
+    for (const x of found) {
+        if (x.s === "current")
+            add("instructions", "ok", x.f);
+        else
+            add("instructions", "warn", `${x.f} has an older parawatch block`, `parawatch init -f ${path.basename(x.f)}`);
+    }
+    const hooked = (input.claudeSettings ?? claudeSettingsFiles()).filter((f) => {
+        try {
+            return fs.readFileSync(f, "utf8").includes("parawatch hook");
+        }
+        catch {
+            return false;
+        }
+    });
+    add("hook", hooked.length ? "ok" : "info", hooked.length ? `Claude Code hook in ${hooked.join(", ")}` : "no Claude Code hook (optional; see the README)");
+    // GitHub
+    const g = githubConfig();
+    if (!g.enabled)
+        add("github", "off", "turned off in config.json or PARAWATCH_GITHUB=0");
+    else {
+        const gh = input.gh ?? runGh;
+        let ghVersion;
+        try {
+            ghVersion = (await gh(["--version"])).split("\n")[0]?.trim();
+        }
+        catch {
+            ghVersion = undefined;
+        }
+        if (!ghVersion)
+            add("github", "off", "gh not found, so pull requests are not followed (nothing else needs it)", "install gh and run gh auth login");
+        else {
+            const hosts = await ghHosts(gh);
+            if (!hosts.length)
+                add("github", "warn", `${ghVersion}, but not signed in`, "gh auth login");
+            else {
+                const c = readCache();
+                const when = c.fetchedAt ? `last read ${c.fetchedAt.replace("T", " ").slice(0, 16)}` : "not read yet";
+                add("github", c.error ? "warn" : "ok", `${hosts.join(", ")} · ${c.prs.length} PRs · ${when}${c.error ? ` · ${c.error}` : ""}`, c.error ? "parawatch pr sync" : undefined);
+            }
+        }
+    }
+    const ls = listeners();
+    add("waits", "info", ls.length ? `${ls.length} agent wait(s) armed` : "no agent is waiting right now");
+    return out;
+}
+const MARK = { ok: "✓", warn: "!", off: "-", info: "·" };
+export function doctorText(checks, color = false) {
+    const width = Math.max(...checks.map((c) => c.area.length));
+    return checks
+        .map((c) => {
+        const mark = color && c.state === "warn" ? `\x1b[33m${MARK[c.state]}\x1b[0m` : color && c.state === "ok" ? `\x1b[32m${MARK[c.state]}\x1b[0m` : MARK[c.state];
+        const fix = c.fix ? (color ? `\n${" ".repeat(width + 4)}\x1b[2m→ ${c.fix}\x1b[0m` : `\n${" ".repeat(width + 4)}→ ${c.fix}`) : "";
+        return `${mark} ${c.area.padEnd(width)}  ${c.text}${fix}`;
+    })
+        .join("\n");
+}
+//# sourceMappingURL=doctor.js.map

package/dist/core/errors.js

@@ -0,0 +1,4 @@
+/** A mistake the user can fix: the CLI prints the message alone, without a stack. */
+export class UserError extends Error {
+}
+//# sourceMappingURL=errors.js.map