parawatch 0.3.1 → 0.3.3

package/README.md

@@ -154,7 +154,7 @@ parawatch ask -p api "Merge PR 88?" --action "gh pr merge 88 --squash" --preview
 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 wait                   # 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
@@ -167,7 +167,7 @@ An approval (`ask --action`) shows the exact command and the text it sends, with
 
 `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 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.
+`wait` prints the answers, and news on linked pull requests, and exits with code 0. Run from an agent session, it reads that session's own cards and pull requests, and the ones no session owns in the project it claimed, with a cursor of its own: four sessions in one project each wake only for their own news. `wait -p <project>` reads the whole project, for a lead. 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
 
@@ -177,9 +177,9 @@ An approval (`ask --action`) shows the exact command and the text it sends, with
 
 ### Waking a Claude Code session
 
-Claude Code re-invokes a session when one of its background commands exits. So an agent that runs `parawatch wait -p <project>` as a background command is woken by your answer, with the answer as the command's output.
+Claude Code re-invokes a session when one of its background commands exits. So an agent that runs `parawatch wait` as a background command is woken by your answer, with the answer as the command's output.
 
-As a backstop, the hook adds any unhandled answers to the next turn of a session in that project:
+As a backstop, the hook adds the session's unhandled answers and pull request news to its next turn:
 
 ```json
 {
@@ -290,10 +290,13 @@ parawatch sync            # this machine, the others, how the sync tool is doing
 - **Ids carry the machine once a log is shared:** `pc-c3`, `mac-r2`. Commands take the short form (`parawatch close c3`) while only one machine has that number. Cards from before the move keep their ids.
 - **When two machines answer one card before either has seen the other's answer, the earlier answer stands.** The other one stays on the card, marked as not used, and does not wake the agent. An answer given after seeing the first one counts as usual.
 - **Paths follow the machine.** Attachments, things to open and project folders written on another machine are read as the same place here, under its home folder or the shared folder. Name other folders that sit in different places on each machine (a cloud drive, say): `parawatch sync root gdrive "G:\My Drive"` on one machine and `parawatch sync root gdrive ~/Library/CloudStorage/…/My\ Drive` on the other. Pasted pictures are saved in the shared folder, so every machine can open them.
+- **A path that is absolute on either system is kept as written**, so an agent on the PC can ask you to open `/Users/Shared/Try/Game.app` on the Mac. Git Bash on Windows rewrites arguments that start with `/` before parawatch sees them; run such commands there with `MSYS_NO_PATHCONV=1`.
 - **Waits are seen everywhere.** A card on your laptop says whether an agent on the PC is waiting for it.
+- **Runs are seen everywhere.** Each machine writes a summary of the sessions its agent logs show (state, title, project, last activity, what each does) to `runs/<device>.json` about every half minute while `status`, a `wait` or the app runs. The other machines show those runs marked with the machine. The logs stay where they are. A machine whose summary is older than 15 minutes drops out of the list.
 - **Every machine reads GitHub for itself.** The same news is delivered once.
+- **Cards reach you as far as the sync tool does.** With Syncthing, leave global discovery and relays on (its defaults) to stay in step from another network; with them off, machines only meet on the same network or a VPN. `parawatch sync` shows each connection's address, a relay included.
 
-The shared folder holds `events/`, `devices/` (each machine's paths, version and last sign of life), `listeners/` and `attachments/`. Cursors, the lock, the GitHub reading and settings stay on each machine.
+The shared folder holds `events/`, `devices/` (each machine's paths, version and last sign of life), `runs/`, `listeners/` and `attachments/`. Cursors, the lock, the GitHub reading and settings stay on each machine.
 
 **Sync adapters** are how parawatch asks the sync tool how it is doing, for `parawatch sync`, `doctor` and the app's settings. Pick one with `--adapter` (or `"sync": { "adapter": … }` in `config.json`):
 

package/dist/bin/cli.js

@@ -2,14 +2,14 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import { Command } from "commander";
-import { UserError, addProject, answerCard, beatRun, claimSession, closeCard, commentCard, consumerName, editCard, endRun, linkPr, listeners, listenersFor, noteRun, openCard, prEvent, findCard, readInbox, readState, removeProject, startListening, startRun, unlinkPr, waitInbox, } from "../core/ops.js";
+import { UserError, addProject, answerCard, beatRun, claimSession, closeCard, commentCard, inboxScope, editCard, endRun, linkPr, listeners, listenersFor, noteRun, openCard, prEvent, findCard, readInbox, readState, removeProject, startListening, startRun, unlinkPr, waitInbox, } from "../core/ops.js";
 import { githubConfig, readCache, resolvePrRef, syncGithub, prViews } from "../core/github.js";
 import { digest, digestText, localDate } from "../core/digest.js";
 import { everywhere, readEvents } from "../core/store.js";
 import { followEvents } from "../core/follow.js";
 import { adapterNames, setRoot, setupSync, syncAdapter, syncStatus, touchDevice } from "../core/sync.js";
 import { syncText } from "../core/format.js";
-import { collectRuns } from "../core/runs.js";
+import { collectRuns, shareRunsDue } from "../core/runs.js";
 import { askRows, cardDetail, cardLine, cardRows, inboxLine, prRows, runsTree, view } from "../core/format.js";
 import { hookContext, notify, removeInstructions, writeInstructions } from "../core/integrate.js";
 import { installSkill, skillSource, skillTargets, uninstallSkill } from "../core/skill.js";
@@ -204,21 +204,30 @@ program
 // ------------------------------------------------------------------ inbox
 function inboxOptions(c) {
     return c
-        .option("-p, --project <name>", "only answers for this project")
+        .option("-p, --project <name>", "everything in this project, whoever owns it (for a lead)")
         .option("--card <id>", "only answers to this card")
-        .option("--as <consumer>", "cursor name (defaults to the project)")
+        .option("--as <consumer>", "cursor name (defaults to the session, or the project with -p)")
         .option("--json", "JSON output");
 }
-inboxOptions(program.command("wait").description("block until the human answers, print the answers and exit"))
+inboxOptions(program
+    .command("wait")
+    .description("block until the human answers or a linked pull request has news, print it and exit. In an agent session it reads that session's own cards and pull requests"))
     .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();
+    const session = currentSession();
+    const { consumer, filter } = inboxScope(o, session);
+    startListening({ consumer, project: filter.project, card: filter.card, session, ...(filter.session ? { scope: "session" } : {}) });
+    // while waiting, keep GitHub fresh so news on linked pull requests wakes this wait, and tell
+    // the other machines what runs here
+    const tick = () => {
+        void refreshGithub();
+        if (shareRunsDue())
+            collectRuns(readState(), { sinceHours: 6 });
+    };
     tick();
     const timer = setInterval(tick, 60_000);
     timer.unref();
-    const items = await waitInbox(consumerName(o), { project: o.project, card: o.card }, o.timeout * 1000);
+    const items = await waitInbox(consumer, filter, o.timeout * 1000);
     clearInterval(timer);
     if (!items.length) {
         process.exitCode = 2;
@@ -232,7 +241,8 @@ inboxOptions(program.command("wait").description("block until the human answers,
 inboxOptions(program.command("inbox").description("print unhandled answers without waiting"))
     .option("--peek", "do not mark them as seen")
     .action((o) => {
-    const items = readInbox(consumerName(o), { project: o.project, card: o.card }, !o.peek);
+    const { consumer, filter } = inboxScope(o, currentSession());
+    const items = readInbox(consumer, filter, !o.peek);
     if (o.json)
         print({ v: SCHEMA_VERSION, items });
     else if (items.length)
@@ -415,8 +425,9 @@ program
     }
     if (answered.length) {
         const notes = {};
+        // the snapshot already marked the cards whose session has ended
         for (const c of answered)
-            if (!listenersFor(c, ls).length)
+            if (!listenersFor(c, ls, () => false).length)
                 notes[c.id] = "no agent waiting";
         out.push("", head("ANSWERED, WAITING FOR THE AGENT", answered.length));
         out.push(...cardRows(answered, v, now, "  ", notes));

package/dist/core/desktop.js

@@ -2,7 +2,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { parsePrRef } from "./github.js";
-import { sessionTitle, UserError } from "./ops.js";
+import { UserError } from "./errors.js";
+import { sessionTitle } from "./state.js";
 /**
  * Where the Claude desktop app keeps its Code sessions: one JSON file per session, named
  * `local_<id>.json`, holding the CLI session id the app runs (`cliSessionId`).
@@ -27,36 +28,86 @@ function* sessionFiles(dir, depth = 0) {
             yield p;
     }
 }
-/** The desktop app session running a CLI session (full id or a prefix of 6+ characters). */
-export function findDesktopSession(cliSession, dir = desktopSessionsDir()) {
-    if (cliSession.length < 6)
-        return undefined;
-    let best;
+/** Session files read before, by path; a file is read again only when it changes. */
+const readCache = new Map();
+/** Every desktop app session in the folder, read once per change of its file. */
+function desktopSessions(dir) {
+    const out = [];
     for (const file of sessionFiles(dir)) {
-        let d;
+        let mtimeMs;
         try {
-            d = JSON.parse(fs.readFileSync(file, "utf8"));
+            mtimeMs = fs.statSync(file).mtimeMs;
         }
         catch {
             continue;
         }
-        const ids = [d.cliSessionId, d.lastAssistantCliSessionId].filter((x) => typeof x === "string");
+        let hit = readCache.get(file);
+        if (!hit || hit.mtimeMs !== mtimeMs) {
+            hit = { mtimeMs, session: readSessionFile(file) };
+            readCache.set(file, hit);
+        }
+        if (hit.session)
+            out.push(hit.session);
+    }
+    return out;
+}
+function readSessionFile(file) {
+    let d;
+    try {
+        d = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    const ids = [d.cliSessionId, d.lastAssistantCliSessionId].filter((x) => typeof x === "string");
+    if (!ids.length)
+        return undefined;
+    return {
+        id: typeof d.sessionId === "string" ? d.sessionId : path.basename(file, ".json"),
+        cliSessionId: ids[0],
+        ids,
+        title: typeof d.title === "string" ? d.title : undefined,
+        cwd: typeof d.cwd === "string" ? d.cwd : undefined,
+        archived: d.isArchived === true,
+        lastActivityAt: typeof d.lastActivityAt === "number" ? d.lastActivityAt : 0,
+    };
+}
+/** The desktop app session running a CLI session (full id or a prefix of 6+ characters). */
+export function findDesktopSession(cliSession, dir = desktopSessionsDir()) {
+    if (cliSession.length < 6)
+        return undefined;
+    let best;
+    for (const { ids, ...s } of desktopSessions(dir)) {
         if (!ids.some((x) => x.startsWith(cliSession)))
             continue;
-        const s = {
-            id: typeof d.sessionId === "string" ? d.sessionId : path.basename(file, ".json"),
-            cliSessionId: ids[0],
-            title: typeof d.title === "string" ? d.title : undefined,
-            cwd: typeof d.cwd === "string" ? d.cwd : undefined,
-            archived: d.isArchived === true,
-            lastActivityAt: typeof d.lastActivityAt === "number" ? d.lastActivityAt : 0,
-        };
         // prefer a live session, then the most recent one
         if (!best || (best.archived && !s.archived) || (best.archived === s.archived && s.lastActivityAt > best.lastActivityAt))
             best = s;
     }
     return best;
 }
+/**
+ * The CLI sessions the human archived in the Claude desktop app, as a test for a session id
+ * (full or a prefix of 6+ characters). Such a session never takes another turn, however its log
+ * ends. A CLI session that a live desktop session also runs is not archived.
+ */
+export function archivedSessions(dir = desktopSessionsDir()) {
+    const archived = new Set();
+    const live = new Set();
+    for (const s of desktopSessions(dir))
+        for (const id of s.ids)
+            (s.archived ? archived : live).add(id);
+    for (const id of live)
+        archived.delete(id);
+    const ids = [...archived];
+    return (session) => {
+        if (!session || session.length < 6)
+            return false;
+        if (archived.has(session))
+            return true;
+        return ids.some((id) => id.startsWith(session));
+    };
+}
 /** A link that opens the session in the Claude desktop app. */
 export function desktopSessionUrl(s) {
     return `claude://code/continue?session=${encodeURIComponent(s.id)}&source=parawatch`;

package/dist/core/format.js

@@ -321,6 +321,9 @@ export function runsTree(runs, v = PLAIN, now = Date.now(), indent = "") {
     const all = blocks.flatMap((b) => b.rows);
     const nameW = Math.min(Math.max(24, Math.floor(v.width * 0.4)), Math.max(12, ...all.map((row) => textWidth(row.prefix) + 2 + textWidth(row.run?.title ?? ""))));
     const wideW = v.wide ? 24 : 0;
+    // the machine a run is on gets a column of its own, so a long title cannot cut it off
+    const devW = Math.min(12, Math.max(0, ...all.map((row) => (row.run?.device ? textWidth(row.run.device) : 0))));
+    const devCol = devW ? devW + 2 : 0;
     const out = [];
     for (const { name, rows } of blocks) {
         if (name === OTHER)
@@ -342,12 +345,13 @@ export function runsTree(runs, v = PLAIN, now = Date.now(), indent = "") {
             const label = r.title + (r.repeats ? ` ×${r.repeats + 1}` : "") + (r.prs?.length ? ` (${r.prs.length} PR)` : "");
             const title = paint(v, pad(fit(label, room), room), ...titlePaint);
             const age = paint(v, ago(r.lastActivity, now).padStart(4), "dim");
+            const dev = devW ? "  " + paint(v, pad(fit(r.device ?? "", devW), devW), "cyan") : "";
             const src = (r.projectSource && SOURCE_NOTE[r.projectSource]) || "";
             const wide = v.wide ? "  " + paint(v, pad(fit(`${r.kind === "subagent" ? r.model ?? "subagent" : r.runtime} ${r.id.slice(0, 8)}${src ? " " + src : ""}`, wideW - 2), wideW - 2), "dim") : "";
-            const restW = v.width - nameW - 2 - 4 - wideW - 2;
+            const restW = v.width - nameW - 2 - 4 - devCol - wideW - 2;
             const whatPaint = r.error || r.state === "stalled" || r.state === "failed" || r.asks?.blocked ? ["red"] : r.asks ? ["yellow"] : ended ? ["dim"] : [];
             const what = restW >= 8 ? "  " + paint(v, fit(whatText(r), restW), ...whatPaint) : "";
-            out.push(`${lead}${mark} ${title}  ${age}${wide}${what}`.trimEnd());
+            out.push(`${lead}${mark} ${title}  ${age}${dev}${wide}${what}`.trimEnd());
         }
     }
     return out.join("\n");

package/dist/core/github.js

@@ -7,7 +7,7 @@ import { execFile, execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { UserError } from "./ops.js";
-import { appendLocked, homeDir, withLock } from "./store.js";
+import { appendLocked, deviceName, homeDir, withLock } from "./store.js";
 export const DEFAULT_STALL_HOURS = {
     review: 24,
     "no reviewer": 4,
@@ -307,6 +307,23 @@ export function nextCache(prev, fresh, hosts, at) {
             delete since[k];
     return { cache: { fetchedAt: at, hosts, prs, since }, events };
 }
+/**
+ * Drop news another machine already reported. This machine's reading spans from its previous
+ * reading (`since`) to now; the same change on the same PR that another machine wrote in that
+ * span is the one this machine just noticed, maybe long after. A machine that reads GitHub for
+ * the first time in hours would otherwise tell every agent again what they already handled.
+ */
+export function dropReported(fresh, log, since, me = deviceName()) {
+    if (!since)
+        return fresh;
+    const seen = new Set();
+    for (const e of log)
+        if (e.type === "pr.change" && e.dev && e.dev !== me && e.ts >= since)
+            seen.add(`${e.pr.key}|${e.change}|${e.by ?? ""}`);
+    if (!seen.size)
+        return fresh;
+    return fresh.filter((b) => b.type !== "pr.change" || !seen.has(`${b.pr.key}|${b.change}|${b.by ?? ""}`));
+}
 // ------------------------------------------------------------------ sync
 function fetchingPath() {
     return path.join(homeDir(), "github.fetching");
@@ -386,7 +403,7 @@ export async function syncGithub(opts) {
             const { cache, events } = nextCache(latest, fresh, hosts, started);
             if (errors.length)
                 cache.error = errors.join("; ");
-            appendLocked(() => events);
+            appendLocked((log) => dropReported(events, log, latest.fetchedAt));
             writeCache(cache);
             return cache;
         });

package/dist/core/integrate.js

@@ -1,9 +1,10 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { readInbox, inboxFrom, readState } from "./ops.js";
+import { furthest, inboxFrom, readInbox, readState, sameSession, sessionConsumer } from "./ops.js";
 import { homeDir, readCursor, readEvents } from "./store.js";
 import { inboxLine } from "./format.js";
+import { insidePath } from "./paths.js";
 export const BEGIN = "<!-- parawatch:begin -->";
 export const END = "<!-- parawatch:end -->";
 export function instructions(project) {
@@ -23,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 --project ${p}\`. It prints the human's answers and pull request news and exits; act on them, \`parawatch close <card> --note "what you did"\`, then arm it again.
+- 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}\`.
 - 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}`;
@@ -97,23 +98,28 @@ export function instructionState(file) {
 export function hookContext(input, project) {
     const events = readEvents();
     const state = readState(events);
+    const session = input.session_id;
     let name = project;
-    if (!name && input.session_id)
-        name = state.claims.find((c) => input.session_id.startsWith(c.session))?.project;
+    if (!name && session)
+        name = state.claims.find((c) => sameSession(session, c.session))?.project;
     if (!name && input.cwd) {
         for (const p of state.projects.values())
-            if (p.paths.some((x) => input.cwd === x || input.cwd.startsWith(x + "/")))
+            if (p.paths.some((x) => insidePath(input.cwd, x)))
                 name = p.name;
     }
-    if (!name)
+    if (!name && !session)
         return undefined;
-    const items = inboxFrom(events, readCursor(name), { project: name }, state);
+    // A session reads its own news with its own cursor; one still waiting on its project moves the
+    // project's cursor instead, so whichever is further says what it has handled.
+    const items = session
+        ? inboxFrom(events, furthest(readCursor(sessionConsumer(session)), name ? readCursor(name) : {}), { session, project: name }, state)
+        : inboxFrom(events, readCursor(name), { project: name }, state);
     if (!items.length)
         return undefined;
     const cards = items.filter((i) => i.kind !== "pr").length;
     const prs = items.length - cards;
     const what = [cards ? `${cards} answer(s) on cards` : "", prs ? `${prs} pull request update(s)` : ""].filter(Boolean).join(" and ");
-    return [`Parawatch: ${what} for ${name} that you have not handled yet.`, ...items.map(inboxLine), cards ? `Act on them, then \`parawatch close <card>\`.` : `Act on them.`].join("\n");
+    return [`Parawatch: ${what}${name ? ` for ${name}` : ""} that you have not handled yet.`, ...items.map(inboxLine), cards ? `Act on them, then \`parawatch close <card>\`.` : `Act on them.`].join("\n");
 }
 /** Best-effort desktop notification. Never throws, never blocks. */
 /** The desktop app writes its pid here while it runs, so the CLI leaves notifications to it. */

package/dist/core/ops.js

@@ -2,10 +2,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { UserError } from "./errors.js";
 import { advance, appendEvent, deviceName, eventsDir, homeDir, isAfter, readCursor, readEvents, sharedDir, writeCursor } from "./store.js";
-import { findId, fold, nextId } from "./state.js";
+import { archivedSessions } from "./desktop.js";
+import { findId, fold, nextId, sessionTitle } from "./state.js";
 import { pathMap } from "./sync.js";
 import { CARD_KINDS, HUMAN, PR_CHANGES } from "./types.js";
-export { UserError };
+export { UserError, sessionTitle };
 /** Current state, with other machines' paths made local. */
 export function readState(events = readEvents()) {
     return fold(events, pathMap());
@@ -18,9 +19,21 @@ function cleanList(xs) {
     const out = (xs ?? []).map((x) => x.trim()).filter(Boolean);
     return out.length ? out : undefined;
 }
+/**
+ * An attachment or a thing to open, as stored. A URL, and a path that is absolute on either
+ * system (`/Users/...`, `C:\...`, `\\server\share`), is kept as written: it may name a place on
+ * another machine, and resolving it here would root it on this one (`E:\Users\...` on Windows,
+ * `<cwd>/C:\...` on a Mac). Only a relative path is resolved.
+ */
+export function storedPath(x) {
+    if (/^[a-z]+:\/\//i.test(x))
+        return x;
+    if (path.posix.isAbsolute(x) || path.win32.isAbsolute(x))
+        return x;
+    return path.resolve(x);
+}
 function absPaths(xs) {
-    // attachments and things to open are kept as given when they look like URLs
-    return cleanList(xs)?.map((x) => (/^[a-z]+:\/\//i.test(x) ? x : path.resolve(x)));
+    return cleanList(xs)?.map(storedPath);
 }
 export function addProject(name, paths) {
     if (!/^[A-Za-z0-9._-]+$/.test(name))
@@ -57,13 +70,6 @@ export function parseWhen(s) {
         throw new UserError(`"${s}" is not a date (use YYYY-MM-DD)`);
     return d.toISOString();
 }
-/** The claimed name of a session (claims may hold an id prefix). */
-export function sessionTitle(claims, session) {
-    if (!session)
-        return undefined;
-    const c = claims.find((x) => session.startsWith(x.session) || x.session.startsWith(session));
-    return c?.title;
-}
 function checkKind(kind) {
     if (!CARD_KINDS.includes(kind))
         throw new UserError(`kind must be one of ${CARD_KINDS.join(", ")}`);
@@ -273,6 +279,38 @@ export function prEvent(pr, change, opts = {}) {
         throw new UserError(`change must be one of ${PR_CHANGES.join(", ")}`);
     appendEvent(() => ({ type: "pr.change", pr, change: change, by: opts.by, text: opts.text?.trim() || undefined, title: opts.title, source: "external" }));
 }
+/** Whether two session ids name the same session. A claim or a link may hold a short prefix. */
+export function sameSession(a, b) {
+    return !!a && !!b && (a.startsWith(b) || b.startsWith(a));
+}
+/**
+ * Whether a session has ended: it said so with `claim --done`, or the human archived it in the
+ * Claude desktop app. Cards and pull requests it owned then belong to its project, so an answer
+ * still reaches a session waiting there. The desktop app is read only when asked about a session
+ * that has not claimed done.
+ */
+export function endedSessions(state, isArchived) {
+    let archived = isArchived;
+    return (session) => {
+        const claim = state.claims.find((c) => sameSession(c.session, session));
+        if (claim?.done)
+            return true;
+        archived ??= archivedSessions();
+        return archived(session);
+    };
+}
+/** Whether something owned by `owner` in `project` is for a reader with this filter. */
+function inScope(owner, project, f, ended) {
+    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;
+    }
+    return !f.project || project === f.project;
+}
 /** Two machines that both read GitHub report the same change; the later report is an echo. */
 const ECHO_MS = 30 * 60_000;
 /**
@@ -285,6 +323,7 @@ export function inboxFrom(events, after, filter, state = readState(events)) {
     const out = [];
     const reported = new Map();
     const answerNo = new Map();
+    const ended = filter.ended ?? endedSessions(state);
     for (const ev of events) {
         if (ev.type === "pr.change") {
             const k = `${ev.pr.key}|${ev.change}|${ev.text ?? ""}`;
@@ -296,7 +335,7 @@ 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 || (filter.project && link.project !== filter.project))
+            if (!link || filter.card || !inScope(link.session, link.project, filter, ended))
                 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;
@@ -316,7 +355,7 @@ export function inboxFrom(events, after, filter, state = readState(events)) {
         const card = state.cards.get(ev.card);
         if (!card || card.status === "closed")
             continue;
-        if (filter.project && card.project !== filter.project)
+        if (!inScope(card.session, card.project, filter, ended))
             continue;
         if (filter.card && card.id !== filter.card)
             continue;
@@ -432,13 +471,58 @@ export function listeners(now = Date.now()) {
     }
     return out;
 }
-/** The waits an answer to this card would wake right now. */
-export function listenersFor(card, ls) {
-    return ls.filter((l) => (l.card ? l.card === card.id : !l.project || l.project === card.project));
+/**
+ * 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.
+ */
+export function listenersFor(card, ls, ended) {
+    let gone = card.ownerEnded;
+    const ownerGone = () => (gone ??= !!card.session && (ended ?? endedSessions(readState()))(card.session));
+    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
+            : !l.project || l.project === card.project);
 }
 export function consumerName(opts) {
     return opts.as || opts.project || (opts.card ? `card-${opts.card}` : "default");
 }
+/** The cursor a session reads with when it waits for its own news. */
+export function sessionConsumer(session) {
+    return `session-${session.replace(/[^A-Za-z0-9._-]/g, "_")}`;
+}
+/** Per device, the further of two positions. */
+export function furthest(a, b) {
+    const out = { ...a };
+    for (const [d, seq] of Object.entries(b))
+        if (seq > (out[d] ?? 0))
+            out[d] = seq;
+    return out;
+}
+/**
+ * What a wait or an inbox reads. `--card` and `--project` read what they name, with a cursor of
+ * 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.
+ */
+export function inboxScope(opts, session) {
+    if (opts.card || opts.project || !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);
+    // 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) {
+        const from = readCursor(claim.project);
+        if (Object.keys(from).length)
+            writeCursor(consumer, from);
+    }
+    return { consumer, filter: { session, project: claim?.project } };
+}
 export function readInbox(consumer, filter, move) {
     const events = readEvents();
     const pos = readCursor(consumer);

package/dist/core/paths.js

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import path from "node:path";
+const WINDOWS = process.platform === "win32";
+/**
+ * The real spelling of a path, for comparing: symlinks and Windows short names (`RUNNER~1`)
+ * resolved, through the deepest part that exists. On Windows also lower case with `\` only, since
+ * the file system ignores case and logs mix `/` and `\`.
+ */
+export function canonicalPath(p) {
+    let rest = "";
+    let head = path.resolve(p);
+    let out = head;
+    for (;;) {
+        try {
+            out = path.join(fs.realpathSync.native(head), rest);
+            break;
+        }
+        catch {
+            const up = path.dirname(head);
+            if (up === head)
+                break;
+            rest = path.join(path.basename(head), rest);
+            head = up;
+        }
+    }
+    return WINDOWS ? out.replace(/\//g, "\\").toLowerCase() : out;
+}
+function within(child, parent) {
+    const rel = path.relative(parent, child);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+/**
+ * Whether `child` is `parent` or inside it, as written or once both are resolved
+ * (`canonicalPath`). Pass a canonical form when it is already known, to skip the file system.
+ */
+export function insidePath(child, parent, canon) {
+    if (within(path.resolve(child), path.resolve(parent)))
+        return true;
+    return within(canon?.child ?? canonicalPath(child), canon?.parent ?? canonicalPath(parent));
+}
+/** Whether two paths name the same folder. */
+export function samePath(a, b) {
+    return path.resolve(a) === path.resolve(b) || canonicalPath(a) === canonicalPath(b);
+}
+/**
+ * Whether a text (a prompt) names this folder: as written, or with `\` and `/` swapped, and on
+ * Windows ignoring case.
+ */
+export function namesPath(text, dir) {
+    if (text.includes(dir))
+        return true;
+    const hay = WINDOWS ? text.toLowerCase() : text;
+    const d = WINDOWS ? dir.toLowerCase() : dir;
+    return hay.includes(d.replace(/\\/g, "/")) || hay.includes(d.replace(/\//g, "\\"));
+}
+//# sourceMappingURL=paths.js.map

package/dist/core/runs.js

@@ -3,6 +3,9 @@ import fs from "node:fs";
 import path from "node:path";
 import { scanAll } from "../adapters/index.js";
 import { ACTIVITY_MINUTES, activeMinutes } from "../adapters/jsonl.js";
+import { archivedSessions } from "./desktop.js";
+import { canonicalPath, insidePath, namesPath, samePath } from "./paths.js";
+import { deviceName, sharedDir } from "./store.js";
 /** All checkouts of a project path: the path itself plus its git worktrees. */
 function rootsOf(p, cache) {
     const hit = cache.get(p);
@@ -13,7 +16,7 @@ function rootsOf(p, cache) {
         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)) {
+        if (!samePath(top, p)) {
             cache.set(p, roots);
             return roots;
         }
@@ -32,23 +35,23 @@ function rootsOf(p, cache) {
     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)) }));
+    return projects.map((p) => ({
+        project: p.name,
+        roots: p.paths.flatMap((x) => rootsOf(x, cache)).map((r) => ({ path: r, canonical: canonicalPath(r) })),
+    }));
 }
 /** The project whose checkout holds this directory; the deepest root wins. */
 function projectForCwd(cwd, ms) {
     if (!cwd)
         return undefined;
+    const child = canonicalPath(cwd);
     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 };
+            if (insidePath(cwd, r.path, { child, parent: r.canonical }) && (!best || r.path.length > best.depth))
+                best = { project: m.project, depth: r.path.length };
         }
     }
     return best?.project;
@@ -60,7 +63,7 @@ function projectForPrompt(prompt, ms) {
     const hits = new Set();
     for (const m of ms) {
         for (const r of m.roots)
-            if (prompt.includes(r))
+            if (namesPath(prompt, r.path))
                 hits.add(m.project);
     }
     return hits.size === 1 ? [...hits][0] : undefined;
@@ -96,27 +99,31 @@ function claimFor(id, state) {
  * 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.
  */
+function applyClaim(r, claim) {
+    r.project = claim.project;
+    r.projectSource = "claim";
+    r.task = claim.task ?? r.task;
+    r.role = claim.role ?? r.role;
+    if (claim.title)
+        r.title = claim.title;
+    if (claim.kind === "scheduled")
+        r.scheduled = true;
+    // done until someone writes to the session again
+    if (claim.done && claim.at && (!r.lastPromptAt || r.lastPromptAt < claim.at)) {
+        r.done = claim.done;
+        // a session that says it is finished is not stuck, even if its log ends mid-turn
+        if (r.state === "idle" || r.state === "stalled")
+            r.state = "done";
+        r.asks = undefined;
+    }
+}
 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 = claimFor(r.id, state);
         if (claim) {
-            r.project = claim.project;
-            r.projectSource = "claim";
-            r.task = claim.task ?? r.task;
-            r.role = claim.role ?? r.role;
-            if (claim.title)
-                r.title = claim.title;
-            if (claim.kind === "scheduled")
-                r.scheduled = true;
-            // done until someone writes to the session again
-            if (claim.done && claim.at && (!r.lastPromptAt || r.lastPromptAt < claim.at)) {
-                r.done = claim.done;
-                if (r.state === "idle")
-                    r.state = "done";
-                r.asks = undefined;
-            }
+            applyClaim(r, claim);
             continue;
         }
         const here = projectForCwd(r.cwd, ms);
@@ -154,6 +161,29 @@ export function attribute(runs, state) {
     }
     return runs;
 }
+/**
+ * A Claude Code session the human archived in the Claude desktop app has ended, even when its log
+ * stops mid-turn (archived while a tool ran, say), and so have its subagents.
+ */
+export function endArchived(runs, isArchived) {
+    const ended = new Set();
+    for (const r of runs) {
+        if (r.runtime !== "claude-code" || r.kind !== "session" || r.device || !isArchived(r.id))
+            continue;
+        ended.add(r.id);
+    }
+    for (const r of runs) {
+        if (!ended.has(r.id) && !(r.parent && ended.has(r.parent)))
+            continue;
+        if (r.state === "failed")
+            continue;
+        r.state = "done";
+        if (ended.has(r.id))
+            r.done ??= "archived in the Claude app";
+        r.asks = undefined;
+    }
+    return runs;
+}
 /**
  * Fold repeated runs of a scheduled task into the newest one, with a count. Runs claimed as
  * scheduled group by project and task; unclaimed top-level sessions group by an identical first
@@ -247,6 +277,92 @@ export function declaredRuns(state, now = Date.now()) {
         };
     });
 }
+// ---------------------------------------------------------------- other machines
+/** How often a machine rewrites its runs for the others, and when its summary counts as gone. */
+const SHARE_EVERY_MS = 30_000;
+export const SHARED_RUNS_GONE_MS = 15 * 60_000;
+const SHARED_RUNS_FILE = /^([a-z0-9][a-z0-9-]{0,31})\.json$/;
+function sharedRunsDir() {
+    const s = sharedDir();
+    return s ? path.join(s, "runs") : undefined;
+}
+/**
+ * Write the runs read from this machine's agent logs where the other machines read them, at most
+ * every half minute. The logs themselves stay here; only the summary travels.
+ */
+export function shareRuns(runs, now = Date.now()) {
+    if (!shareRunsDue(now))
+        return;
+    const dir = sharedRunsDir();
+    const me = deviceName();
+    const file = path.join(dir, `${me}.json`);
+    // the folders it edited are paths on this machine, and only guide attribution here
+    const slim = runs.map(({ touched: _t, ...r }) => ({ ...r, prompt: r.prompt?.slice(0, 300) }));
+    const body = { v: 1, device: me, at: new Date(now).toISOString(), runs: slim };
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        const tmp = path.join(dir, `.${me}.${process.pid}.tmp`);
+        fs.writeFileSync(tmp, JSON.stringify(body) + "\n");
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        // the folder may be busy syncing; the next reading writes it again
+    }
+}
+/** Whether this machine's summary for the others is due (a shared folder, and none written lately). */
+export function shareRunsDue(now = Date.now()) {
+    const dir = sharedRunsDir();
+    if (!dir)
+        return false;
+    try {
+        return now - fs.statSync(path.join(dir, `${deviceName()}.json`)).mtimeMs >= SHARE_EVERY_MS;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Runs other machines shared, as they last wrote them, marked with the machine. A machine that
+ * has not written for a while is left out: its agents may be long gone. Claims made since are
+ * applied here, and the activity chart slides by the summary's age.
+ */
+export function otherRuns(state, now = Date.now()) {
+    const dir = sharedRunsDir();
+    if (!dir)
+        return [];
+    const me = deviceName();
+    let names = [];
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const n of names.sort()) {
+        const m = SHARED_RUNS_FILE.exec(n);
+        if (!m || m[1] === me)
+            continue;
+        try {
+            const s = JSON.parse(fs.readFileSync(path.join(dir, n), "utf8"));
+            const at = Date.parse(s.at);
+            if (!Number.isFinite(at) || now - at > SHARED_RUNS_GONE_MS || !Array.isArray(s.runs))
+                continue;
+            const shift = Math.max(0, Math.floor((now - at) / 60_000));
+            for (const r of s.runs) {
+                const run = { ...r, device: m[1], activity: r.activity?.map((x) => x + shift).filter((x) => x < ACTIVITY_MINUTES) };
+                const claim = claimFor(run.id, state);
+                if (claim)
+                    applyClaim(run, claim);
+                out.push(run);
+            }
+        }
+        catch {
+            // half synced; read it next time
+        }
+    }
+    return out;
+}
 const ENDED = new Set(["done", "idle", "failed"]);
 const RECENT_END_MS = 30 * 60_000;
 const OLD_STALL_MS = 3 * 3_600_000;
@@ -254,7 +370,11 @@ 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);
+    let runs = endArchived(attribute(scanAll({ sinceMs, now }, q.runtimes), state), archivedSessions()).filter(recent);
+    // a narrower reading (one runtime) would hide the rest from the other machines
+    if (!q.runtimes)
+        shareRuns(runs, now);
+    runs.push(...otherRuns(state, now).filter(recent));
     runs.push(...declaredRuns(state, now).filter(recent));
     attachPrs(runs, state);
     if (q.project)

package/dist/core/snapshot.js

@@ -1,5 +1,5 @@
 import { prViews, keyOf, parsePrRef, readCache, githubConfig } from "./github.js";
-import { linkPr, listeners, readState } from "./ops.js";
+import { endedSessions, linkPr, listeners, readState } from "./ops.js";
 import { collectRuns } from "./runs.js";
 import { deviceName, eventFiles, sharedDir } from "./store.js";
 import { SCHEMA_VERSION } from "./types.js";
@@ -15,7 +15,8 @@ export function snapshot(opts = {}) {
     if (linkCreatedPrs(runs, state))
         state = readState();
     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 ended = endedSessions(state);
+    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);
     quietAnsweredAsks(runs, all);
     const cache = readCache();
     const enabled = githubConfig().enabled && (cache.hosts === undefined ? false : cache.hosts.length > 0);

package/dist/core/state.js

@@ -1,3 +1,10 @@
+/** The claimed name of a session (claims may hold an id prefix). */
+export function sessionTitle(claims, session) {
+    if (!session)
+        return undefined;
+    const c = claims.find((x) => session.startsWith(x.session) || x.session.startsWith(session));
+    return c?.title;
+}
 function mapAll(xs, map, from) {
     return xs && map ? xs.map((x) => map(x, from)) : xs;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parawatch",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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

@@ -74,10 +74,12 @@ News from somewhere GitHub does not show (a merge bot, a ticket system) can be r
 
 ## 4. Waiting for the answer
 
-Right after opening cards or linking a pull request, keep exactly one wait armed for your project:
+Right after opening cards or linking a pull request, keep exactly one wait armed:
 
-- **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.
+- **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).
 
 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.
 
@@ -119,6 +121,7 @@ The session then shows as done, not as idle, and the line goes into the human's
 
 ## 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.
 - 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`.