parawatch 0.1.0 → 0.2.0

package/README.md

@@ -11,26 +11,38 @@ It answers three questions:
 
 - **What needs me?** Decisions to make, builds or videos to try, things only you can do.
 - **What is running?** Every agent session, its subagents and its `codex exec` jobs, grouped by project, with what each one is doing right now.
-- **Did my answer reach the agent?** When you answer a card, the agent waiting on it wakes up. You do not go back to the chat to say "I decided".
+- **What waits on someone else?** Pull requests waiting on a review, CI or a merge queue, each next to the session that owns it, with how long it has waited.
+- **Did my answer reach the agent?** When you answer a card, or a review lands on its pull request, the agent waiting on it wakes up. You do not go back to the chat to say "I decided" or "a review came in".
 
-parawatch is a CLI first. Agents use the CLI, and so can you. There is no server and nothing leaves your machine. On top of the CLI, this repository has a [desktop app](apps/desktop/README.md) (the panel above, a menu bar count, a Dock badge and notifications).
+parawatch is a CLI first. Agents use the CLI, and so can you. There is no server. Agent logs and cards never leave your machine; the only thing read from outside is your pull requests, through the GitHub CLI you have already signed in, and only when you have it. On top of the CLI, this repository has a [desktop app](apps/desktop/README.md) (the panel above, a menu bar count, a Dock badge and notifications).
 
 ```
 $ parawatch status
-NEEDS YOU  3
-  c1   decide   game/139  Which ending for the shake box?                12m
-  c2   try      game/139  Try build 139: does the glass read as glass?    4m
-  c3   blocked  app       Install the iPad simulator runtime              1h
+NEEDS YOU  4
+  c1   decide   game/139   Which ending for the shake box?                12m
+  c2   try      game/139   Try build 139: does the glass read as glass?    4m
+  c3   blocked  app        Install the iPad simulator runtime              1h
+  c7   decide   app/PR 21  Merge PR 21 and post the 1.4 release note?      9m
 
-AGENTS  5 working
+ASKED IN CHAT, NO CARD  1  (read from the log)
+  Pricing page    6m  Publish it now, or wait for the new photos?  (site)
+
+WAITING ON OTHERS  3 · 1 stuck
+  marble-box#139  stuck in merge queue    9h  Game Director           Shake round 2 and the top-box ending
+  ear-trainer#22  review (mina)           5h                          Settings screen
+  ear-trainer#21  merge                  20m  Interval lesson screen  Interval lessons and the count-in
+
+AGENTS  4 working
 app
-  ● Interval lesson screen        1m  Bash: Build the app
-  ○ App Director                 24m  PR 18 passed. Waiting for the simulator runtime.
+  ✓ Interval lesson screen (1 PR)    1m  done · PR 21 is green and reviewed; waiting on the merge
+  ○ App Director                    24m  PR 18 passed. Waiting for the simulator runtime.
 game
-  ● Game Director                 1s  Bash: Wait for answers
-  ├ ● 139 shake round 2           1s  Bash: Run tests
-  ├ ● Generate the level icons    2m  exec: python3 make_icons.py
-  └ ● Glass shader pass           9m  Bash: Capture the tank
+  ● Game Director (1 PR)             0s  Bash: Wait for answers
+  ├ ● 139 shake round 2              0s  Bash: Run tests
+  ├ ● Generate the level icons       2m  exec: python3 make_icons.py
+  └ ! Overnight physics benchmark   24m  stalled · no sign of life for 24m · scene 5 of 8
+site
+  ○ Pricing page                     6m  asks: Publish it now, or wait for the new photos?
 ```
 
 One line per item, always inside the terminal width. Finished subagents fold into a count after five minutes (`parawatch runs --all` shows them). `--wide` adds the runtime and ids. Colors follow `NO_COLOR` and `FORCE_COLOR`.
@@ -69,9 +81,11 @@ Node 20 or newer.
 
 | | |
 |--|--|
-| **Project** | A name and one or more paths. Git worktrees of a path belong to the project too. |
+| **Project** | A name, and optionally one or more paths. Git worktrees of a path belong to the project too. |
+| **Claim** | An agent session saying what it works on: a project, a task (a ticket key, a pull request, a short name), a title. It is the main way runs are grouped; guesses from the log are the fallback. A claim can also say the work is done. |
 | **Card** | Something that needs the human. Four kinds: `decide` (pick an option or write an answer), `try` (open a build, watch a video, look at a screen), `block` (only the human can do it and the agent is stuck until they do: install, sudo, sign in), `todo` (only the human can do it, but nothing waits on it now: check a bill, register a company). A card remembers the session that opened it, and `--since` keeps when the matter first came up when it is older than the card. |
-| **Run** | An agent at work. Most runs are *observed*: parawatch reads the agent's own log. Jobs that leave no log (a bake, a benchmark) can be *declared* with `parawatch run start`. |
+| **Run** | An agent at work. Most runs are *observed*: parawatch reads the agent's own log. Jobs that leave no log (a bake, a benchmark) can be *declared* with `parawatch run start`, with a heartbeat if they can hang silently. |
+| **Pull request** | Read through `gh`. Linked to the session that owns it, so its news wakes that session. |
 | **Lead** | A role, not a concept of its own. Claim a session with `--role lead` and it shows at the top of its project with its children under it. |
 
 ## For the human
@@ -86,17 +100,21 @@ parawatch answer c5 -m "glass is too dark" --attach ~/Desktop/shot.png
 parawatch runs --since 12        # agents seen in the last 12 hours
 parawatch runs -p game --all    # include finished ones
 parawatch runs --wide            # with runtime and ids
+parawatch runs --every           # each run of a scheduled task, not one row per task
+parawatch pr list                # open pull requests: what each waits on, since when, whose it is
+parawatch goto api#88            # open the session that owns a pull request
+parawatch digest                 # what each session did today (--date, --json)
 ```
 
-Register projects once:
+Agents say what they work on themselves (`parawatch claim`, below), so nothing has to be registered. Registering a project's paths groups the sessions that start inside it even when they do not claim:
 
 ```
 parawatch project add game ~/dev/game
 parawatch project add app ~/dev/app ~/notes/app
-parawatch claim 811a9612 -p game --role lead --title "Game Director"
+parawatch claim 811a9612 -p game --role lead --title "Game Director"   # claim a session for it
 ```
 
-`claim` is for sessions that do not start inside a project path (an agent run from a notes folder, a scratch directory). Children of a claimed session follow it.
+Children of a claimed session follow it.
 
 ## For agents
 
@@ -109,18 +127,27 @@ parawatch init -f AGENTS.md -p game     # or CLAUDE.md
 It writes a short block between `<!-- parawatch:begin -->` and `<!-- parawatch:end -->` and replaces it in place on later runs. The protocol in short:
 
 ```
+parawatch claim -p api -t ABC-1234 --title "Fix the login redirect"   # as soon as the work is clear
+parawatch pr link https://github.com/acme/api/pull/88                 # when it opens a pull request
 parawatch ask -p game "Which ending?" -o "Side tank" -o "Top box" -r 2 -b "two or three lines"
+parawatch ask -p api "Merge PR 88?" --action "gh pr merge 88 --squash" --preview note.md   # an approval
 parawatch try -p game "Try build 139" --open /path/Game.app --look "does the glass read?"
 parawatch block -p app "Install the iPad simulator runtime"
 parawatch todo -p game "Check the GitHub bill" --since 2026-10-01
 parawatch wait -p game           # run in the background; exits when the human answers
 parawatch comment c4 "baking the top box now"   # a note on the card; does not wake anyone
 parawatch close c4 -n "used the top box"
+parawatch run start -p game "overnight bench" --heartbeat 600 --log bench.log   # a job with no agent log
+parawatch claim --done "Merged #88; login works on staging"                    # when the work is finished
 ```
 
+An agent claims the project the work is for, not the folder it runs in, and claims again when it moves to other work. A claim of `--kind scheduled` folds the runs of a schedule into one row. `--done` marks the session finished until someone writes to it again, and its line goes into the digest.
+
+An approval (`ask --action`) shows the exact command and the text it sends, with Do it and Don't, so the human can say yes without opening the session.
+
 `parawatch edit <card>` changes a card after the fact: its kind, wording, task, who asked or `--since`. `parawatch goto <card>` opens the session that asked in the Claude desktop app (`--copy` also puts a line about the card on the clipboard, to paste there); sessions outside the desktop app get the `claude --resume` command instead.
 
-`wait` prints the answers and exits with code 0. With `--timeout <seconds>` it exits with code 2 when nothing came. An answer given before `wait` starts is not lost: each consumer has its own cursor, and `wait` returns everything after it.
+`wait` prints the answers, and news on the project's linked pull requests, and exits with code 0. With `--timeout <seconds>` it exits with code 2 when nothing came. An answer given before `wait` starts is not lost: each consumer has its own cursor, and `wait` returns everything after it. While a `wait` runs, cards say an agent is waiting; when none does, an answered card says the answer is kept until the agent next checks.
 
 ### Agent skill
 
@@ -149,6 +176,32 @@ The hook only peeks. The agent's own `wait` or `inbox` moves its cursor.
 
 Anything that can run a command and notice when it exits can use `wait`. `parawatch inbox` returns at once (add `--peek` to leave the cursor where it is), for runtimes that poll.
 
+## Pull requests
+
+When the [GitHub CLI](https://cli.github.com) is installed and signed in, parawatch reads your open pull requests and the ones asking for your review, on every host `gh` knows (GitHub Enterprise included). It never holds a token of its own. Without `gh`, all of this stays off.
+
+- **Whose it is.** A session links a pull request with `parawatch pr link <url>`. One it opened with `gh pr create` is linked from its log on its own.
+- **What it waits on.** Review (and from whom), CI, a failed check, requested changes, a conflict, the merge queue, auto-merge, or the merge itself, and since when. Past a limit per state it shows as stuck.
+- **News wakes the owner.** New reviews, approvals, requested changes, comments, CI results, conflicts, leaving the merge queue without merging, and the merge arrive at the owning project's `wait` like an answer. The desktop app notifies what keeps a pull request from landing, and the landing.
+- **Other sources.** A merge bot or a ticket system can record news the same way: `parawatch pr event <url> queue_removed -m "batch 412 failed"`.
+
+GitHub is read when its last reading is older than the interval: by `status`, by a running `wait`, and by the desktop app. `parawatch pr sync` reads it now. Pull requests nobody touched for 60 days are left out unless a session owns them.
+
+`config.json` in the store folder changes the defaults (every key is optional):
+
+```json
+{
+  "github": {
+    "enabled": true,
+    "intervalMinutes": 5,
+    "maxAgeDays": 60,
+    "stallHours": { "review": 24, "CI": 2, "merge queue": 6, "conflict": 4 }
+  }
+}
+```
+
+`PARAWATCH_GITHUB=0` turns it off for one command.
+
 ## Observed agents
 
 parawatch reads agent logs. It never writes to them and never sends them anywhere.
@@ -158,9 +211,11 @@ parawatch reads agent logs. It never writes to them and never sends them anywher
 | Claude Code | `~/.claude/projects/*/<session>.jsonl` and `<session>/subagents/` (or `$CLAUDE_CONFIG_DIR`) | sessions with their title, subagents with their description and model, the tool in flight |
 | Codex | `~/.codex/sessions/` (or `$CODEX_HOME`) | `codex exec` jobs and interactive sessions with their prompt and last tool call; jobs started from a Claude Code session show under it |
 
-States: `●` working, `◐` waiting, `○` idle, `✓` done, `!` stalled (quiet longer than its tool's timeout allows), `✗` failed.
+States: `●` working, `◐` waiting, `○` idle, `✓` done (a finished subagent, or a session that claimed `--done`), `!` stalled (quiet longer than its tool's timeout allows, or a declared job past its heartbeat), `✗` failed.
+
+A run belongs to a project by, in order: a claim; its working directory, unless it only edits files of another project; its parent's project; the project whose files it edits most; a project path named in its first prompt. Runs that match nothing show under `other`. `--wide` marks the guesses (`~edits`, `~prompt`).
 
-Runs that match no registered project show under `other`. A run belongs to a project by, in order: a claim, its working directory, its parent's project, a project path named in its first prompt.
+When a session's turn ends with a question for the human and no card, parawatch lists it under ASKED IN CHAT. It reads the Claude desktop app's end-of-turn summary when there is one, else a question at the end of the last message. It is a guess, so agents are told to put questions on cards.
 
 ### Adding a runtime
 
@@ -185,21 +240,21 @@ It reads only, reads only files touched since `sinceMs`, and reads only the head
 Anything else can build on the same two commands:
 
 ```
-parawatch status --json          # one snapshot: projects, cards, runs
+parawatch status --json          # one snapshot: projects, cards, runs, pull requests, running waits
 parawatch watch                  # every new event as one JSON line
 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. Cursors live next to it in `cursors/`. 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`, and the optional `config.json`. Delete the folder to start over.
 
 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.
 
 ## Not goals
 
 - Starting or steering agents. Use whatever you already use; parawatch only watches and carries answers back.
-- A shared team tracker. It is for one person and their agents, on one machine.
+- A shared team tracker. It is for one person and their agents, on one machine. It shows other people only as the reviewers your pull requests wait on.
 - Replacing your issue tracker. Cards are short-lived questions, not the backlog.
 
 ## License

package/dist/adapters/claudeCode.js

@@ -40,10 +40,77 @@ function promptText(rec) {
         return undefined;
     return text;
 }
+const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+const DIR_IN_COMMAND = /(?:^|[;&|]\s*|\s)(?:cd|git\s+-C)\s+("[^"]+"|'[^']+'|[^\s;&|]+)/g;
+const PR_URL = /https?:\/\/[^\s"'<>()]+\/pull\/\d+/g;
+/** The desktop app's end-of-turn tool: a recap, maybe a question for the human. */
+const WRAP_UP = /(^|__)wrap_up$/;
+function resultText(b) {
+    const c = b.content;
+    if (typeof c === "string")
+        return c;
+    if (Array.isArray(c))
+        return c.map((x) => (isObj(x) && typeof x.text === "string" ? x.text : "")).join("\n");
+    return "";
+}
+function unquote(s) {
+    return s.replace(/^["']|["']$/g, "");
+}
+/**
+ * What a log shows about where the work happens and what it produced: folders of edited files and
+ * of `cd`/`git -C` targets (absolute paths only), and pull requests opened with `gh pr create`.
+ */
+export function scanWork(recs) {
+    const touched = [];
+    const add = (dir) => {
+        if (!path.isAbsolute(dir))
+            return;
+        const i = touched.indexOf(dir);
+        if (i >= 0)
+            touched.splice(i, 1);
+        touched.push(dir);
+    };
+    const prCalls = new Set();
+    const prs = [];
+    for (const r of recs) {
+        if (!isObj(r) || !isConversation(r))
+            continue;
+        for (const b of blocks(r)) {
+            if (b.type === "tool_use") {
+                const inp = b.input ?? {};
+                if (EDIT_TOOLS.has(String(b.name))) {
+                    const f = str(inp.file_path) || str(inp.notebook_path);
+                    if (f)
+                        add(path.dirname(f));
+                }
+                else if (b.name === "Bash") {
+                    const cmd = str(inp.command) ?? "";
+                    for (const m of cmd.matchAll(DIR_IN_COMMAND))
+                        add(unquote(m[1]));
+                    if (/\bgh\s+pr\s+create\b/.test(cmd) && b.id)
+                        prCalls.add(b.id);
+                }
+            }
+            else if (b.type === "tool_result" && b.tool_use_id && prCalls.has(b.tool_use_id)) {
+                for (const m of resultText(b).matchAll(PR_URL))
+                    if (!prs.includes(m[0]))
+                        prs.push(m[0]);
+            }
+        }
+    }
+    return { touched: touched.slice(-50), createdPrs: prs };
+}
+/** The last line of an agent's closing message, when it is a question. */
+function trailingQuestion(text) {
+    const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+    const last = lines[lines.length - 1];
+    return last && /[?？]\**$/.test(last) ? last : undefined;
+}
 /** Work out what a Claude Code transcript is doing from its last records. */
 export function readClaudeTail(recs, kind) {
     const out = { state: "unknown" };
     let lastConv;
+    let wrapUp;
     for (const r of recs) {
         if (!isObj(r))
             continue;
@@ -58,6 +125,15 @@ export function readClaudeTail(recs, kind) {
             out.title = str(r.agentName);
         if (isConversation(r))
             lastConv = r;
+        if (promptText(r)) {
+            out.lastPromptAt = ts ?? out.lastPromptAt;
+            wrapUp = undefined; // a new turn began
+        }
+        if (r.type === "assistant") {
+            const w = blocks(r).find((b) => b.type === "tool_use" && WRAP_UP.test(String(b.name)));
+            if (w)
+                wrapUp = { ...(w.input ?? {}), at: ts };
+        }
     }
     if (!lastConv)
         return out;
@@ -73,8 +149,22 @@ export function readClaudeTail(recs, kind) {
         }
         else if (bs.some((b) => b.type === "text" && b.text?.trim())) {
             out.state = kind === "subagent" ? "done" : "idle";
-            const text = bs.filter((b) => b.type === "text").map((b) => b.text ?? "").join(" ");
-            out.action = oneLine(text, 100);
+            const full = bs.filter((b) => b.type === "text").map((b) => b.text ?? "").join("\n");
+            out.action = oneLine(full, 100);
+            if (kind === "session") {
+                const recap = wrapUp && str(wrapUp.recap);
+                if (recap)
+                    out.recap = oneLine(recap, 300);
+                const ask = wrapUp && str(wrapUp.ask);
+                const blocked = wrapUp?.blocked === true;
+                if (ask || blocked)
+                    out.asks = { text: oneLine(ask || recap || full, 200), via: "wrap_up", blocked: blocked || undefined, at: str(wrapUp.at) };
+                else if (!wrapUp) {
+                    const q = trailingQuestion(full);
+                    if (q)
+                        out.asks = { text: oneLine(q.replace(/\*\*/g, ""), 200), via: "text", at: out.lastActivity };
+                }
+            }
         }
         else {
             out.state = "working";
@@ -104,6 +194,10 @@ function firstPrompt(file) {
     }
     return out;
 }
+/** A log small enough that its tail already holds the whole file. */
+function sameFile(file) {
+    return fs.statSync(file).size <= TAIL_BYTES;
+}
 function readMeta(file) {
     try {
         const data = JSON.parse(fs.readFileSync(file.replace(/\.jsonl$/, ".meta.json"), "utf8"));
@@ -177,9 +271,16 @@ function readSession(file, now) {
     const base = { id, runtime: "claude-code", kind: "session", title: id.slice(0, 8), state: "unknown", source: file };
     try {
         const head = firstPrompt(file);
-        const tail = readClaudeTail(readTailLines(file, TAIL_BYTES), "session");
+        const tailRecs = readTailLines(file, TAIL_BYTES);
+        const tail = readClaudeTail(tailRecs, "session");
+        const work = scanWork(sameFile(file) ? tailRecs : [...readHeadLines(file, HEAD_BYTES), ...tailRecs]);
         const run = {
             ...base,
+            lastPromptAt: tail.lastPromptAt,
+            asks: tail.asks,
+            recap: tail.recap,
+            touched: work.touched.length ? work.touched : undefined,
+            createdPrs: work.createdPrs.length ? work.createdPrs : undefined,
             title: tail.title || (head.prompt ? oneLine(head.prompt, 60) : base.title),
             cwd: tail.cwd || head.cwd,
             startedAt: head.startedAt,
@@ -203,9 +304,13 @@ function readSubagent(file, now) {
     try {
         const meta = readMeta(file);
         const head = firstPrompt(file);
-        const tail = readClaudeTail(readTailLines(file, TAIL_BYTES), "subagent");
+        const tailRecs = readTailLines(file, TAIL_BYTES);
+        const tail = readClaudeTail(tailRecs, "subagent");
+        const work = scanWork(sameFile(file) ? tailRecs : [...readHeadLines(file, HEAD_BYTES), ...tailRecs]);
         const run = {
             ...base,
+            touched: work.touched.length ? work.touched : undefined,
+            createdPrs: work.createdPrs.length ? work.createdPrs : undefined,
             title: str(meta.description) || (head.prompt ? oneLine(head.prompt, 60) : base.title),
             model: str(meta.model),
             cwd: tail.cwd || head.cwd,

package/dist/bin/cli.js

@@ -2,12 +2,14 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import { Command } from "commander";
-import { UserError, addProject, answerCard, claimSession, closeCard, commentCard, consumerName, editCard, endRun, noteRun, openCard, readInbox, removeProject, startRun, waitInbox, } from "../core/ops.js";
+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 { githubConfig, readCache, resolvePrRef, syncGithub, prViews } from "../core/github.js";
+import { digest, digestText, localDate } from "../core/digest.js";
 import { readEvents } from "../core/store.js";
 import { followEvents } from "../core/follow.js";
 import { fold } from "../core/state.js";
 import { collectRuns } from "../core/runs.js";
-import { cardDetail, cardLine, cardRows, inboxLine, runsTree, view } from "../core/format.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 { cardContextLine, resolveGoto } from "../core/desktop.js";
@@ -29,7 +31,17 @@ 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.1.0");
+    .version("0.2.0");
+/** Read GitHub when the last reading is old; never fails the command. */
+async function refreshGithub(force = false) {
+    try {
+        await syncGithub({ state: fold(readEvents()), force });
+    }
+    catch (err) {
+        if (force)
+            throw err;
+    }
+}
 // ------------------------------------------------------------------ cards
 function cardCommand(kind, name, summary) {
     return program
@@ -64,10 +76,12 @@ function finishCard(input, json) {
     else
         process.stdout.write(`${card.id}\n`);
 }
-cardCommand("decide", "ask", "ask the human to decide")
+cardCommand("decide", "ask", "ask the human to decide, or to approve a prepared action")
     .option("-o, --option <text>", "a choice (repeatable)", collect)
     .option("-r, --recommend <n>", "the recommended choice, 1-based", int)
-    .action((title, o) => finishCard({ kind: "decide", title, ...common(o), options: o.option, recommend: o.recommend }, o.json));
+    .option("--action <text>", "the exact command or step that runs on yes (options default to Do it / Don't)")
+    .option("--preview <file>", "a file with the text the action sends or changes (a message, a diff)")
+    .action((title, o) => finishCard({ kind: "decide", title, ...common(o), options: o.option, recommend: o.recommend, action: o.action, preview: o.preview }, o.json));
 cardCommand("try", "try", "ask the human to try a build, watch a video or look at a screen")
     .option("--open <path>", "app, file or URL to open (repeatable)", collect)
     .option("-l, --look <text>", "what to look at")
@@ -96,7 +110,7 @@ program
 });
 program
     .command("goto <target>")
-    .description("open the agent session behind a card (or a session id) in the Claude desktop app")
+    .description("open the agent session behind a card, a pull request (URL, owner/repo#N, repo#N) or a session id in the Claude desktop app")
     .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) => {
@@ -145,10 +159,17 @@ program
     const card = fold(readEvents()).cards.get(id);
     if (!card)
         throw new UserError(`no card "${id}"`);
-    if (o.json)
+    if (o.json) {
         print(card);
-    else
-        process.stdout.write(cardDetail(card) + "\n");
+        return;
+    }
+    const waits = card.status === "closed" ? [] : listenersFor(card, listeners());
+    const delivery = card.status === "closed"
+        ? ""
+        : waits.length
+            ? `\nDelivery: an agent is waiting (${waits.map((l) => l.consumer).join(", ")}); an answer wakes it now.`
+            : "\nDelivery: no agent is waiting; an answer is kept until the agent next checks (its next turn, or its next wait).";
+    process.stdout.write(cardDetail(card) + delivery + "\n");
 });
 program
     .command("cards")
@@ -174,7 +195,14 @@ function inboxOptions(c) {
 inboxOptions(program.command("wait").description("block until the human answers, print the answers and exit"))
     .option("--timeout <seconds>", "give up after this long (exit code 2); 0 waits forever", int, 0)
     .action(async (o) => {
+    startListening({ consumer: consumerName(o), project: o.project, card: o.card, session: currentSession() });
+    // while waiting, keep GitHub fresh so news on linked pull requests wakes this wait
+    const tick = () => void refreshGithub();
+    tick();
+    const timer = setInterval(tick, 60_000);
+    timer.unref();
     const items = await waitInbox(consumerName(o), { project: o.project, card: o.card }, o.timeout * 1000);
+    clearInterval(timer);
     if (!items.length) {
         process.exitCode = 2;
         return;
@@ -209,10 +237,11 @@ program
     .option("--since <hours>", "look at logs touched in the last N hours", int, 6)
     .option("-a, --all", "include runs that ended a while ago")
     .option("--runtime <name>", "only this adapter (repeatable)", collect)
+    .option("--every", "list each run of a scheduled task instead of one row per task")
     .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 });
+    const runs = collectRuns(fold(readEvents()), { sinceHours: o.since, project: o.project, includeEnded: o.all, runtimes: o.runtime, keepRepeats: o.every });
     if (o.json)
         print({ v: SCHEMA_VERSION, runs });
     else
@@ -224,10 +253,13 @@ run
     .requiredOption("-p, --project <name>", "project")
     .option("-t, --task <task>", "task")
     .option("--parent <id>", "the run that started this one (defaults to the calling session)")
+    .option("--heartbeat <seconds>", "count the run as stalled after this long without a beat, a note or log output", int)
+    .option("--log <file>", "a log file the job writes; each change counts as a beat")
     .action((title, o) => {
-    process.stdout.write(startRun({ title, project: o.project, task: o.task, parent: o.parent ?? currentSession() }) + "\n");
+    process.stdout.write(startRun({ title, project: o.project, task: o.task, parent: o.parent ?? currentSession(), heartbeat: o.heartbeat, log: o.log }) + "\n");
 });
-run.command("note <id> <text>").action((id, text) => noteRun(id, text));
+run.command("note <id> <text>").description("say how it is going (also counts as a beat)").action((id, text) => noteRun(id, text));
+run.command("beat <id>").description("say it is still alive").action((id) => beatRun(id));
 run
     .command("end <id>")
     .option("--failed", "it failed")
@@ -235,53 +267,152 @@ run
     .action((id, o) => endRun(id, o.failed ? "failed" : "done", o.note));
 program
     .command("claim [session]")
-    .description("say which project an agent session belongs to (id prefix, 6+ characters; defaults to the calling session)")
-    .requiredOption("-p, --project <name>", "project")
-    .option("-t, --task <task>", "task")
+    .description("say which project and task an agent session works on (id prefix, 6+ characters; defaults to the calling session)")
+    .option("-p, --project <name>", "project (may be left out once the session has claimed one)")
+    .option("-t, --task <task>", "task: a ticket key, a PR, a short name")
     .option("--role <role>", "for example lead or worker")
     .option("--title <title>", "name to show")
+    .option("--kind <kind>", "'scheduled' for a session a schedule starts again and again")
+    .option("--done <summary>", "the work is finished; one line on how it ended")
     .action((session, o) => {
     const id = session ?? currentSession();
     if (!id)
         throw new UserError("no session id given and none found in the environment (CLAUDE_CODE_SESSION_ID, CODEX_THREAD_ID)");
-    claimSession({ session: id, project: o.project, task: o.task, role: o.role, title: o.title });
-    process.stdout.write(`${id.slice(0, 8)} → ${o.project}${o.role ? ` (${o.role})` : ""}\n`);
+    if (o.kind !== undefined && o.kind !== "scheduled")
+        throw new UserError("--kind can only be 'scheduled'");
+    const c = claimSession({ session: id, project: o.project, task: o.task, role: o.role, title: o.title, kind: o.kind, done: o.done });
+    process.stdout.write(`${id.slice(0, 8)} → ${c.project}${c.task ? ` / ${c.task}` : ""}${c.role ? ` (${c.role})` : ""}${c.done ? " · done" : ""}\n`);
+});
+// ------------------------------------------------------------------ pull requests
+const pr = program.command("pr").description("pull requests and what they wait on (reads GitHub through gh)");
+pr.command("link <pr>")
+    .description("say this pull request belongs to the calling session: news on it wakes the session's wait")
+    .option("-p, --project <name>", "project (defaults to the session's claim)")
+    .option("-t, --task <task>", "task (defaults to the session's claim)")
+    .option("--session <id>", "the owning session (defaults to the calling session)")
+    .action((ref, o) => {
+    const r = resolvePrRef(ref);
+    const session = o.session ?? currentSession();
+    linkPr({ pr: r, session, project: o.project, task: o.task });
+    process.stdout.write(`${r.repo}#${r.number} → ${session ? session.slice(0, 8) : o.project ?? "no session"}\n`);
+});
+pr.command("unlink <pr>")
+    .description("forget which session owns a pull request")
+    .action((ref) => unlinkPr(resolvePrRef(ref).key));
+pr.command("list")
+    .description("open pull requests you wrote or are asked to review, with what each waits on")
+    .option("-p, --project <name>", "only this project")
+    .option("--offline", "do not read GitHub, show the last reading")
+    .option("--json", "JSON output")
+    .action(async (o) => {
+    if (!o.offline)
+        await refreshGithub();
+    const state = fold(readEvents());
+    const runs = collectRuns(state, { sinceHours: 72 });
+    let prs = prViews(readCache(), state, runs);
+    if (o.project)
+        prs = prs.filter((p) => p.project === o.project);
+    if (o.json)
+        print({ v: SCHEMA_VERSION, prs });
+    else
+        process.stdout.write(prs.length ? prRows(prs, view()).join("\n") + "\n" : githubNote() ?? "No open pull requests.\n");
+});
+pr.command("sync")
+    .description("read GitHub now")
+    .action(async () => {
+    const c = await syncGithub({ state: fold(readEvents()), 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`);
+});
+pr.command("event <pr> <change>")
+    .description("record news another tool saw on a pull request (a merge bot, a ticket system); it wakes the owner like GitHub's own")
+    .option("-m, --text <text>", "what happened")
+    .option("--by <who>", "who did it")
+    .action((ref, change, o) => prEvent(resolvePrRef(ref), change, { text: o.text, by: o.by }));
+function githubNote() {
+    if (!githubConfig().enabled)
+        return "GitHub is turned off in config.json.\n";
+    const c = readCache();
+    if (c.hosts && !c.hosts.length)
+        return "GitHub: gh is not installed or not signed in (gh auth login).\n";
+    return undefined;
+}
+program
+    .command("digest")
+    .description("what each session did on a day: work claimed, cards, jobs, pull request news, how it ended")
+    .option("-d, --date <YYYY-MM-DD>", "the day (default: today)")
+    .option("--json", "JSON output")
+    .action((o) => {
+    const d = digest(o.date ?? localDate());
+    if (o.json)
+        print({ v: SCHEMA_VERSION, ...d });
+    else
+        process.stdout.write(digestText(d) + "\n");
 });
 // ------------------------------------------------------------------ status
 program
     .command("status")
-    .description("everything at a glance: what needs you, then what is running")
+    .description("everything at a glance: what needs you, what waits on others, then what is running")
     .option("-p, --project <name>", "only this project")
     .option("--since <hours>", "look at logs touched in the last N hours", int, 6)
+    .option("--offline", "do not read GitHub, show the last reading")
     .option("-w, --wide", "show runtime and ids")
     .option("--json", "JSON output")
-    .action((o) => {
+    .action(async (o) => {
+    if (!o.offline)
+        await refreshGithub();
     const snap = snapshot({ sinceHours: o.since, project: o.project });
     if (o.json) {
         print(snap);
         return;
     }
     const { cards, runs } = snap;
+    const prs = snap.prs ?? [];
     const v = view({ wide: o.wide });
+    const now = Date.now();
     const head = (title, n, ...extra) => v.color ? `\x1b[1m${title}\x1b[0m  \x1b[2m${n}${extra.join("")}\x1b[0m` : `${title}  ${n}${extra.join("")}`;
     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 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, Date.now(), "  "));
+    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 (reviews.length) {
+        out.push("", head("REVIEWS ASKED OF YOU", reviews.length));
+        out.push(...prRows(reviews, v, now, "  "));
+    }
     if (todo.length) {
         out.push("", head("TO DO, NOTHING WAITS ON IT", todo.length));
-        out.push(...cardRows(todo, v, Date.now(), "  "));
+        out.push(...cardRows(todo, v, now, "  "));
     }
     if (answered.length) {
+        const notes = {};
+        for (const c of answered)
+            if (!listenersFor(c, ls).length)
+                notes[c.id] = "no agent waiting";
         out.push("", head("ANSWERED, WAITING FOR THE AGENT", answered.length));
-        out.push(...cardRows(answered, v, Date.now(), "  "));
+        out.push(...cardRows(answered, v, now, "  ", notes));
+    }
+    if (waiting.length) {
+        const stuck = waiting.filter((p) => p.stalled).length;
+        out.push("", head("WAITING ON OTHERS", waiting.length, stuck ? ` · ${stuck} stuck` : ""));
+        out.push(...prRows(waiting, v, now, "  "));
     }
     const working = runs.filter((r) => r.state === "working" || r.state === "waiting").length;
     out.push("", head("AGENTS", runs.length ? `${working} working` : "nothing running"));
     if (runs.length)
         out.push(runsTree(runs, v));
+    if (snap.github?.error && snap.github.enabled)
+        out.push("", v.color ? `\x1b[2mGitHub: ${snap.github.error}\x1b[0m` : `GitHub: ${snap.github.error}`);
     process.stdout.write(out.join("\n") + "\n");
 });
 // ------------------------------------------------------------------ skill