parawatch 0.0.0-stage → 0.2.0

package/dist/core/skill.js

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { UserError } from "./ops.js";
+/** The agent skill shipped with this package (works from src/ and from dist/). */
+export function skillSource() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills", "parawatch");
+}
+export function skillTargets() {
+    const claude = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+    const codex = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+    return [
+        { runtime: "claude-code", dir: path.join(claude, "skills"), home: claude },
+        { runtime: "codex", dir: path.join(codex, "skills"), home: codex },
+    ];
+}
+/**
+ * Link the skill into each runtime's skills folder. Runtimes whose config folder is missing are
+ * skipped unless named. An existing folder that is not our link is left alone unless `force`.
+ */
+export function installSkill(targets, opts = {}) {
+    const src = skillSource();
+    if (!fs.existsSync(path.join(src, "SKILL.md")))
+        throw new UserError(`skill not found at ${src}`);
+    const out = [];
+    for (const t of targets) {
+        const named = opts.only?.includes(t.runtime);
+        if (opts.only && !named)
+            continue;
+        const dest = path.join(t.dir, "parawatch");
+        if (!named && !fs.existsSync(t.home)) {
+            out.push({ runtime: t.runtime, path: dest, result: "skipped", note: `${t.home} not found` });
+            continue;
+        }
+        fs.mkdirSync(t.dir, { recursive: true });
+        let stat;
+        try {
+            stat = fs.lstatSync(dest);
+        }
+        catch {
+            stat = undefined;
+        }
+        if (stat?.isSymbolicLink()) {
+            const current = path.resolve(t.dir, fs.readlinkSync(dest));
+            if (current === src) {
+                out.push({ runtime: t.runtime, path: dest, result: "already linked" });
+                continue;
+            }
+            fs.unlinkSync(dest);
+            fs.symlinkSync(src, dest);
+            out.push({ runtime: t.runtime, path: dest, result: "replaced link", note: `was ${current}` });
+            continue;
+        }
+        if (stat) {
+            if (!opts.force) {
+                out.push({ runtime: t.runtime, path: dest, result: "skipped", note: "a folder is already there; use --force to replace it" });
+                continue;
+            }
+            fs.rmSync(dest, { recursive: true, force: true });
+        }
+        fs.symlinkSync(src, dest);
+        out.push({ runtime: t.runtime, path: dest, result: "linked" });
+    }
+    return out;
+}
+//# sourceMappingURL=skill.js.map

package/dist/core/snapshot.js

@@ -0,0 +1,71 @@
+import { prViews, keyOf, parsePrRef, readCache, githubConfig } from "./github.js";
+import { linkPr, listeners } from "./ops.js";
+import { collectRuns } from "./runs.js";
+import { fold } from "./state.js";
+import { readEvents } from "./store.js";
+import { SCHEMA_VERSION } from "./types.js";
+/**
+ * `closed`: also carry the most recently closed cards, newest first, so a panel can show them
+ * again. Off by default; open and answered cards are always there.
+ *
+ * GitHub is read from the last reading only; `syncGithub` refreshes it.
+ */
+export function snapshot(opts = {}) {
+    let state = fold(readEvents());
+    const runs = collectRuns(state, { sinceHours: opts.sinceHours ?? 6, project: opts.project, keepRepeats: opts.keepRepeats });
+    if (linkCreatedPrs(runs, state))
+        state = fold(readEvents());
+    const all = [...state.cards.values()].filter((c) => !opts.project || c.project === opts.project);
+    const cards = [...all.filter((c) => c.status !== "closed"), ...recentlyClosed(all, opts.closed ?? 0)];
+    quietAnsweredAsks(runs, all);
+    const cache = readCache();
+    const enabled = githubConfig().enabled && (cache.hosts === undefined ? false : cache.hosts.length > 0);
+    let prs = enabled ? prViews(cache, state, runs) : undefined;
+    if (prs && opts.project)
+        prs = prs.filter((p) => p.project === opts.project);
+    return {
+        v: SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        projects: [...state.projects.values()],
+        cards,
+        runs,
+        prs,
+        github: { enabled, fetchedAt: cache.fetchedAt, error: cache.error },
+        listeners: listeners(),
+    };
+}
+/** A pull request a session's log shows it opened belongs to that session, unless linked already. */
+function linkCreatedPrs(runs, state) {
+    let added = false;
+    for (const r of runs) {
+        for (const url of r.createdPrs ?? []) {
+            const key = keyOf(url);
+            const pr = parsePrRef(url);
+            if (!key || !pr || state.prLinks.has(key))
+                continue;
+            linkPr({ pr, session: r.id, project: r.project, task: r.task });
+            state.prLinks.set(key, { pr, session: r.id, project: r.project, at: new Date().toISOString() });
+            added = true;
+        }
+    }
+    return added;
+}
+/** A question asked in chat is no longer pending once the session put it on a card. */
+function quietAnsweredAsks(runs, cards) {
+    for (const r of runs) {
+        if (!r.asks)
+            continue;
+        const turn = r.lastPromptAt ?? "";
+        if (cards.some((c) => c.status !== "closed" && c.session && r.id.startsWith(c.session) && c.openedAt >= turn))
+            r.asks = undefined;
+    }
+}
+export function recentlyClosed(cards, keep) {
+    if (keep <= 0)
+        return [];
+    return cards
+        .filter((c) => c.status === "closed")
+        .sort((a, b) => (b.closedAt ?? "").localeCompare(a.closedAt ?? ""))
+        .slice(0, keep);
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/core/state.js

@@ -0,0 +1,107 @@
+/** Rebuild current state from the event log. */
+export function fold(events) {
+    const s = { projects: new Map(), cards: new Map(), runs: new Map(), claims: [], prLinks: new Map(), lastSeq: 0 };
+    for (const ev of events) {
+        s.lastSeq = Math.max(s.lastSeq, ev.seq);
+        switch (ev.type) {
+            case "project.add":
+                s.projects.set(ev.project.name, ev.project);
+                break;
+            case "project.remove":
+                s.projects.delete(ev.name);
+                break;
+            case "card.open":
+                s.cards.set(ev.card.id, { ...ev.card, openedAt: ev.ts, status: "open", answers: [], comments: [] });
+                break;
+            case "card.answer": {
+                const c = s.cards.get(ev.card);
+                if (!c)
+                    break;
+                c.answers.push({ seq: ev.seq, at: ev.ts, by: ev.by, choice: ev.choice, comment: ev.comment, attach: ev.attach });
+                if (c.status === "open")
+                    c.status = "answered";
+                break;
+            }
+            case "card.comment": {
+                const c = s.cards.get(ev.card);
+                if (c)
+                    c.comments.push({ seq: ev.seq, at: ev.ts, by: ev.by, text: ev.text });
+                break;
+            }
+            case "card.edit": {
+                const c = s.cards.get(ev.card);
+                if (!c)
+                    break;
+                const target = c;
+                for (const [k, v] of Object.entries(ev.set)) {
+                    if (v === null || v === undefined)
+                        delete target[k];
+                    else
+                        target[k] = v;
+                }
+                break;
+            }
+            case "card.close": {
+                const c = s.cards.get(ev.card);
+                if (!c)
+                    break;
+                c.status = "closed";
+                c.closedAt = ev.ts;
+                c.closeNote = ev.note;
+                break;
+            }
+            case "run.start":
+                s.runs.set(ev.run.id, { ...ev.run, startedAt: ev.ts, lastActivity: ev.ts, status: "running" });
+                break;
+            case "run.note": {
+                const r = s.runs.get(ev.run);
+                if (!r)
+                    break;
+                r.note = ev.text;
+                r.lastActivity = ev.ts;
+                break;
+            }
+            case "run.beat": {
+                const r = s.runs.get(ev.run);
+                if (r)
+                    r.lastActivity = ev.ts;
+                break;
+            }
+            case "run.end": {
+                const r = s.runs.get(ev.run);
+                if (!r)
+                    break;
+                r.status = ev.status;
+                r.endedAt = ev.ts;
+                r.lastActivity = ev.ts;
+                if (ev.note)
+                    r.note = ev.note;
+                break;
+            }
+            case "run.claim":
+                // a later claim of the same session replaces the earlier one
+                s.claims = s.claims.filter((c) => c.session !== ev.claim.session);
+                s.claims.push({ ...ev.claim, at: ev.ts });
+                break;
+            case "pr.link":
+                s.prLinks.set(ev.link.pr.key, { ...ev.link, at: ev.ts });
+                break;
+            case "pr.unlink":
+                s.prLinks.delete(ev.pr);
+                break;
+        }
+    }
+    return s;
+}
+/** Next id with a prefix, counting the events that created that kind of thing. */
+export function nextId(events, prefix) {
+    let n = 0;
+    for (const ev of events) {
+        if (prefix === "c" && ev.type === "card.open")
+            n++;
+        if (prefix === "r" && ev.type === "run.start")
+            n++;
+    }
+    return `${prefix}${n + 1}`;
+}
+//# sourceMappingURL=state.js.map

package/dist/core/store.js

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { SCHEMA_VERSION } from "./types.js";
+/** Directory holding all parawatch state for this user. */
+export function homeDir() {
+    const explicit = process.env.PARAWATCH_HOME;
+    if (explicit)
+        return explicit;
+    const xdg = process.env.XDG_STATE_HOME || path.join(os.homedir(), ".local", "state");
+    return path.join(xdg, "parawatch");
+}
+export function eventsPath() {
+    return path.join(homeDir(), "events.jsonl");
+}
+function ensureHome() {
+    fs.mkdirSync(homeDir(), { recursive: true });
+}
+const LOCK_STALE_MS = 30_000;
+const LOCK_WAIT_MS = 10_000;
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** Run fn while holding an exclusive lock file. Several agents may write at once. */
+export function withLock(fn) {
+    ensureHome();
+    const lock = path.join(homeDir(), "lock");
+    const started = Date.now();
+    let fd;
+    while (fd === undefined) {
+        try {
+            fd = fs.openSync(lock, "wx");
+            fs.writeSync(fd, String(process.pid));
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            try {
+                const age = Date.now() - fs.statSync(lock).mtimeMs;
+                if (age > LOCK_STALE_MS) {
+                    fs.rmSync(lock, { force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue; // lock vanished between open and stat
+            }
+            if (Date.now() - started > LOCK_WAIT_MS) {
+                throw new Error(`parawatch: could not take the lock at ${lock}`);
+            }
+            sleepSync(15);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        fs.closeSync(fd);
+        fs.rmSync(lock, { force: true });
+    }
+}
+/** Parse every event line. Broken lines are skipped, not fatal. */
+export function readEvents() {
+    let text;
+    try {
+        text = fs.readFileSync(eventsPath(), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    return parseEventLines(text);
+}
+export function parseEventLines(text) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const ev = JSON.parse(line);
+            if (typeof ev.seq === "number" && typeof ev.type === "string")
+                out.push(ev);
+        }
+        catch {
+            // a torn or hand-edited line; keep going
+        }
+    }
+    return out;
+}
+/** Append one event. `build` sees the current events so it can pick ids under the lock. */
+export function appendEvent(build) {
+    return withLock(() => appendLocked((events) => [build(events)])[0]);
+}
+/** Append events while already holding the lock (inside `withLock`). */
+export function appendLocked(build) {
+    const events = readEvents();
+    let seq = events[events.length - 1]?.seq ?? 0;
+    const ts = new Date().toISOString();
+    const out = build(events).map((body) => ({ v: SCHEMA_VERSION, seq: ++seq, ts, ...body }));
+    if (out.length)
+        fs.appendFileSync(eventsPath(), out.map((e) => JSON.stringify(e) + "\n").join(""));
+    return out;
+}
+const CURSOR_NAME = /^[A-Za-z0-9._-]+$/;
+function cursorPath(name) {
+    if (!CURSOR_NAME.test(name))
+        throw new Error(`parawatch: bad consumer name "${name}"`);
+    return path.join(homeDir(), "cursors", `${name}.json`);
+}
+export function readCursor(name) {
+    try {
+        const data = JSON.parse(fs.readFileSync(cursorPath(name), "utf8"));
+        return typeof data.seq === "number" ? data.seq : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+export function writeCursor(name, seq) {
+    const file = cursorPath(name);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ seq, at: new Date().toISOString() }) + "\n");
+    fs.renameSync(tmp, file);
+}
+//# sourceMappingURL=store.js.map

package/dist/core/types.js

@@ -0,0 +1,6 @@
+export const SCHEMA_VERSION = 1;
+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. */
+export const HUMAN = "human";
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "parawatch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "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",
+    "claude-code",
+    "codex",
+    "cli",
+    "human-in-the-loop",
+    "parallel",
+    "inbox"
+  ],
+  "license": "MIT",
+  "author": "penspanic",
+  "homepage": "https://github.com/penspanic/parawatch#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/penspanic/parawatch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/penspanic/parawatch/issues"
+  },
+  "type": "module",
+  "bin": {
+    "parawatch": "dist/bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/bin/cli.ts",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit && npm run typecheck -w @parawatch/panel -w @parawatch/desktop",
+    "prepublishOnly": "npm run build && npm test",
+    "demo": "tsx scripts/demo.ts"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "workspaces": [
+    "packages/*",
+    "apps/*"
+  ]
+}

package/skills/parawatch/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: parawatch
+description: How an agent works with a human through parawatch. Use whenever you need something from the human (a decision, an approval of a prepared step, trying a build or looking at a capture, an action only they can do such as installing, signing in or sudo), as soon as you know what you are working on in a session where parawatch is set up (its AGENTS.md or CLAUDE.md has a parawatch block, or `parawatch project list` shows projects), when you open a pull request, when you finish your work, when you lead or coordinate other agents, and when you start a long job that leaves no agent log (CI wait, bake, benchmark). Covers claiming your work, linking pull requests, opening good cards, waiting for answers and PR news in the background, closing cards, finishing, and declaring runs. Not for talking to other agents, and not a task tracker.
+---
+
+# parawatch
+
+The human watches every project and agent from `parawatch status` and a side panel, and answers there. Anything you need from them goes through parawatch, not through chat or a document they have to remember to check. Their answer wakes you.
+
+## 1. Say what you work on, as soon as you know
+
+The human sees agents grouped by project and task. Parawatch can only guess from the folder a session started in, and many people start every session in the same home or notes folder. So say it yourself, the moment the work is clear (from the first message, or once you have read enough to know):
+
+```
+parawatch claim -p <project> -t <task> --title "<what you do, in a few words>"
+parawatch claim -p <project> --role lead --title "<what you are, e.g. Game Director>"   # if you lead the project
+```
+
+- **Claim the project the work is for, not the folder you run in.** A session started in a notes folder that changes the `api` repository claims `api`.
+- **`-t` is the unit of work**: a ticket key (`ABC-1234`), a pull request (`#88`), or a short name. It is how the human tells two sessions in one project apart.
+- **Claim again when the work changes** (the next ticket, another repository). The latest claim wins.
+- A project does not have to be registered to be claimed. `parawatch project list` shows the names already in use; reuse one when it fits.
+- A session a schedule starts again and again adds `--kind scheduled`, so its runs fold into one row.
+
+`claim` without a session id uses the calling session (`$CLAUDE_CODE_SESSION_ID`). Cards you open record your session too, so the human can jump from a card to you; claim first so the card shows your title. Your subagents and the `codex exec` jobs you start show under you on their own.
+
+To register a project so sessions started inside it are grouped without a claim: `parawatch project add <name> <repo path> [<notes folder>]`. Git worktrees of a registered path belong to the project automatically.
+
+Then check what is already waiting so you do not ask twice:
+
+```
+parawatch cards -p <project>
+parawatch inbox -p <project> --peek
+```
+
+## 2. Asking the human
+
+One question per card. Pick the kind by what the human has to do:
+
+| Need | Command |
+|--|--|
+| A choice | `parawatch ask -p <project> "<the question>" -o "<option>" -o "<option>" -r <n> -b "<why it matters now>"` |
+| Approval of a step you have prepared (merge, post, move a ticket, send a message, force-push) | `parawatch ask -p <project> "<what and why, as a question>" --action "<the exact command or step>" --preview <file with the text it sends>` |
+| An open answer | `parawatch ask -p <project> "<the question>" -b "<context>"` |
+| Try a build, watch a video, look at a screen | `parawatch try -p <project> "<what to try>" --open <app, file or URL> --attach <image or video> -l "<what to look at>"` |
+| Something only they can do, and you are stuck until they do | `parawatch block -p <project> "<what to do>" -b "<exact steps>"` |
+| Something only they can do, but nothing waits on it now | `parawatch todo -p <project> "<what to do>" -b "<exact steps, and by when>"` |
+
+A good card:
+
+- **The title is the question or the request**, readable alone in a list: "Ship the top-box ending?" not "Ending".
+- **The body is two or three lines**: what changed, what it affects, what happens if they do not answer. It renders as Markdown.
+- **Write in the human's words**: what they will see or feel in the product, not ticket numbers, metrics, engine terms or internal ids. Put those in an attachment or a link at the end of the body.
+- **Options are exclusive and concrete, and each says what happens if picked.** Recommend one with `-r` when you have a view; say why in the body.
+- **Attach evidence** with absolute paths: screenshots, short videos, logs. `--open` takes what they should launch (an `.app`, a file, a URL).
+- **Add `-t <task>`** when the project runs several tasks at once, so the human can tell them apart.
+- **`block` is red and counts as needing them now.** Use it only when your work stops until they act. Errands for later (a bill, a registration, a policy check, a measurement whenever the machine is free) are `todo`; they wait folded in the panel and do not pop up.
+- **Moving items from a board or a note:** pass `--since <YYYY-MM-DD>` with the date the item first came up, so the card does not look new. `parawatch edit <card>` fixes a card's kind, wording or date later.
+- **An approval shows exactly what runs.** With `--action` the human sees the command and the preview and answers Do it or Don't, without opening your session. Run exactly that on yes; say in the close note that you ran it.
+- **Never leave a question only in your reply.** If your turn ends needing the human, the question goes on a card. Parawatch flags questions it finds at the end of a turn as "asked in chat, no card", but that is a guess and easy to miss.
+- Do not open a card for something you can decide yourself, or that the project's own rules already settle.
+
+## 3. Pull requests
+
+When you open a pull request, link it to yourself:
+
+```
+parawatch pr link <url>          # or #88 inside the repository
+```
+
+A pull request you open with `gh pr create` is linked from your log on its own, but say it anyway; it costs nothing and survives a long session. When `gh` is installed and signed in, parawatch reads your pull requests from GitHub (GitHub Enterprise too). New reviews, requested changes, approvals, CI failures, conflicts, a drop from the merge queue and the merge itself arrive at your wait like an answer. The human sees the PR, what it waits on and for how long, next to your session.
+
+News from somewhere GitHub does not show (a merge bot, a ticket system) can be recorded by any tool: `parawatch pr event <url> <change> -m "<what happened>"`.
+
+## 4. Waiting for the answer
+
+Right after opening cards or linking a pull request, keep exactly one wait armed for your project:
+
+- **Claude Code**: run `parawatch wait -p <project>` as a background Bash command (`run_in_background: true`). When the human answers, the command exits, its output is the answer, and you are woken. Do not poll, do not sleep-loop, do not start a second wait while one is running.
+- **Other runtimes**: check `parawatch inbox -p <project>` at the start of every turn.
+
+Keep working on other things meanwhile. A wait with `--timeout <seconds>` exits with code 2 when nothing came; re-arm it if you still need the answer. While no wait runs, an answer is kept, and the card tells the human that no agent is waiting; it reaches you on your next turn or your next wait.
+
+## 5. Handling an answer
+
+The output looks like `[project] c4 "Ship the top-box ending?" chose 2 (Top box); said: fill it to the rim; attached: /path/shot.png`, or for a pull request `[project] PR acme/api#88 "Fix login": changes requested by alice (https://…)`.
+
+1. Act on it. Read attached files; they are the human's evidence.
+2. If the answer is a lasting decision, record it where the project keeps decisions (a design doc, an ADR), not only in the card.
+3. Close the card with what you did: `parawatch close c4 -n "Top box shipped in #212"`.
+4. If more cards are open, or a linked pull request is not merged yet, arm the wait again.
+
+To add information to a card without waking anyone, use `parawatch comment <card> "<text>"`. Never answer a card yourself: `answer` is the human's.
+
+## 6. Long jobs that leave no agent log
+
+A render, a benchmark, an editor build, a deploy you are waiting on:
+
+```
+id=$(parawatch run start -p <project> "overnight bench" --heartbeat 600 --log /path/bench.log)
+parawatch run note $id "scene 3 of 8"   # also counts as a beat
+parawatch run beat $id                  # still alive, nothing to say
+parawatch run end $id                   # or: parawatch run end $id --failed -n "editor stopped ticking"
+```
+
+The run shows under your session. With `--heartbeat`, it turns stalled when no beat, note or log change comes in that many seconds, so a job that hangs silently (a locked screen, App Nap) shows at once. End it when it ends, or it keeps showing as working. Do not poll a job with sleep loops; declare it and arm a wait.
+
+Do not declare runs for things parawatch already sees in their own logs: Claude Code sessions and subagents, and `codex exec` jobs, show up by themselves. A declared run on top of them is a duplicate.
+
+## 7. Finishing
+
+When your work is finished, say so with one line on how it ended:
+
+```
+parawatch claim --done "Merged #88; login works on staging"
+```
+
+The session then shows as done, not as idle, and the line goes into the human's daily digest (`parawatch digest`). It stays done until someone writes to the session again.
+
+## 8. Leads and workers
+
+- The lead owns the cards for its project. Workers (subagents, `codex exec` jobs, other sessions you start) report back to the lead instead of opening cards, unless the lead told them to ask the human directly.
+- 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`.
+
+## Quick reference
+
+```
+parawatch status                     # everything: what needs the human, what waits on others, what is running
+parawatch runs -p <project> --wide   # agents with ids
+parawatch pr list                    # open pull requests and what each waits on
+parawatch digest                     # what each session did today
+parawatch show <card>                # one card in full
+parawatch cards -p <project> -a      # include closed cards
+```