parawatch 0.3.3 → 0.3.5

package/README.md

@@ -121,6 +121,8 @@ 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 run hide <id>         # hide a run (6+ characters of its id) until it does something new; `runs --all` still shows it
+parawatch run unhide <id>
 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)
@@ -231,7 +233,7 @@ 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 (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.
+States: `●` working, `◐` waiting, `○` idle, `✓` done (a finished subagent, or a session that claimed `--done`), `!` stalled (quiet longer than its tool's timeout allows, counting a waited-on background job's output file as activity, or a declared job past its heartbeat), `✗` failed. A Claude Code run whose turn ended while a background shell job is still running (no completion notice or stop yet) counts as working, not idle or done.
 
 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`).
 
@@ -257,6 +259,8 @@ It reads only, reads only files touched since `sinceMs`, and reads only the head
 | [`apps/desktop`](apps/desktop/README.md) | The desktop app. Reads and writes the store directly, so it works without the CLI on `PATH`. |
 | [`packages/panel`](packages/panel) | The panel both of them show, as plain DOM, with a harness page for working on it. |
 
+The desktop app shows each service's own site icon beside runs and pull requests (Claude Code, Codex, GitHub). It fetches the icon from that service's site, like a browser's favicon, and caches it in the app's data folder for a week. Turn it off in Settings and nothing is fetched. The names and icons belong to their owners, and parawatch is not affiliated with them.
+
 Anything else can build on the same two commands:
 
 ```

package/dist/adapters/claudeCode.js

@@ -32,6 +32,8 @@ function toolSummary(b) {
 function promptText(rec) {
     if (rec.type !== "user" || rec.isMeta === true)
         return undefined;
+    if (isObj(rec.origin) && rec.origin.kind === "task-notification")
+        return undefined;
     const bs = blocks(rec);
     if (bs.some((b) => b.type === "tool_result"))
         return undefined;
@@ -40,6 +42,68 @@ function promptText(rec) {
         return undefined;
     return text;
 }
+const JOB_STARTED = /(?:running in background with ID|moved to the background \(ID): ([\w-]+)\)?[^\n]{0,80}?\.\s*Output is being written to: (.+?)\.\s+You will be notified/s;
+const JOB_STARTED_NO_PATH = /(?:running in background with ID|moved to the background \(ID): ([\w-]+)/;
+const NOTICE = /<task-notification>([\s\S]*?)<\/task-notification>/g;
+/** `parawatch wait` / `parawatch watch` at a command start: it blocks for the human and prints nothing. */
+const HUMAN_WAIT = /(?:^|&&|;|\||\bnpx\s+)\s*(?:parawatch\s+(?:wait|watch)\b|node\s+\S*cli\.js\s+(?:wait|watch)\b)/;
+const STOP_TOOLS = new Set(["TaskStop", "KillShell", "KillBash"]);
+function tag(xml, name) {
+    return new RegExp(`<${name}>([\\s\\S]*?)</${name}>`).exec(xml)?.[1]?.trim();
+}
+/** Text a record carries that may hold a task notice: a user message, a queued command, a queue entry. */
+function noticeText(rec) {
+    const parts = [];
+    for (const b of blocks(rec))
+        if (b.type === "text" && b.text)
+            parts.push(b.text);
+    const att = rec.attachment;
+    if (isObj(att) && typeof att.prompt === "string")
+        parts.push(att.prompt);
+    if (rec.type === "queue-operation" && typeof rec.content === "string")
+        parts.push(rec.content);
+    return parts.join("\n");
+}
+/**
+ * Background shell jobs a transcript started and has not seen end. A job ends with a completion
+ * notice (a status other than running) or a stop tool call. A job that started before the tail
+ * began is unknown and not counted.
+ */
+function pendingJobs(recs) {
+    const jobs = new Map();
+    const commands = new Map();
+    const ended = new Set();
+    for (const r of recs) {
+        if (!isObj(r))
+            continue;
+        for (const b of blocks(r)) {
+            if (b.type === "tool_use") {
+                if (b.id && b.name === "Bash")
+                    commands.set(b.id, str(b.input?.command) ?? "");
+                if (STOP_TOOLS.has(String(b.name))) {
+                    const id = str(b.input?.task_id) || str(b.input?.shell_id) || str(b.input?.bash_id);
+                    if (id)
+                        ended.add(id);
+                }
+            }
+            else if (b.type === "tool_result") {
+                const text = resultText(b);
+                const m = JOB_STARTED.exec(text);
+                const id = m?.[1] ?? JOB_STARTED_NO_PATH.exec(text)?.[1];
+                if (id)
+                    jobs.set(id, { id, output: m?.[2]?.trim(), command: b.tool_use_id ? commands.get(b.tool_use_id) : undefined });
+            }
+        }
+        for (const n of noticeText(r).matchAll(NOTICE)) {
+            const id = tag(n[1], "task-id");
+            const status = tag(n[1], "status");
+            // monitor events carry no status and do not end a job
+            if (id && status && status.toLowerCase() !== "running")
+                ended.add(id);
+        }
+    }
+    return [...jobs.values()].filter((j) => !ended.has(j.id) && !(j.command && HUMAN_WAIT.test(j.command.trim())));
+}
 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;
@@ -137,6 +201,7 @@ export function readClaudeTail(recs, kind) {
     }
     if (!lastConv)
         return out;
+    const jobs = pendingJobs(recs);
     const bs = blocks(lastConv);
     if (lastConv.type === "assistant") {
         const tool = [...bs].reverse().find((b) => b.type === "tool_use");
@@ -147,6 +212,15 @@ export function readClaudeTail(recs, kind) {
             if (typeof t === "number")
                 out.pendingTimeoutMs = t;
         }
+        else if (jobs.length && bs.some((b) => b.type === "text" && b.text?.trim())) {
+            // the turn ended while a background job runs: the run is waiting, not finished
+            const j = jobs[jobs.length - 1];
+            out.state = "working";
+            out.action = oneLine(`waiting for a background job${j.command ? `: ${j.command}` : ` (${j.id})`}`, 100);
+            const outputs = jobs.map((x) => x.output).filter((x) => !!x);
+            if (outputs.length)
+                out.pendingOutputs = outputs;
+        }
         else if (bs.some((b) => b.type === "text" && b.text?.trim())) {
             out.state = kind === "subagent" ? "done" : "idle";
             const full = bs.filter((b) => b.type === "text").map((b) => b.text ?? "").join("\n");
@@ -208,10 +282,26 @@ function readMeta(file) {
     }
 }
 const STALL_MS = 20 * 60_000;
-export function applyStall(run, pendingTimeoutMs, now) {
+/** The newest modification time among files that exist on this machine, or undefined. */
+export function newestMtime(files) {
+    let newest;
+    for (const f of files ?? []) {
+        try {
+            const m = fs.statSync(f).mtimeMs;
+            if (newest === undefined || m > newest)
+                newest = m;
+        }
+        catch {
+            // not on this machine, or gone
+        }
+    }
+    return newest;
+}
+/** `lastSeenMs` is other proof of life, such as a background job's output file changing. */
+export function applyStall(run, pendingTimeoutMs, now, lastSeenMs) {
     if (run.state !== "working" || !run.lastActivity)
         return;
-    const quiet = now - Date.parse(run.lastActivity);
+    const quiet = now - Math.max(Date.parse(run.lastActivity), lastSeenMs ?? 0);
     const allowed = Math.max(STALL_MS, (pendingTimeoutMs ?? 0) + 2 * 60_000);
     if (quiet > allowed)
         run.state = "stalled";
@@ -290,7 +380,7 @@ function readSession(file, now) {
             prompt: head.prompt ? oneLine(head.prompt, 400) : undefined,
             activity: logActivity(file, now),
         };
-        applyStall(run, tail.pendingTimeoutMs, now);
+        applyStall(run, tail.pendingTimeoutMs, now, newestMtime(tail.pendingOutputs));
         return run;
     }
     catch (err) {
@@ -321,7 +411,7 @@ function readSubagent(file, now) {
             prompt: head.prompt ? oneLine(head.prompt, 400) : undefined,
             activity: logActivity(file, now),
         };
-        applyStall(run, tail.pendingTimeoutMs, now);
+        applyStall(run, tail.pendingTimeoutMs, now, newestMtime(tail.pendingOutputs));
         return run;
     }
     catch (err) {

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, commentCard, inboxScope, 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, 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 { digest, digestText, localDate } from "../core/digest.js";
 import { everywhere, readEvents } from "../core/store.js";
@@ -109,7 +109,7 @@ cardCommand("todo", "todo", "something only the human can do, but nothing waits
     .action((title, o) => finishCard({ kind: "todo", title, ...common(o) }, o.json));
 program
     .command("edit <card>")
-    .description("change a card: its kind, wording, task, who asked or when it came up (an empty value clears)")
+    .description("change a card: its kind, wording, task, who asked, when it came up, or (before anyone answered) its action, preview and attachments (an empty value clears)")
     .option("-k, --kind <kind>", "decide, try, block or todo")
     .option("--title <text>", "new title")
     .option("-b, --body <text>", "new body")
@@ -117,9 +117,24 @@ program
     .option("--from <who>", "who asked")
     .option("--session <id>", "the agent session that asked")
     .option("--since <date>", "when the matter first came up (YYYY-MM-DD)")
+    .option("--action <text>", "the exact command or step that runs on yes (only before anyone answered)")
+    .option("--preview <file>", "a file with the text the action sends; its text is read again (only before anyone answered)")
+    .option("--attach <file>", "replace the attachments with these files (repeatable; only before anyone answered)", collect)
+    .option("--no-attach", "remove the attachments (only before anyone answered)")
     .option("--json", "print the card as JSON")
     .action((id, o) => {
-    const card = editCard(id, { kind: o.kind, title: o.title, body: o.body, task: o.task, from: o.from, session: o.session, since: o.since });
+    const card = editCard(id, {
+        kind: o.kind,
+        title: o.title,
+        body: o.body,
+        task: o.task,
+        from: o.from,
+        session: o.session,
+        since: o.since,
+        action: o.action,
+        preview: o.preview,
+        attach: o.attach === false ? [] : o.attach,
+    });
     if (o.json)
         print(card);
     else
@@ -292,6 +307,14 @@ run
     .option("--failed", "it failed")
     .option("-n, --note <text>", "how it ended")
     .action((id, o) => endRun(id, o.failed ? "failed" : "done", o.note));
+run
+    .command("hide <id>")
+    .description("hide a run from the lists until it does something new (id or its first 6+ characters; `runs --all` still shows it)")
+    .action((id) => void process.stdout.write(`hidden ${hideRun(id)}\n`));
+run
+    .command("unhide <id>")
+    .description("show a hidden run again")
+    .action((id) => void process.stdout.write(`shown ${unhideRun(id)}\n`));
 program
     .command("claim [session]")
     .description("say which project and task an agent session works on (id prefix, 6+ characters; defaults to the calling session)")

package/dist/core/format.js

@@ -115,6 +115,11 @@ export function cardRows(cards, v = PLAIN, now = Date.now(), indent = "", extra
 export function cardLine(c, now = Date.now()) {
     return cardRows([c], PLAIN, now)[0].trimEnd();
 }
+/** Local clock time, as in "14:05". */
+function hhmm(iso) {
+    const d = new Date(iso);
+    return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+}
 export function cardDetail(c) {
     const out = [];
     out.push(`${c.id} · ${KIND_LABEL[c.kind]} · ${c.project}${c.task ? ` [${c.task}]` : ""} · ${c.status}`);
@@ -125,10 +130,11 @@ export function cardDetail(c) {
         out.push("");
         c.options.forEach((o, i) => out.push(`  ${i + 1}. ${o}${c.recommend === i + 1 ? "  (recommended)" : ""}`));
     }
+    const changed = c.changedAt ? ` (changed ${hhmm(c.changedAt)})` : "";
     if (c.action)
-        out.push("", `Runs on yes: ${c.action}`);
+        out.push("", `Runs on yes${changed}: ${c.action}`);
     if (c.preview)
-        out.push("", "Preview:", ...c.preview.split("\n").map((l) => `  ${l}`));
+        out.push("", `Preview${c.action ? "" : changed}${c.previewFile ? ` of ${c.previewFile}` : ""}:`, ...c.preview.split("\n").map((l) => `  ${l}`));
     if (c.look)
         out.push("", `Look at: ${c.look}`);
     for (const o of c.open ?? [])

package/dist/core/ops.js

@@ -4,6 +4,7 @@ import { UserError } from "./errors.js";
 import { advance, appendEvent, deviceName, eventsDir, homeDir, isAfter, readCursor, readEvents, sharedDir, writeCursor } from "./store.js";
 import { archivedSessions } from "./desktop.js";
 import { findId, fold, nextId, sessionTitle } from "./state.js";
+import { collectRuns } from "./runs.js";
 import { pathMap } from "./sync.js";
 import { CARD_KINDS, HUMAN, PR_CHANGES } from "./types.js";
 export { UserError, sessionTitle };
@@ -53,14 +54,15 @@ const PREVIEW_MAX = 20_000;
 function readPreview(file) {
     if (!file?.trim())
         return undefined;
+    const abs = path.resolve(file);
     let text;
     try {
-        text = fs.readFileSync(path.resolve(file), "utf8");
+        text = fs.readFileSync(abs, "utf8");
     }
     catch {
         throw new UserError(`cannot read the preview file ${file}`);
     }
-    return text.length > PREVIEW_MAX ? text.slice(0, PREVIEW_MAX) + "\n…" : text;
+    return { preview: text.length > PREVIEW_MAX ? text.slice(0, PREVIEW_MAX) + "\n…" : text, previewFile: abs };
 }
 /** A date or timestamp as ISO text; a bare date counts as local midnight. */
 export function parseWhen(s) {
@@ -83,7 +85,7 @@ export function openCard(input) {
     const action = input.action?.trim() || undefined;
     // an approval with no choices of its own is a yes or a no
     const options = cleanList(input.options) ?? (action ? ["Do it", "Don't"] : undefined);
-    const preview = readPreview(input.preview);
+    const pv = readPreview(input.preview);
     if (input.recommend !== undefined) {
         if (!options)
             throw new UserError("--recommend needs --option");
@@ -116,7 +118,8 @@ export function openCard(input) {
                 session,
                 since,
                 action,
-                preview,
+                preview: pv?.preview,
+                previewFile: pv?.previewFile,
             },
         };
     });
@@ -175,7 +178,8 @@ export function commentCard(id, text, by) {
     appendEvent(() => ({ type: "card.comment", card: id, by, text: text.trim() }));
 }
 export function editCard(id, set) {
-    id = requireCard(id).id;
+    const card = requireCard(id);
+    id = card.id;
     const clean = {};
     if (set.kind !== undefined)
         clean.kind = checkKind(set.kind);
@@ -196,6 +200,19 @@ export function editCard(id, set) {
         clean.session = set.session.trim() || cleared;
     if (set.since !== undefined)
         clean.since = set.since.trim() ? parseWhen(set.since) : cleared;
+    const approval = set.action !== undefined || set.preview !== undefined || set.attach !== undefined;
+    if (approval && card.answers.length) {
+        throw new UserError(`card ${id} was already answered; close it and open a new one (a yes must not apply to text the human did not see)`);
+    }
+    if (set.action !== undefined)
+        clean.action = set.action.trim() || cleared;
+    if (set.preview !== undefined) {
+        const pv = readPreview(set.preview);
+        clean.preview = pv?.preview ?? cleared;
+        clean.previewFile = pv?.previewFile ?? cleared;
+    }
+    if (set.attach !== undefined)
+        clean.attach = absPaths(set.attach) ?? cleared;
     if (!Object.keys(clean).length)
         throw new UserError("nothing to change");
     appendEvent(() => ({ type: "card.edit", card: id, set: clean }));
@@ -230,6 +247,34 @@ export function endRun(id, status, note) {
     const run = requireRun(id);
     appendEvent(() => ({ type: "run.end", run, status, note }));
 }
+/** The id of a seen or declared run from the start of it (6+ characters), or the exact id. */
+function resolveRunId(id, state) {
+    const exact = (xs) => (xs.includes(id) ? [id] : xs.filter((x) => x.startsWith(id)));
+    if (id.length < 6 && !state.runs.has(id))
+        throw new UserError("give at least 6 characters of the run id");
+    const seen = collectRuns(state, { sinceHours: 24 * 7, includeEnded: true, keepRepeats: true }).map((r) => r.id);
+    const found = [...new Set(exact([...seen, ...state.runs.keys(), ...state.hidden.keys()]))];
+    if (found.length === 1)
+        return found[0];
+    if (!found.length)
+        throw new UserError(`no run "${id}" (parawatch runs --wide shows ids)`);
+    throw new UserError(`"${id}" matches ${found.length} runs; give more of the id`);
+}
+/** Hide a run from the lists until it does something new. Works for runs other machines shared. */
+export function hideRun(id) {
+    const run = resolveRunId(id, readState());
+    appendEvent(() => ({ type: "run.hide", run }));
+    return run;
+}
+export function unhideRun(id) {
+    const state = readState();
+    const hidden = [...state.hidden.keys()].filter((k) => k === id || k.startsWith(id));
+    const run = hidden.length === 1 ? hidden[0] : hidden.length ? hidden.find((k) => k === id) : resolveRunId(id, state);
+    if (!run)
+        throw new UserError(`"${id}" matches ${hidden.length} hidden runs; give more of the id`);
+    appendEvent(() => ({ type: "run.unhide", run }));
+    return run;
+}
 /**
  * Say which project and task a session works on. A claim without a project keeps the session's
  * earlier claim and only changes what is given (for `--done`). A claim of a new task clears `done`.

package/dist/core/runs.js

@@ -363,6 +363,27 @@ export function otherRuns(state, now = Date.now()) {
     }
     return out;
 }
+/**
+ * Leave out runs the human hid. A run comes back once it has done something after it was hidden.
+ * Children of a hidden session stay hidden by the same rule, measured from the parent's hide time.
+ */
+function withoutHidden(runs, state) {
+    if (!state.hidden.size)
+        return runs;
+    const byId = new Map(runs.map((r) => [r.id, r]));
+    const hiddenAt = (r, seen = new Set()) => {
+        seen.add(r.id);
+        const own = state.hidden.get(r.id);
+        const at = own !== undefined ? Date.parse(own) : r.parent && !seen.has(r.parent) && byId.has(r.parent) ? hiddenAt(byId.get(r.parent), seen) : undefined;
+        return at !== undefined && Number.isFinite(at) ? at : undefined;
+    };
+    return runs.filter((r) => {
+        const at = hiddenAt(r);
+        if (at === undefined)
+            return true;
+        return r.lastActivity ? Date.parse(r.lastActivity) > at : false;
+    });
+}
 const ENDED = new Set(["done", "idle", "failed"]);
 const RECENT_END_MS = 30 * 60_000;
 const OLD_STALL_MS = 3 * 3_600_000;
@@ -392,13 +413,16 @@ export function collectRuns(state, q, now = Date.now()) {
                 return true; // still waiting for the human to read it
             if (live.has(r.id))
                 return true;
-            if (r.role === "lead")
+            // a lead idle between turns stays; one that really ended (claimed done, archived) follows the normal rule
+            if (r.role === "lead" && !r.done)
                 return true;
             return r.lastActivity ? now - Date.parse(r.lastActivity) < RECENT_END_MS : false;
         });
     }
     if (!q.keepRepeats)
         runs = foldRepeats(runs);
+    if (!q.includeEnded)
+        runs = withoutHidden(runs, state);
     return runs.sort((a, b) => (b.lastActivity ?? "").localeCompare(a.lastActivity ?? ""));
 }
 //# sourceMappingURL=runs.js.map

package/dist/core/sites.js

@@ -0,0 +1,148 @@
+export const CLAUDE_SITE = "https://claude.ai/";
+export const CODEX_SITE = "https://developers.openai.com/codex";
+/** The fixed sites, with the name the tooltip uses. */
+export const SERVICE_NAMES = {
+    [CLAUDE_SITE]: "Claude Code",
+    [CODEX_SITE]: "Codex",
+};
+/** The site for a run's runtime; declared runs and unknown runtimes have none. */
+export function siteForRun(run) {
+    if (run.runtime === "claude-code")
+        return CLAUDE_SITE;
+    if (run.runtime === "codex")
+        return CODEX_SITE;
+    return undefined;
+}
+/** The site for a pull request, from its URL (`https://<host>/...` becomes `https://<host>/`). */
+export function siteForPr(pr) {
+    try {
+        const u = new URL(pr.url);
+        return u.protocol === "https:" && u.hostname ? `https://${u.host}/` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether `site` may be fetched: a plain https URL with no credentials, query or fragment, that is
+ * one of the fixed sites or the root of a host in `prHosts`.
+ */
+export function allowedSite(site, prHosts) {
+    if (typeof site !== "string")
+        return false;
+    let u;
+    try {
+        u = new URL(site);
+    }
+    catch {
+        return false;
+    }
+    if (u.protocol !== "https:" || u.username || u.password || u.search || u.hash)
+        return false;
+    if (u.href !== site)
+        return false;
+    if (site in SERVICE_NAMES)
+        return true;
+    if (u.pathname !== "/")
+        return false;
+    for (const h of prHosts)
+        if (h.toLowerCase() === u.host)
+            return true;
+    return false;
+}
+/** The runtime's product name, for tooltips. */
+export function serviceName(run) {
+    const site = siteForRun(run);
+    return site ? SERVICE_NAMES[site] : undefined;
+}
+/** How long an icon is kept before it is fetched again, and how long a failure is remembered. */
+export const ICON_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export const ICON_FAIL_TTL_MS = 24 * 60 * 60 * 1000;
+/** `fresh`: use the stored icon; `failed`: do not try again yet; `stale`: fetch it. */
+export function iconCacheState(e, now) {
+    const fetched = e?.fetchedAt ? Date.parse(e.fetchedAt) : NaN;
+    const failed = e?.failedAt ? Date.parse(e.failedAt) : NaN;
+    if (Number.isFinite(failed) && now - failed < ICON_FAIL_TTL_MS && !(Number.isFinite(fetched) && fetched > failed))
+        return "failed";
+    if (Number.isFinite(fetched) && now - fetched < ICON_TTL_MS)
+        return "fresh";
+    return "stale";
+}
+function attrs(tag) {
+    const out = {};
+    const re = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)\s*(?:=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+    for (const m of tag.replace(/^<link\b/i, "").matchAll(re))
+        out[m[1].toLowerCase()] = m[2] ?? m[3] ?? m[4] ?? "";
+    return out;
+}
+/** The icon links a page declares (`rel` icon, shortcut icon, apple-touch-icon), as absolute https URLs. */
+export function parseIconLinks(html, base) {
+    const found = [];
+    for (const m of html.matchAll(/<link\b[^>]*>/gi)) {
+        const a = attrs(m[0]);
+        const rel = (a.rel ?? "").toLowerCase().split(/\s+/);
+        if (!rel.includes("icon") && !rel.includes("apple-touch-icon"))
+            continue;
+        if (!a.href)
+            continue;
+        let url;
+        try {
+            url = new URL(a.href, base);
+        }
+        catch {
+            continue;
+        }
+        if (url.protocol !== "https:")
+            continue;
+        const svg = (a.type ?? "").toLowerCase().includes("svg") || /\.svg$/i.test(url.pathname);
+        let size;
+        for (const s of (a.sizes ?? "").toLowerCase().split(/\s+/)) {
+            const wh = /^(\d+)x(\d+)$/.exec(s);
+            if (wh)
+                size = Math.max(size ?? 0, Number(wh[1]), Number(wh[2]));
+        }
+        found.push({ url: url.href, svg, size });
+    }
+    return found;
+}
+/**
+ * The URLs to try, best first: an SVG, then the raster icon closest to 32px or larger, then the
+ * site's `/favicon.ico`.
+ */
+export function rankIcons(links, base) {
+    const score = (l) => {
+        if (l.svg)
+            return -1;
+        const s = l.size ?? 32;
+        return s >= 32 ? s - 32 : 1000 + (32 - s);
+    };
+    const urls = links
+        .map((l, i) => ({ l, i }))
+        .sort((a, b) => score(a.l) - score(b.l) || a.i - b.i)
+        .map((x) => x.l.url);
+    try {
+        urls.push(new URL("/favicon.ico", base).href);
+    }
+    catch {
+        // not a URL; nothing to fall back to
+    }
+    return [...new Set(urls)];
+}
+/** The file name an icon is stored under: the site without its scheme, safe for any file system. */
+export function siteFileKey(site) {
+    return site.replace(/^https:\/\//, "").replace(/\/+$/, "").replace(/[^a-zA-Z0-9.-]+/g, "_").toLowerCase();
+}
+const EXTENSIONS = {
+    "image/svg+xml": "svg",
+    "image/png": "png",
+    "image/x-icon": "ico",
+    "image/vnd.microsoft.icon": "ico",
+    "image/jpeg": "jpg",
+    "image/gif": "gif",
+    "image/webp": "webp",
+};
+/** The image types an icon may have; anything else is not shown. */
+export function iconExtension(mime) {
+    return EXTENSIONS[mime.split(";")[0].trim().toLowerCase()];
+}
+//# sourceMappingURL=sites.js.map

package/dist/core/state.js

@@ -10,7 +10,7 @@ function mapAll(xs, map, from) {
 }
 /** Rebuild current state from the event log. `map` makes other machines' paths local. */
 export function fold(events, map) {
-    const s = { projects: new Map(), cards: new Map(), runs: new Map(), claims: [], prLinks: new Map(), lastSeq: 0 };
+    const s = { projects: new Map(), cards: new Map(), runs: new Map(), claims: [], hidden: new Map(), prLinks: new Map(), lastSeq: 0 };
     for (const ev of events) {
         s.lastSeq = Math.max(s.lastSeq, ev.seq);
         switch (ev.type) {
@@ -26,6 +26,8 @@ export function fold(events, map) {
                     card.dev = ev.dev;
                 card.attach = mapAll(card.attach, map, ev.dev);
                 card.open = mapAll(card.open, map, ev.dev);
+                if (card.previewFile)
+                    card.previewFile = mapAll([card.previewFile], map, ev.dev)?.[0];
                 s.cards.set(ev.card.id, card);
                 break;
             }
@@ -58,9 +60,15 @@ export function fold(events, map) {
                 for (const [k, v] of Object.entries(ev.set)) {
                     if (v === null || v === undefined)
                         delete target[k];
+                    else if (k === "attach")
+                        c.attach = mapAll(ev.set.attach, map, ev.dev);
+                    else if (k === "previewFile")
+                        c.previewFile = mapAll([ev.set.previewFile], map, ev.dev)?.[0];
                     else
                         target[k] = v;
                 }
+                if ("action" in ev.set || "preview" in ev.set)
+                    c.changedAt = ev.ts;
                 break;
             }
             case "card.close": {
@@ -105,6 +113,12 @@ export function fold(events, map) {
                 s.claims = s.claims.filter((c) => c.session !== ev.claim.session);
                 s.claims.push({ ...ev.claim, at: ev.ts });
                 break;
+            case "run.hide":
+                s.hidden.set(ev.run, ev.ts);
+                break;
+            case "run.unhide":
+                s.hidden.delete(ev.run);
+                break;
             case "pr.link":
                 s.prLinks.set(ev.link.pr.key, { ...ev.link, at: ev.ts });
                 break;

package/package.json

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

@@ -56,6 +56,7 @@ A good card:
 - **Add `-t <task>`** when the project runs several tasks at once, so the human can tell them apart.
 - **`block` is red and counts as needing them now.** Use it only when your work stops until they act. Errands for later (a bill, a registration, a policy check, a measurement whenever the machine is free) are `todo`; they wait folded in the panel and do not pop up.
 - **Moving items from a board or a note:** pass `--since <YYYY-MM-DD>` with the date the item first came up, so the card does not look new. `parawatch edit <card>` fixes a card's kind, wording or date later.
+- **`--action` is the exact command, one line if possible.** Steps and reasons go in the body, and `--preview` is the file with the text it sends (the human can open that file from the card). Change `--action`, `--preview` or `--attach` with `parawatch edit` while the card is unanswered; once answered, close it and open a new one.
 - **An approval shows exactly what runs.** With `--action` the human sees the command and the preview and answers Do it or Don't, without opening your session. Run exactly that on yes; say in the close note that you ran it.
 - **Never leave a question only in your reply.** If your turn ends needing the human, the question goes on a card. Parawatch flags questions it finds at the end of a turn as "asked in chat, no card", but that is a guess and easy to miss.
 - Do not open a card for something you can decide yourself, or that the project's own rules already settle.
@@ -135,6 +136,7 @@ When `parawatch sync` shows other machines, the human may answer from any of the
 ```
 parawatch status                     # everything: what needs the human, what waits on others, what is running
 parawatch runs -p <project> --wide   # agents with ids
+parawatch run hide <id>              # the human asks to hide a run; it returns when it does something new
 parawatch pr list                    # open pull requests and what each waits on
 parawatch digest                     # what each session did today
 parawatch show <card>                # one card in full