parawatch 0.0.0-stage → 0.1.0

package/dist/core/runs.js

@@ -0,0 +1,160 @@
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { scanAll } from "../adapters/index.js";
+import { ACTIVITY_MINUTES, activeMinutes } from "../adapters/jsonl.js";
+/** All checkouts of a project path: the path itself plus its git worktrees. */
+function rootsOf(p, cache) {
+    const hit = cache.get(p);
+    if (hit)
+        return hit;
+    const roots = [p];
+    try {
+        const git = (args) => execFileSync("git", ["-C", p, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 });
+        // a folder inside a bigger repo (a notes vault, a monorepo package) must not claim the whole repo
+        const top = git(["rev-parse", "--show-toplevel"]).trim();
+        if (path.resolve(top) !== path.resolve(p)) {
+            cache.set(p, roots);
+            return roots;
+        }
+        const out = git(["worktree", "list", "--porcelain"]);
+        for (const line of out.split("\n")) {
+            if (line.startsWith("worktree ")) {
+                const w = line.slice("worktree ".length).trim();
+                if (w && !roots.includes(w))
+                    roots.push(w);
+            }
+        }
+    }
+    catch {
+        // not a git checkout, or git missing; the path alone still matches
+    }
+    cache.set(p, roots);
+    return roots;
+}
+function inside(child, parent) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+function matchers(projects) {
+    const cache = new Map();
+    return projects.map((p) => ({ project: p.name, roots: p.paths.flatMap((x) => rootsOf(x, cache)) }));
+}
+/** The project whose checkout holds this directory; the deepest root wins. */
+function projectForCwd(cwd, ms) {
+    if (!cwd)
+        return undefined;
+    let best;
+    for (const m of ms) {
+        for (const r of m.roots) {
+            if (inside(cwd, r) && (!best || r.length > best.depth))
+                best = { project: m.project, depth: r.length };
+        }
+    }
+    return best?.project;
+}
+/** A project whose path the run's first prompt names, when exactly one does. */
+function projectForPrompt(prompt, ms) {
+    if (!prompt)
+        return undefined;
+    const hits = new Set();
+    for (const m of ms) {
+        for (const r of m.roots)
+            if (prompt.includes(r))
+                hits.add(m.project);
+    }
+    return hits.size === 1 ? [...hits][0] : undefined;
+}
+/**
+ * Give each observed run a project, in this order: an explicit claim, the checkout
+ * it runs in, its parent's project, a project path named in its first prompt.
+ */
+export function attribute(runs, state) {
+    const ms = matchers([...state.projects.values()]);
+    const byId = new Map(runs.map((r) => [r.id, r]));
+    for (const r of runs) {
+        const claim = state.claims.find((c) => r.id.startsWith(c.session));
+        if (claim) {
+            r.project = claim.project;
+            r.task = claim.task ?? r.task;
+            r.role = claim.role ?? r.role;
+            if (claim.title)
+                r.title = claim.title;
+            continue;
+        }
+        r.project = projectForCwd(r.cwd, ms);
+    }
+    // parents may themselves get a project only from a claim, so resolve children afterwards
+    for (let pass = 0; pass < 3; pass++) {
+        for (const r of runs) {
+            if (r.project || !r.parent)
+                continue;
+            const p = byId.get(r.parent);
+            if (p?.project)
+                r.project = p.project;
+            else
+                r.project = state.claims.find((c) => r.parent.startsWith(c.session))?.project;
+        }
+    }
+    for (const r of runs) {
+        if (!r.project)
+            r.project = projectForPrompt(r.prompt, ms);
+    }
+    return runs;
+}
+/** A declared run is busy from its start until it ends (or now, while it runs). */
+function declaredActivity(start, end, now) {
+    const from = Date.parse(start);
+    const to = end ? Date.parse(end) : now;
+    const times = [];
+    for (let t = Math.max(from, now - ACTIVITY_MINUTES * 60_000); t <= to; t += 60_000)
+        times.push(t);
+    if (to >= from)
+        times.push(to);
+    return activeMinutes(times, now);
+}
+export function declaredRuns(state, now = Date.now()) {
+    return [...state.runs.values()].map((d) => ({
+        id: d.id,
+        runtime: "declared",
+        kind: "declared",
+        title: d.title,
+        project: d.project,
+        task: d.task,
+        parent: d.parent,
+        startedAt: d.startedAt,
+        lastActivity: d.lastActivity,
+        state: d.status === "running" ? "working" : d.status,
+        action: d.note,
+        activity: declaredActivity(d.startedAt, d.status === "running" ? undefined : (d.endedAt ?? d.lastActivity), now),
+    }));
+}
+const ENDED = new Set(["done", "idle", "failed"]);
+const RECENT_END_MS = 30 * 60_000;
+const OLD_STALL_MS = 3 * 3_600_000;
+export function collectRuns(state, q, now = Date.now()) {
+    const sinceMs = now - q.sinceHours * 3_600_000;
+    // a log file can be touched (title records, snapshots) long after its last real activity
+    const recent = (r) => !r.lastActivity || Date.parse(r.lastActivity) >= sinceMs;
+    let runs = attribute(scanAll({ sinceMs, now }, q.runtimes), state).filter(recent);
+    runs.push(...declaredRuns(state, now).filter(recent));
+    if (q.project)
+        runs = runs.filter((r) => r.project === q.project);
+    if (!q.includeEnded) {
+        // keep what is moving, plus things that finished in the last half hour and parents of live children
+        const live = new Set(runs.filter((r) => !ENDED.has(r.state)).map((r) => r.parent).filter(Boolean));
+        runs = runs.filter((r) => {
+            // a run quiet for hours is almost always gone, not stuck; --all still shows it
+            if (r.state === "stalled")
+                return r.lastActivity ? now - Date.parse(r.lastActivity) < OLD_STALL_MS : true;
+            if (!ENDED.has(r.state))
+                return true;
+            if (live.has(r.id))
+                return true;
+            if (r.role === "lead")
+                return true;
+            return r.lastActivity ? now - Date.parse(r.lastActivity) < RECENT_END_MS : false;
+        });
+    }
+    return runs.sort((a, b) => (b.lastActivity ?? "").localeCompare(a.lastActivity ?? ""));
+}
+//# sourceMappingURL=runs.js.map

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,24 @@
+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.
+ */
+export function snapshot(opts = {}) {
+    const 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)];
+    const runs = collectRuns(state, { sinceHours: opts.sinceHours ?? 6, project: opts.project });
+    return { v: SCHEMA_VERSION, generatedAt: new Date().toISOString(), projects: [...state.projects.values()], cards, runs };
+}
+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,95 @@
+/** Rebuild current state from the event log. */
+export function fold(events) {
+    const s = { projects: new Map(), cards: new Map(), runs: new Map(), claims: [], 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.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);
+                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,128 @@
+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(() => {
+        const events = readEvents();
+        const last = events[events.length - 1];
+        const ev = {
+            v: SCHEMA_VERSION,
+            seq: (last?.seq ?? 0) + 1,
+            ts: new Date().toISOString(),
+            ...build(events),
+        };
+        fs.appendFileSync(eventsPath(), JSON.stringify(ev) + "\n");
+        return ev;
+    });
+}
+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,5 @@
+export const SCHEMA_VERSION = 1;
+export const CARD_KINDS = ["decide", "try", "block", "todo"];
+/** 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.1.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,105 @@
+---
+name: parawatch
+description: How an agent works with a human through parawatch. Use whenever you need something from the human (a decision, an approval, trying a build or looking at a capture, an action only they can do such as installing, signing in or sudo), when you lead or coordinate other agents on a project, when you start a long job that leaves no agent log (CI wait, bake, benchmark), and at the start of a session in a project that uses parawatch (its AGENTS.md or CLAUDE.md has a parawatch block, or `parawatch project list` shows it). Covers claiming your session, opening good cards, waiting for answers in the background, closing cards 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. At the start of a session
+
+```
+parawatch project list
+```
+
+If the project you work on is listed, put yourself on the board:
+
+```
+parawatch claim -p <project> --role lead --title "<what you are, e.g. Game Director>"   # if you lead the project
+parawatch claim -p <project> --title "<your task>"                                        # otherwise
+```
+
+`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.
+
+If the project is not listed and the human wants it tracked: `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>"` |
+| 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.
+- Do not open a card for something you can decide yourself, or that the project's own rules already settle.
+
+## 3. Waiting for the answer
+
+Right after opening cards, 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.
+
+## 4. 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`.
+
+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, 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.
+
+## 5. Long jobs that leave no agent log
+
+A CI run, a render, a benchmark, a deploy you are waiting on:
+
+```
+id=$(parawatch run start -p <project> "PR 212 CI")
+parawatch run note $id "UI tests running"
+parawatch run end $id                 # or: parawatch run end $id --failed -n "UI test timed out"
+```
+
+The run shows under your session. End it when it ends, or it keeps showing as working.
+
+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.
+
+## 6. 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 and end runs you started.
+
+## Quick reference
+
+```
+parawatch status                     # everything: what needs the human, what is running
+parawatch runs -p <project> --wide   # agents with ids
+parawatch show <card>                # one card in full
+parawatch cards -p <project> -a      # include closed cards
+```