parawatch 0.3.11 → 0.3.12

package/dist/bin/cli.js

@@ -2,7 +2,7 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import { Command } from "commander";
-import { UserError, addProject, answerCard, beatRun, claimSession, closeCard, dismissCard, commentCard, inboxScope, editCard, endRun, hideRun, unhideRun, linkPr, listeners, listenersFor, noteRun, openCard, prEvent, findCard, readInbox, readState, removeProject, startListening, startRun, unlinkPr, waitInbox, } from "../core/ops.js";
+import { UserError, addProject, answerCard, beatRun, claimSession, closeCard, dismissCard, endedSessions, handCard, handPr, leadOf, makeLead, commentCard, inboxScope, editCard, endRun, hideRun, unhideRun, linkPr, listeners, listenersFor, noteRun, openCard, prEvent, findCard, readInbox, readState, removeProject, startListening, startRun, unlinkPr, waitInbox, } from "../core/ops.js";
 import { githubConfig, readCache, resolvePrRef, syncGithub, prViews } from "../core/github.js";
 import { recordPrompt } from "../core/prompts.js";
 import { callingSubagent } from "../adapters/claudeCode.js";
@@ -190,6 +190,26 @@ program
     .description("close a card that no longer matters, without answering it; the agent that asked is told")
     .option("-n, --note <text>", "why, for the agent")
     .action((id, o) => dismissCard(id, o.note));
+program
+    .command("hand <target> <session>")
+    .description("give a card or a pull request to another session (id prefix, 6+ characters); that session is told once")
+    .action((target, session) => {
+    if (/#\d+$|:\/\//.test(target)) {
+        const ref = resolvePrRef(target);
+        handPr(ref, session);
+        process.stdout.write(`${ref.repo}#${ref.number} → ${session.slice(0, 8)}\n`);
+        return;
+    }
+    const card = handCard(target, session);
+    process.stdout.write(`${card.id} → ${session.slice(0, 8)}\n`);
+});
+program
+    .command("lead <project> <session>")
+    .description("make a session the project's lead: it gets what no session owns there, and what ended sessions left")
+    .action((project, session) => {
+    const r = makeLead(project, session);
+    process.stdout.write(`${r.session.slice(0, 8)} leads ${project}${r.handed.length ? `; handed ${r.handed.join(", ")}` : ""}\n`);
+});
 program
     .command("show <card>")
     .description("show one card with its answers")
@@ -203,11 +223,16 @@ program
         return;
     }
     const waits = card.status === "closed" ? [] : listenersFor(card, listeners());
+    const state = readState();
+    const ended = endedSessions(state);
+    const noOne = card.status !== "closed" && (!card.session || ended(card.session)) && !leadOf(state, ended)(card.project);
     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).";
+        : noOne
+            ? `\nDelivery: no session gets an answer (${card.session ? "its session has ended" : "no session opened it"}, and ${card.project} has no lead). Pick a lead with parawatch lead ${card.project} <session>, or hand it on with parawatch hand ${card.id} <session>.`
+            : 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
@@ -226,9 +251,9 @@ program
 // ------------------------------------------------------------------ inbox
 function inboxOptions(c) {
     return c
-        .option("-p, --project <name>", "everything in this project, whoever owns it (for a lead)")
+        .option("-p, --project <name>", "this project instead of the claimed one; outside a session, everything in it")
         .option("--card <id>", "only answers to this card")
-        .option("--as <consumer>", "cursor name (defaults to the session, or the project with -p)")
+        .option("--as <consumer>", "cursor name (defaults to the session; outside a session, the project with -p)")
         .option("--json", "JSON output");
 }
 inboxOptions(program
@@ -341,7 +366,9 @@ program
     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`);
+    // a new lead: earlier leads of the project step down, and it takes what no session got
+    const handed = o.role === "lead" && !c.done ? makeLead(c.project, id).handed : [];
+    process.stdout.write(`${id.slice(0, 8)} → ${c.project}${c.task ? ` / ${c.task}` : ""}${c.role ? ` (${c.role})` : ""}${c.done ? " · done" : ""}${handed.length ? `; handed ${handed.join(", ")}` : ""}\n`);
 });
 // ------------------------------------------------------------------ pull requests
 const pr = program.command("pr").description("pull requests and what they wait on (reads GitHub through gh)");
@@ -436,16 +463,23 @@ program
     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");
+    // answered, but no session gets it: no owner left and no lead in the project
+    const stranded = cards.filter((c) => c.status === "answered" && c.unrouted);
+    const answered = cards.filter((c) => c.status === "answered" && !c.unrouted);
+    const strandedPrs = prs.filter((p) => p.unrouted);
     // a session held by a permission prompt needs the human as much as a card does
     const prompts = runs.filter((r) => r.asks?.via === "permission");
     const askers = runs.filter((r) => r.asks && r.asks.via !== "permission");
     const reviews = prs.filter((p) => p.reviewRequested && !p.mine);
-    const waiting = prs.filter((p) => !(p.reviewRequested && !p.mine));
+    const waiting = prs.filter((p) => !(p.reviewRequested && !p.mine) && !p.unrouted);
     const ls = snap.listeners ?? [];
     const out = [];
     out.push(head("NEEDS YOU", open.length + prompts.length || "nothing"));
-    out.push(...cardRows(open, v, now, "  "));
+    const noOne = {};
+    for (const c of open)
+        if (c.unrouted)
+            noOne[c.id] = "no session gets the answer";
+    out.push(...cardRows(open, v, now, "  ", noOne));
     out.push(...askRows(prompts, v, now, "  "));
     if (askers.length) {
         out.push("", head("ASKED IN CHAT, NO CARD", askers.length, "  (read from the log)"));
@@ -459,6 +493,14 @@ program
         out.push("", head("TO DO, NOTHING WAITS ON IT", todo.length));
         out.push(...cardRows(todo, v, now, "  "));
     }
+    if (stranded.length || strandedPrs.length) {
+        out.push("", head("NO SESSION GETS THESE", stranded.length + strandedPrs.length, "  (no owner left, no lead)"));
+        out.push(...cardRows(stranded, v, now, "  "));
+        out.push(...prRows(strandedPrs, v, now, "  "));
+        const projects = [...new Set([...stranded.map((c) => c.project), ...strandedPrs.map((p) => p.project)])];
+        const dim = (t) => (v.color ? `\x1b[2m${t}\x1b[0m` : t);
+        out.push(dim(`  pick a lead: parawatch lead ${projects.length === 1 ? projects[0] : "<project>"} <session>   or hand one on: parawatch hand <card or PR> <session>`));
+    }
     if (answered.length) {
         const notes = {};
         // the snapshot already marked the cards whose session has ended

package/dist/core/format.js

@@ -179,12 +179,26 @@ export function prChangeText(change, by) {
     return by && by !== "github" && by !== "external" ? `${w} by ${by}` : w;
 }
 export function inboxLine(i) {
+    if (i.kind === "handed" && i.pr) {
+        const p = i.pr;
+        return `[${p.project ?? "?"}] PR ${p.ref.repo}#${p.ref.number}${p.title ? ` "${p.title}"` : ""} handed to you by the human: its news wakes you from now on (${p.ref.url})`;
+    }
     if (i.kind === "pr" && i.pr) {
         const p = i.pr;
-        return `[${p.project ?? "?"}] PR ${p.ref.repo}#${p.ref.number}${p.title ? ` "${p.title}"` : ""}: ${prChangeText(p.change, i.by)}${p.text ? `; ${p.text}` : ""} (${p.ref.url})`;
+        return `[${p.project ?? "?"}] PR ${p.ref.repo}#${p.ref.number}${p.title ? ` "${p.title}"` : ""}: ${p.change ? prChangeText(p.change, i.by) : "news"}${p.text ? `; ${p.text}` : ""} (${p.ref.url})`;
     }
     const card = i.card;
     const head = `[${card.project}] ${card.id} "${card.title}"`;
+    if (i.kind === "handed") {
+        const was = [];
+        if (i.choice !== undefined)
+            was.push(`chose ${i.choice}${i.choiceText ? ` (${i.choiceText})` : ""}`);
+        if (i.comment)
+            was.push(`said: ${i.comment}`);
+        if (i.attach?.length)
+            was.push(`attached: ${i.attach.join(", ")}`);
+        return `${head} handed to you by the human; ${was.length ? `the answer: ${was.join("; ")}` : "not answered yet"}`;
+    }
     if (i.kind === "comment")
         return `${head} comment: ${i.comment}`;
     if (i.kind === "dismissed")

package/dist/core/integrate.js

@@ -24,7 +24,7 @@ The human follows this work through \`parawatch\`. Use it instead of asking in c
 - Stuck until the human does something only they can do (install, sudo, sign in): \`parawatch block --project ${p} "what to do"\`
 - Something only the human can do, but nothing waits on it now: \`parawatch todo --project ${p} "what to do"\`
 - Put every question for the human on a card, not only in your reply: a question left in chat is easy to miss.
-- After opening a card or linking a pull request, keep a background wait armed: \`parawatch wait\`. It prints the human's answers to your cards and news on your pull requests and exits; act on them, \`parawatch close <card> --note "what you did"\`, then arm it again. A lead watching the whole project waits with \`parawatch wait --project ${p}\`.
+- After opening a card or linking a pull request, keep a background wait armed: \`parawatch wait\`. It prints the human's answers to your cards and news on your pull requests and exits; act on them, \`parawatch close <card> --note "what you did"\`, then arm it again. A lead waits the same way; answers on another live session's cards go to that session. What no session owns goes to the lead (\`parawatch claim --project ${p} --role lead\`).
 - A long job with no agent log (a bake, a benchmark): \`parawatch run start --project ${p} "title" --heartbeat <seconds> [--log <file>]\`, \`parawatch run note <id> "..."\`, \`parawatch run end <id>\`.
 - Never answer a card yourself. \`parawatch status\` shows everything that is open.
 ${END}`;

package/dist/core/ops.js

@@ -234,6 +234,65 @@ export function dismissCard(id, note) {
         throw new UserError(`card ${card.id} is already closed`);
     appendEvent(() => ({ type: "card.close", card: card.id, note: note?.trim() || undefined, dismissed: true }));
 }
+/** The session id as claims hold it, when one matches; else as given. */
+function claimedId(state, session) {
+    return state.claims.find((c) => sameSession(c.session, session))?.session ?? session;
+}
+/** Give an open card to another session. That session is told once, with the last answer. */
+export function handCard(id, session) {
+    const card = requireCard(id);
+    if (card.status === "closed")
+        throw new UserError(`card ${card.id} is already closed`);
+    if (session.length < 6)
+        throw new UserError("give at least 6 characters of the session id");
+    const to = claimedId(readState(), session);
+    appendEvent(() => ({ type: "card.hand", card: card.id, session: to, by: HUMAN }));
+    return card;
+}
+/** Give a pull request to another session: its news wakes that session from now on. */
+export function handPr(pr, session) {
+    if (session.length < 6)
+        throw new UserError("give at least 6 characters of the session id");
+    const state = readState();
+    const link = state.prLinks.get(pr.key);
+    linkPr({ pr, session: claimedId(state, session), project: link?.project, task: link?.task, handed: true });
+}
+/**
+ * Answered cards no session gets in a project: no owner, or the owner has ended, and no live lead
+ * (or a lead that came after the answer). A new lead takes them over.
+ */
+export function backlogOf(project, state = readState()) {
+    const ended = endedSessions(state);
+    return [...state.cards.values()].filter((c) => c.project === project && c.status === "answered" && (!c.session || ended(c.session)));
+}
+/** Hand the answered cards no session gets to the project's lead, who is told of each once. */
+export function takeBacklog(project, session) {
+    const handed = [];
+    for (const c of backlogOf(project)) {
+        if (sameSession(c.session, session))
+            continue;
+        handCard(c.id, session);
+        handed.push(c.id);
+    }
+    return handed;
+}
+/**
+ * Make a session the project's lead (the human's pick, from the panel or `parawatch lead`).
+ * Earlier leads of the project step down; answered cards no session got are handed to it.
+ */
+export function makeLead(project, session) {
+    if (session.length < 6)
+        throw new UserError("give at least 6 characters of the session id");
+    const state = readState();
+    const to = claimedId(state, session);
+    for (const c of state.claims) {
+        if (c.role === "lead" && c.project === project && !sameSession(c.session, to))
+            claimSession({ session: c.session, role: "", done: c.done });
+    }
+    // a lead works on: any done it said earlier no longer stands
+    claimSession({ session: to, project, role: "lead" });
+    return { session: to, handed: takeBacklog(project, to) };
+}
 export function startRun(r) {
     if (r.heartbeat !== undefined && (!Number.isFinite(r.heartbeat) || r.heartbeat <= 0))
         throw new UserError("--heartbeat must be a number of seconds above 0");
@@ -320,7 +379,7 @@ export function linkPr(link) {
     const project = link.project?.trim() || claim?.project;
     appendEvent(() => ({
         type: "pr.link",
-        link: { pr: link.pr, session: link.session, project, task: link.task?.trim() || claim?.task, auto: link.auto || undefined },
+        link: { pr: link.pr, session: link.session, project, task: link.task?.trim() || claim?.task, auto: link.auto || undefined, handed: link.handed || undefined },
     }));
 }
 export function unlinkPr(key) {
@@ -354,15 +413,33 @@ export function endedSessions(state, isArchived) {
         return archived(session);
     };
 }
+/**
+ * The project's lead: the session that most recently claimed it with `--role lead` and has not
+ * ended. It gets what no session owns in the project, and what a session that has ended left.
+ */
+export function leadOf(state, ended) {
+    const memo = new Map();
+    return (project) => {
+        if (!project)
+            return undefined;
+        if (!memo.has(project)) {
+            const leads = state.claims
+                .filter((c) => c.role === "lead" && c.project === project && !c.done && !ended(c.session))
+                .sort((a, b) => (b.at ?? "").localeCompare(a.at ?? ""));
+            memo.set(project, leads[0]?.session);
+        }
+        return memo.get(project);
+    };
+}
 /** Whether something owned by `owner` in `project` is for a reader with this filter. */
-function inScope(owner, project, f, ended) {
+function inScope(owner, project, f, ended, lead) {
     if (f.session) {
         if (owner && sameSession(owner, f.session))
             return true;
-        // what a session that has ended owned is the project's now
         if (owner && !ended(owner))
             return false;
-        return !!f.project && project === f.project;
+        // no owner, or it has ended: the project's lead takes it; without a lead it waits in parawatch
+        return sameSession(lead(project), f.session);
     }
     return !f.project || project === f.project;
 }
@@ -379,8 +456,55 @@ export function inboxFrom(events, after, filter, state = readState(events)) {
     const reported = new Map();
     const answerNo = new Map();
     const ended = filter.ended ?? endedSessions(state);
-    for (const ev of events) {
+    const lead = leadOf(state, ended);
+    const finished = new Set();
+    // a card handed to this reader comes with its last answer; the answers before it are not repeated
+    const handedAt = new Map();
+    if (filter.session) {
+        events.forEach((ev, i) => {
+            if (ev.type === "card.hand" && isAfter(ev, pos) && sameSession(ev.session, filter.session))
+                handedAt.set(ev.card, i);
+        });
+    }
+    for (const [i, ev] of events.entries()) {
+        if (ev.type === "pr.link") {
+            // a pull request the human handed to this session: told once
+            if (!ev.link.handed || !isAfter(ev, pos) || !filter.session || filter.card || !sameSession(ev.link.session, filter.session))
+                continue;
+            const now = state.prLinks.get(ev.link.pr.key);
+            if (!now || !sameSession(now.session, filter.session))
+                continue;
+            out.push({ seq: ev.seq, dev: ev.dev, at: ev.ts, kind: "handed", by: HUMAN, pr: { ref: ev.link.pr, project: now.project } });
+            continue;
+        }
+        if (ev.type === "card.hand") {
+            // a card the human handed to this session: told once, with the last answer on it
+            if (!isAfter(ev, pos) || !filter.session || !sameSession(ev.session, filter.session))
+                continue;
+            const card = state.cards.get(ev.card);
+            if (!card || card.status === "closed" || !sameSession(card.session, filter.session))
+                continue;
+            if (filter.card && card.id !== filter.card)
+                continue;
+            const last = [...card.answers].reverse().find((a) => a.by === HUMAN && !a.late);
+            out.push({
+                seq: ev.seq,
+                dev: ev.dev,
+                at: ev.ts,
+                kind: "handed",
+                card,
+                by: ev.by,
+                choice: last?.choice,
+                choiceText: last?.choice !== undefined ? card.options?.[last.choice - 1] : undefined,
+                comment: last?.comment,
+                attach: last?.attach,
+            });
+            continue;
+        }
         if (ev.type === "pr.change") {
+            const wasOver = finished.has(ev.pr.key);
+            if (ev.change === "merged" || ev.change === "closed")
+                finished.add(ev.pr.key);
             const k = `${ev.pr.key}|${ev.change}|${ev.text ?? ""}`;
             const prev = reported.get(k);
             const at = Date.parse(ev.ts);
@@ -390,7 +514,11 @@ export function inboxFrom(events, after, filter, state = readState(events)) {
             if (!isAfter(ev, pos))
                 continue;
             const link = state.prLinks.get(ev.pr.key);
-            if (!link || filter.card || !inScope(link.session, link.project, filter, ended))
+            if (!link || filter.card || !inScope(link.session, link.project, filter, ended, lead))
+                continue;
+            // a merged or closed pull request whose owner has ended needs no one: its news, the merge
+            // itself and the bot comments after it, stays on the pull request
+            if (filter.session && !sameSession(link.session, filter.session) && (wasOver || finished.has(ev.pr.key)))
                 continue;
             out.push({ seq: ev.seq, dev: ev.dev, at: ev.ts, kind: "pr", by: ev.by ?? ev.source, pr: { ref: ev.pr, change: ev.change, title: ev.title, text: ev.text, project: link.project } });
             continue;
@@ -400,7 +528,7 @@ export function inboxFrom(events, after, filter, state = readState(events)) {
             if (!ev.dismissed || !isAfter(ev, pos))
                 continue;
             const card = state.cards.get(ev.card);
-            if (!card || !inScope(card.session, card.project, filter, ended))
+            if (!card || !inScope(card.session, card.project, filter, ended, lead))
                 continue;
             if (filter.card && card.id !== filter.card)
                 continue;
@@ -419,10 +547,12 @@ export function inboxFrom(events, after, filter, state = readState(events)) {
             continue;
         if (ev.by !== HUMAN || late)
             continue;
+        if ((handedAt.get(ev.card) ?? -1) > i)
+            continue;
         const card = state.cards.get(ev.card);
         if (!card || card.status === "closed")
             continue;
-        if (!inScope(card.session, card.project, filter, ended))
+        if (!inScope(card.session, card.project, filter, ended, lead))
             continue;
         if (filter.card && card.id !== filter.card)
             continue;
@@ -539,19 +669,23 @@ export function listeners(now = Date.now()) {
     return out;
 }
 /**
- * The waits an answer to this card would wake right now. A card whose session has ended reaches
- * the session waits in its project, as an unowned card does. A snapshot's card says so itself
- * (`ownerEnded`); otherwise `ended` tells.
+ * The waits an answer to this card would wake right now. A card whose session has ended, or that
+ * no session opened, reaches the project's lead only. A snapshot's card says so itself
+ * (`ownerEnded`, `lead`, `unrouted`); otherwise `ended` and the claims tell.
  */
 export function listenersFor(card, ls, ended) {
     let gone = card.ownerEnded;
-    const ownerGone = () => (gone ??= !!card.session && (ended ?? endedSessions(readState()))(card.session));
+    const isEnded = () => ended ?? endedSessions(readState());
+    const ownerGone = () => (gone ??= !!card.session && isEnded()(card.session));
+    // a snapshot's card names its lead, or says it has none
+    let lead = card.lead ?? (card.unrouted ? null : undefined);
+    const leadNow = () => (lead === undefined ? (lead = leadOf(readState(), isEnded())(card.project) ?? null) : lead) ?? undefined;
     return ls.filter((l) => l.card
         ? l.card === card.id
         : l.scope === "session"
             ? card.session && sameSession(l.session, card.session)
                 ? true
-                : (!card.session || ownerGone()) && !!l.project && l.project === card.project
+                : (!card.session || ownerGone()) && sameSession(l.session, leadNow())
             : !l.project || l.project === card.project);
 }
 export function consumerName(opts) {
@@ -574,13 +708,23 @@ export function furthest(a, b) {
  * that name. Called from an agent session without either, it reads that session's own cards and
  * pull requests, plus unowned ones in the project the session claimed, with a cursor of its own:
  * sessions in one project neither wake for each other's news nor take it from each other.
- * Outside a session, it reads everything.
+ * `--project` from a session names the project instead of the claim, with the same rule. Outside
+ * a session, it reads everything.
  */
 export function inboxScope(opts, session) {
-    if (opts.card || opts.project || !session)
+    if (opts.card || !session)
         return { consumer: consumerName(opts), filter: { project: opts.project, card: opts.card } };
-    const claim = readState().claims.find((c) => sameSession(session, c.session));
     const consumer = opts.as || sessionConsumer(session);
+    if (opts.project) {
+        // A lead waiting on its project from a session: what other live sessions own is theirs. It
+        // takes over the project cursor once, so it does not hear again what that wait delivered.
+        const mine = readCursor(consumer);
+        const merged = furthest(mine, readCursor(opts.project));
+        if (JSON.stringify(merged) !== JSON.stringify(mine))
+            writeCursor(consumer, merged);
+        return { consumer, filter: { session, project: opts.project } };
+    }
+    const claim = readState().claims.find((c) => sameSession(session, c.session));
     // A session that used to wait on its project starts where that wait stopped, so moving to its
     // own cursor does not bring back news it has already handled.
     if (claim && !Object.keys(readCursor(consumer)).length) {

package/dist/core/snapshot.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { prViews, keyOf, parsePrRef, readCache, githubConfig, githubFailing } from "./github.js";
-import { endedSessions, linkPr, listeners, readState } from "./ops.js";
+import { endedSessions, leadOf, linkPr, listeners, readState } from "./ops.js";
 import { collectRuns } from "./runs.js";
 import { deviceName, eventFiles, sharedDir } from "./store.js";
 import { SCHEMA_VERSION } from "./types.js";
@@ -18,8 +18,15 @@ export function snapshot(opts = {}) {
         state = readState();
     const all = [...state.cards.values()].filter((c) => !opts.project || c.project === opts.project);
     const ended = endedSessions(state);
+    const lead = leadOf(state, ended);
+    // what has no live owner goes to the project's lead; with none, it waits here
+    const route = (x) => {
+        const to = lead(x.project);
+        return to ? { ...x, lead: to } : { ...x, unrouted: true };
+    };
     const cards = [...all.filter((c) => c.status !== "closed"), ...recentlyClosed(all, opts.closed ?? 0)]
         .map((c) => (c.status !== "closed" && c.session && ended(c.session) ? { ...c, ownerEnded: true } : c))
+        .map((c) => (c.status !== "closed" && (!c.session || c.ownerEnded) ? route(c) : c))
         .map((c) => {
         const missing = notHere([...(c.attach ?? []), ...(c.open ?? [])]);
         return missing.length ? { ...c, missing } : c;
@@ -30,6 +37,9 @@ export function snapshot(opts = {}) {
     let prs = enabled ? prViews(cache, state, runs) : undefined;
     if (prs && opts.project)
         prs = prs.filter((p) => p.project === opts.project);
+    // a pull request linked to a project whose session has ended, or that has none
+    if (prs)
+        prs = prs.map((p) => (p.state === "open" && p.project && (!p.session || ended(p.session)) ? route(p) : p));
     return {
         v: SCHEMA_VERSION,
         generatedAt: new Date().toISOString(),

package/dist/core/state.js

@@ -86,6 +86,14 @@ export function fold(events, map) {
                     c.dismissed = true;
                 break;
             }
+            case "card.hand": {
+                const c = s.cards.get(ev.card);
+                if (!c)
+                    break;
+                c.session = ev.session;
+                c.handedAt = ev.ts;
+                break;
+            }
             case "run.start":
                 s.runs.set(ev.run.id, { ...ev.run, startedAt: ev.ts, lastActivity: ev.ts, status: "running" });
                 break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parawatch",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "A control tower for people running many AI coding agents in parallel: see what is running, what needs you, and wake the right agent when you answer.",
   "keywords": [
     "ai-agents",

package/skills/parawatch/SKILL.md

@@ -80,7 +80,9 @@ Right after opening cards or linking a pull request, keep exactly one wait armed
 - **Claude Code**: run `parawatch wait` 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` at the start of every turn.
 
-Inside your session, `wait` and `inbox` read only what is yours: answers on cards you opened, news on pull requests linked to you, and cards or pull requests no session owns in the project you claimed. Other sessions in the same project are not woken by your news and cannot take it from you. `-p <project>` reads the whole project instead; leave it to a lead (section 8).
+Inside your session, `wait` and `inbox` read only what is yours: answers on cards you opened and news on pull requests linked to you. Other sessions in the same project are not woken by your news and cannot take it from you, and you are not woken by theirs. What no session owns, and what a session that has ended left open, goes to the project's lead (section 8); with no lead it waits in parawatch until the human picks one. `-p <project>` only names a project other than the one you claimed.
+
+If the human hands you a card or a pull request (`parawatch hand`), your wait prints `[project] c4 "..." handed to you by the human; the answer: ...`. It is yours from then on: act on it and close it like your own.
 
 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.
 
@@ -120,12 +122,13 @@ 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.
+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. Close the cards you handled first: cards still open and pull requests not yet merged pass to the project's lead, or wait in parawatch when there is none. News on your pull requests that are already merged or closed wakes no one else.
 
 ## 8. Leads and workers
 
-- A lead that watches the whole project waits with `parawatch wait -p <project>`.
-- 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.
+- A lead claims with `--role lead` and waits like any session, with a plain `parawatch wait`. Besides its own news it gets what no session owns in its project and what sessions that have ended left open, and on claiming it is handed the answers that waited for a lead. One lead per project: a new lead replaces the old one. The human can also pick the lead in the panel, or with `parawatch lead <project> <session>`.
+- The lead owns the cards for the work it hands out. 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.
+- A session the human started on their own asks the human directly. Its cards and pull requests are its own: answers and news on them go to it, not to the lead. When that work belongs in the lead's queue, the session tells the lead, not the other way round.
 - 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`.