@alphacoder-v0/pi-loops 0.22.8 → 0.24.0

package/src/inbox-card.ts

@@ -0,0 +1,278 @@
+/**
+ * A finding as a person reads it: the one place the stored line of `inbox.jsonl` is split into what
+ * the terminal's `/inbox`, `pi-loops inbox list` and the page show. Parsed at read time and never
+ * written back, so the stored shape (CONTRACT.md 2.2) does not change.
+ *
+ * A checkpoint is `<the decision> · waits: <what waits on it> · if not: <what happens if nobody
+ * acts>` (docs/recipes.md); a card shows the three parts apart, under the page's words "Waiting on"
+ * and "If you don't". News is one finding with a headline. What a claim says to the agent and what a
+ * dismiss tells the loop are decided here too, so every surface says the same thing.
+ */
+import { deadLetterParts } from "./engine.ts";
+import { loopLabel } from "./job-lines.ts";
+import type { InboxEntry, InboxStatus } from "./inbox.ts";
+import { INBOX_TEXT_MAX_CHARS, capChars } from "./protocol.ts";
+import { redact } from "./redact.ts";
+
+export interface InboxCard {
+	/** `inb-…`: the only thing a button sends. */
+	id: string;
+	/** `decision` exactly when the stored kind is `checkpoint`; never read again off the text. */
+	kind: "decision" | "news";
+	status: InboxStatus;
+	/** A decision: the text before `· waits:`. News: the first sentence. Never empty. */
+	headline: string;
+	/** News only: what follows the first sentence. */
+	body?: string;
+	/** A decision: between `· waits:` and `· if not:`. */
+	waits?: string;
+	/** A decision: after `· if not:`; undefined when the loop left the clause out. */
+	ifNot?: string;
+	/** The checker kept it (✓). */
+	verified: boolean;
+	verifiedReason?: string;
+	/** `rule`: a trigger's result. `undelivered`: a prompt that never reached its conversation (a dead letter). */
+	origin: "loop" | "rule" | "undelivered";
+	/** The loop that filed it, with its name when the loop still exists, and its label (src/job-lines.ts loopLabel). */
+	loop?: { id: string; name?: string; label: string };
+	/** A rule check's result: the first rule it matched, with its condition while the rule exists. */
+	rule?: { id: string; condition?: string };
+	source: string;
+	cwd: string;
+	createdAt: string;
+	runId: string;
+	/** The conversation that created the loop: where a claim runs (D3). */
+	sessionId?: string;
+	/** The finding names its run's transcript. The file is not looked at. */
+	hasTranscript: boolean;
+	/** `sessionId` is the conversation the card is shown in. */
+	fromThisConversation: boolean;
+	/** A claim from the page is queued for it and has not marked it claimed yet: Yes is not offered again. */
+	claiming: boolean;
+}
+
+export interface CardContext {
+	/** The conversation the card is shown in. */
+	here?: string;
+	/** A loop's name from jobs.json, or undefined when the loop is gone or has none. */
+	loopName(jobId: string): string | undefined;
+	/** Whether a page claim row for this finding is queued. */
+	claiming?(id: string): boolean;
+	/** A rule's condition from triggers.json, or undefined when the rule is gone. */
+	ruleCondition?(ruleId: string): string | undefined;
+}
+
+/** A rule's condition on a card's origin line, clipped so the line stays one line. */
+const RULE_CONDITION_CHARS = 80;
+
+/**
+ * A finding's text as a screen may show it: a terminal's escape sequences (colour, clear, title),
+ * other control characters, the bidi marks and overrides that reorder a line, and the characters no
+ * surface draws are taken out: the zero-width space and invisible operators (U+200B, U+2060-2064,
+ * U+FEFF), the soft hyphen, U+034F, the Hangul and Mongolian fillers, the tags U+E0000-E007F and the
+ * variation selectors U+FE00-FE0D, which can carry bytes no one sees. What ordinary text needs stays:
+ * the joiners U+200C and U+200D (emoji sequences, Persian, Devanagari), U+FE0E and U+FE0F (how an
+ * emoji is drawn) and the ideographic variation selectors U+E0100-E01EF. So `/inbox` cannot repaint the terminal it prints in, and every
+ * surface, and the claim's prompt, carries the same words.
+ */
+export function screenText(text: string): string {
+	return text
+		// Only a terminated string: an introducer with no BEL or ST would otherwise take the rest of
+		// the finding with it, and the card would hide what a claim then sends.
+		.replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g, "")
+		.replace(/\u001b\[[0-9;?]*[ -\/]*[@-~]/g, "")
+		.replace(/\u001b[@-_]?/g, "")
+		.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f\u00ad\u034f\u061c\u115f\u1160\u180e\u200b\u200e\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\u3164\ufe00-\ufe0d\ufeff\uffa0\u{e0000}-\u{e007f}]/gu, "");
+}
+
+/** The mark `findingKind` reads a checkpoint by (CONTRACT.md 2.6), and the clause after it. */
+const WAITS = /(^|\s)·\s*waits:/i;
+const IF_NOT = /\s·\s*if not:/i;
+/** How far into a news finding its first sentence may end and still be a headline. */
+const HEADLINE_MAX_CHARS = 200;
+
+/**
+ * The parts of a finding's text. A decision splits at the first `· waits:` and then at the first
+ * `· if not:`; a decision with no `· waits:` left (cut by the 500-character cap, or written by hand)
+ * keeps its whole text as the headline, and so does one whose headline would be empty. News splits
+ * after its first sentence, when that ends within 200 characters.
+ */
+export function splitFinding(text: string, kind: InboxEntry["kind"]): Pick<InboxCard, "headline" | "body" | "waits" | "ifNot"> {
+	if (kind === "checkpoint") {
+		const at = WAITS.exec(text);
+		if (!at) return { headline: text };
+		const headline = text.slice(0, at.index).trim();
+		if (!headline) return { headline: text };
+		const rest = text.slice(at.index + at[0].length);
+		const cut = IF_NOT.exec(rest);
+		const waits = (cut ? rest.slice(0, cut.index) : rest).trim();
+		const ifNot = cut ? rest.slice(cut.index + cut[0].length).trim() : "";
+		return { headline, ...(waits ? { waits } : {}), ...(ifNot ? { ifNot } : {}) };
+	}
+	const end = /[.!?](?=\s)|[。！？]/.exec(text);
+	if (!end || end.index >= HEADLINE_MAX_CHARS) return { headline: text };
+	const headline = text.slice(0, end.index + 1).trim();
+	const body = text.slice(end.index + 1).trim();
+	return body ? { headline, body } : { headline };
+}
+
+/**
+ * The `matched <rule-id>` a rule check starts what it says with (src/triggers.ts asks for the ids),
+ * with more ids after it and the punctuation that ends it. It names the rule, which the card's
+ * origin line does already.
+ */
+const MATCHED_TOKEN = /^\s*`?matched`?\s+`?dyn-[0-9a-f]{32}`?(?:\s*(?:,|and)\s*`?dyn-[0-9a-f]{32}`?)*\s*[.:;,!—–-]*\s*/i;
+
+/** A rule result's text as its card reads it: without the leading `matched <rule-id>`, unless that is all it says. */
+export function ruleResultText(text: string): string {
+	const rest = text.replace(MATCHED_TOKEN, "");
+	return rest || text;
+}
+
+/**
+ * One finding as a card, or undefined for a line with no id or no text: `readFinding` turns a
+ * line `{}` into an entry with both empty, and a button that sends an empty id names nothing.
+ * The text is redacted and capped again, since a line another tool wrote is not bounded.
+ */
+export function inboxCard(entry: InboxEntry, ctx: CardContext): InboxCard | undefined {
+	if (!entry.id || !entry.text) return undefined;
+	const text = capChars(redact(screenText(entry.text)).replace(/\s+/g, " "), INBOX_TEXT_MAX_CHARS);
+	const origin = entry.source.startsWith("trigger:") ? "rule" : deadLetterParts(entry.text) ? "undelivered" : "loop";
+	const loopId = origin === "loop" ? entry.job_id : undefined;
+	const loopName = loopId ? ctx.loopName(loopId) : undefined;
+	// A rule check files its result with the first matched rule's id (src/trigger-runtime.ts); a push
+	// with no rule files its source label there, which names no rule.
+	const ruleId = origin === "rule" && entry.job_id?.startsWith("dyn-") ? entry.job_id : undefined;
+	const condition = ruleId ? ctx.ruleCondition?.(ruleId) : undefined;
+	return {
+		id: entry.id,
+		kind: entry.kind === "checkpoint" ? "decision" : "news",
+		status: entry.status,
+		...splitFinding(origin === "rule" ? ruleResultText(text) : text, entry.kind),
+		verified: entry.verified === true,
+		...(entry.verified_reason ? { verifiedReason: redact(screenText(entry.verified_reason)) } : {}),
+		origin,
+		...(loopId ? { loop: loopName === undefined ? { id: loopId, label: loopLabel({ id: loopId }) } : { id: loopId, name: loopName, label: loopLabel({ id: loopId, name: loopName }) } } : {}),
+		...(ruleId ? { rule: condition ? { id: ruleId, condition: capChars(redact(screenText(condition)).replace(/\s+/g, " "), RULE_CONDITION_CHARS - 1) } : { id: ruleId } } : {}),
+		source: entry.source,
+		cwd: entry.cwd,
+		createdAt: entry.created_at,
+		runId: entry.run_id,
+		...(entry.session_id ? { sessionId: entry.session_id } : {}),
+		hasTranscript: origin !== "rule" && !!entry.transcript,
+		fromThisConversation: !!entry.session_id && entry.session_id === ctx.here,
+		claiming: entry.status === "new" && (ctx.claiming?.(entry.id) ?? false),
+	};
+}
+
+/** The cards of `entries`, decisions first and each group in the order given (`Inbox.listNew`'s); lines with no id or text are left out. */
+export function cardsOf(entries: readonly InboxEntry[], ctx: CardContext): InboxCard[] {
+	const cards = entries.flatMap((e) => inboxCard(e, ctx) ?? []);
+	return [...cards.filter((c) => c.kind === "decision"), ...cards.filter((c) => c.kind === "news")];
+}
+
+/** How far a card's continuation lines are indented under its first line. */
+const CLAUSE_INDENT = "       ";
+
+/** What filed a card, as every surface but `inbox --json` names it: a loop's label, else the stored source. */
+export function cardOrigin(card: Pick<InboxCard, "loop" | "source">): string {
+	return card.loop ? card.loop.label : card.source;
+}
+
+/**
+ * A card as terminal lines: `head`, the marks, the headline (news: its whole text) and `meta` on
+ * the first line; a decision's clauses on indented lines under it, under the page's words. A clause
+ * the loop left out prints nothing: two packaged playbooks leave `if not` out on purpose.
+ */
+export function cardLines(card: InboxCard, head: string, meta: string): string[] {
+	const mark = `${card.kind === "decision" ? "⚑ " : ""}${card.verified ? "✓ " : ""}`;
+	const title = card.body === undefined ? card.headline : `${card.headline}${/[。！？]$/.test(card.headline) ? "" : " "}${card.body}`;
+	const lines = [`${head}${mark}${title}${meta}`];
+	if (card.waits !== undefined) lines.push(`${CLAUSE_INDENT}waiting on: ${card.waits}`);
+	if (card.ifNot !== undefined) lines.push(`${CLAUSE_INDENT}if you don't: ${card.ifNot}`);
+	return lines;
+}
+
+/**
+ * A card as one line, for a shell: `pi-loops inbox list` prints one line per finding (docs/cli.md),
+ * so a script that reads the ids with `awk '{print $1}'` keeps working. The clauses follow the
+ * headline on the same line, under the page's words.
+ */
+export function cardLine(card: InboxCard, head: string, meta: string): string {
+	const [first, ...clauses] = cardLines(card, "", "");
+	return `${head}${first}${clauses.map((c) => ` · ${c.trim()}`).join("")}${meta}`;
+}
+
+/** The reasons a page offers for a dismiss, beside a typed one. Each goes to the loop as said. */
+export const DISMISS_CHIPS = ["Not a bug", "Already fixed", "Duplicate", "Too noisy", "Not now"] as const;
+
+/** Whom a dismiss tells: the loop's next run, nobody (and why), or nobody because no reason was given. */
+export type DismissOutcome = { told: "loop"; loop: string } | { told: "nobody"; why: "loop-gone" | "rule" } | { told: "silent" };
+
+/**
+ * Whom a dismiss with `reason` tells. A loop's finding carries its job id; a trigger's carries the
+ * rule's label there, and a rule keeps no notes and has no next run to tell. `loop` is the job
+ * that filed it, when it still exists.
+ */
+export function dismissOutcome(entry: Pick<InboxEntry, "job_id">, loop: { id: string; name?: string } | undefined, reason?: string): DismissOutcome {
+	if (!reason?.trim()) return { told: "silent" };
+	if (loop) return { told: "loop", loop: loopLabel(loop) };
+	return { told: "nobody", why: entry.job_id?.startsWith("cron-") ? "loop-gone" : "rule" };
+}
+
+/** What the terminal adds after `dismissed: <finding>`. */
+export function dismissTail(outcome: DismissOutcome): string {
+	if (outcome.told === "loop") return ` — ${outcome.loop} is told why on its next run`;
+	if (outcome.told === "nobody") return outcome.why === "loop-gone" ? " — the loop that reported it is gone, so nobody is told" : " — a trigger reported it, and a trigger keeps no notes, so nobody is told";
+	return "";
+}
+
+/** What a card says once it is dismissed from the page. */
+export function dismissLine(outcome: DismissOutcome): string {
+	if (outcome.told === "loop") return `Dismissed. Your reason goes to ${outcome.loop}'s next run.`;
+	if (outcome.told === "nobody") return outcome.why === "loop-gone" ? "Dismissed. The loop that reported it is gone, so nobody is told." : "Dismissed. A rule reported it and keeps no notes, so nobody is told.";
+	return "Dismissed.";
+}
+
+/** The turn a claim runs: the finding, where it came from, and what a claim of a checkpoint means. */
+export function claimPrompt(e: InboxEntry): string {
+	// The words the card showed, redacted and capped as it does, so the turn is asked about what the
+	// person read and said yes to, and a secret masked on the card is not sent to the model; the
+	// source and the cwd are screened too, since the turn's message is drawn in a terminal when one
+	// holds the conversation.
+	const text = capChars(redact(screenText(e.text)).replace(/\s+/g, " "), INBOX_TEXT_MAX_CHARS);
+	const source = screenText(e.source).replace(/\s+/g, " ").trim();
+	const cwd = screenText(e.cwd).replace(/\s+/g, " ").trim();
+	const verified = e.verified ? `\n(An independent checker reviewed and kept this finding${e.verified_reason ? `: ${redact(screenText(e.verified_reason))}` : ""}.)` : "";
+	// A checkpoint is a decision the loop prepared and left to a person; the claim is that
+	// person's yes, so the turn carries the decision out rather than re-investigating it.
+	const checkpoint = e.kind === "checkpoint" ? "\nThis finding is a checkpoint: claiming it is the person's approval of the decision it recommends — carry that decision out, and stop where the finding says a person acts." : "";
+	// A prompt that never reached the chat: claiming it is asking for it now, not investigating why it was late.
+	const late = deadLetterParts(text);
+	if (late) return `This prompt (${source}, for ${cwd}) could not be delivered earlier (${late.why}). Do what it asks now:\n${late.prompt}`;
+	return `A recurring loop (${source}, running in ${cwd}) reported this finding — investigate and address it:\n${text}${verified}${checkpoint}`;
+}
+
+/**
+ * Where a claim from the page runs, as the page server finds the conversation that created the
+ * loop: open in the page (rung, so it runs as the person's turn), a terminal that answers what is
+ * queued, a terminal that does not (`pi -p`, a window behind the file), pi-loops in the middle of a
+ * scheduled turn there, nobody (the page starts it), no free page slot (or pi could not be started),
+ * pi stopping too often there to be started again on its own, a pi there without pi-loops (nothing
+ * would drain the row), or a conversation whose file is gone.
+ */
+export type ClaimDelivery = "page" | "terminal" | "terminal-quiet" | "background" | "started" | "full" | "stopped" | "no-pi-loops" | "gone";
+
+/** What a card says once its claim is queued; `title` names the conversation it runs in. */
+export function claimLine(delivery: ClaimDelivery, title?: string): string {
+	const where = title ? `"${title}"` : "its conversation";
+	if (delivery === "page") return `Running in ${where}.`;
+	if (delivery === "started") return `Starting ${where}…`;
+	if (delivery === "terminal") return "Queued for your terminal.";
+	if (delivery === "terminal-quiet") return "Queued; the terminal that has this conversation is not taking messages (/resume there).";
+	if (delivery === "background") return "Queued; runs after pi-loops finishes its scheduled run there.";
+	if (delivery === "full") return "Queued; it opens when another conversation in the page closes.";
+	if (delivery === "no-pi-loops") return "Queued; the pi of that conversation has no pi-loops, so nothing runs it here. Open it in a terminal with pi-loops.";
+	if (delivery === "stopped") return "Queued; pi stopped too often in that conversation to be started again on its own.";
+	return "Queued; its conversation is gone.";
+}

package/src/inbox.ts

@@ -4,7 +4,7 @@
  * the morning. Findings are one-liners with a new → claimed/dismissed lifecycle.
  *
  * Appends are line-atomic; status rewrites are serialized through a file lock.
- * Corrupt lines are skipped on read, never deleted.
+ * Corrupt lines are skipped on read and written back verbatim by every rewrite, never deleted.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -15,6 +15,9 @@ import { stamp } from "./schedule.ts";
 
 export type InboxStatus = "new" | "claimed" | "dismissed";
 
+/** What `Inbox.decide` did: changed the finding, found none with that id, or found it already decided (and by whom, for a claim). */
+export type Decision = { ok: InboxEntry } | { missing: true } | { already: InboxStatus; by?: string };
+
 /** Past this the inbox drops its oldest triaged entries (docs/configuration.md). */
 export const INBOX_ROTATE_BYTES = 1_000_000;
 
@@ -49,18 +52,23 @@ export interface InboxEntry {
 	 */
 	dismiss_reason: string | null;
 	job_id?: string;
-	/** Session that owned the loop when it reported; loops are machine-global here. */
+	/** The session that created the loop that filed this finding. */
 	session_id?: string;
 	claimed_by?: string;
 	/** Checker's reason when it kept a finding, if it gave one. */
 	verified_reason?: string;
 	/** When it was dismissed — what decides whether the loop's next run is shown the reason. */
 	dismissed_at?: string;
+	/** The transcript of the run that filed this finding (RunRecord.sessionFile). */
+	transcript?: string;
 }
 
 /** The fields a finding is, in their order — CONTRACT.md §2.2 and docs/downstream.md §3. */
 export const FINDING_FIELDS = ["id", "created_at", "status", "kind", "source", "run_id", "cwd", "text", "verified", "dismiss_reason"] as const;
 
+/** What a writer gives for a new finding; the inbox fills in the id, the time and the status. */
+export type NewFinding = Omit<InboxEntry, "id" | "created_at" | "status" | "kind" | "verified" | "dismiss_reason"> & Partial<Pick<InboxEntry, "kind" | "verified">>;
+
 /** Reasons longer than a finding are a paragraph, and the prompt they go into is capped. */
 const DISMISS_REASON_MAX_CHARS = INBOX_TEXT_MAX_CHARS;
 
@@ -73,9 +81,45 @@ export class Inbox {
 		this.lockPath = path.join(dir, "inbox.lock");
 	}
 
-	async append(entry: Omit<InboxEntry, "id" | "created_at" | "status" | "kind" | "verified" | "dismiss_reason"> & Partial<Pick<InboxEntry, "kind" | "verified">>): Promise<InboxEntry> {
-		// Built in `FINDING_FIELDS` order, then pi-loops' own: the line is this object as it stands.
-		const full: InboxEntry = {
+	async append(entry: NewFinding): Promise<InboxEntry> {
+		const full = this.build(entry);
+		fs.mkdirSync(path.dirname(this.file), { recursive: true });
+		// Under the same lock as the triage rewrites: findings are appended by every pi window, the
+		// headless host and up to `max_concurrent_runs` loop runs, while `/inbox dismiss|clear`
+		// rewrites the whole file — an append landing mid-rewrite is a finding nobody ever sees.
+		// The lock is awaited, never spun on: a leftover lock directory from a killed process would
+		// otherwise block this process's event loop for the whole stale window.
+		await withFileLock(this.lockPath, () => this.write(full));
+		return full;
+	}
+
+	/**
+	 * Append `entry` unless a finding with the key's `run_id` and `source` is in the inbox already, and
+	 * return the finding that is there either way. A key that has `session_id`, even undefined, names
+	 * one creating conversation's group and matches only its finding; a key without it matches any.
+	 * The look and the append are one step under the inbox lock. A rule check files its result this
+	 * way, and the promotion's inbox fallback and the dead letter of its row then find it: one result,
+	 * one finding, whichever writer comes first. With `unlessRepeat`, the latest new finding of the
+	 * same `job_id`, `cwd` and source with the same text is the one that is there.
+	 */
+	async appendOnce(entry: NewFinding, key: { run_id: string; source: string } | { run_id: string; source: string; session_id: string | undefined }, opts: { unlessRepeat?: boolean } = {}): Promise<InboxEntry> {
+		const full = this.build(entry);
+		const source = capChars(key.source, 80);
+		fs.mkdirSync(path.dirname(this.file), { recursive: true });
+		return withFileLock(this.lockPath, () => {
+			const all = this.list();
+			const there = all.find((e) => e.run_id === key.run_id && e.source === source && (!("session_id" in key) || e.session_id === key.session_id));
+			if (there) return there;
+			const latest = opts.unlessRepeat ? all.filter((e) => e.status === "new" && e.job_id === full.job_id && e.cwd === full.cwd && e.source === full.source).at(-1) : undefined;
+			if (latest && latest.text === full.text) return latest;
+			this.write(full);
+			return full;
+		});
+	}
+
+	/** The line a new finding is: built in `FINDING_FIELDS` order, then pi-loops' own. */
+	private build(entry: NewFinding): InboxEntry {
+		return {
 			id: newId("inb"), // inb-<32 hex>, the shape every other id in pi-loops has
 			created_at: stamp(),
 			status: "new",
@@ -87,22 +131,18 @@ export class Inbox {
 			verified: entry.verified ?? null,
 			dismiss_reason: null,
 			job_id: entry.job_id,
-			session_id: entry.session_id,
 			claimed_by: entry.claimed_by,
 			verified_reason: entry.verified_reason,
 			dismissed_at: entry.dismissed_at,
+			...(entry.session_id === undefined ? {} : { session_id: entry.session_id }),
+			...(entry.transcript === undefined ? {} : { transcript: entry.transcript }),
 		};
-		fs.mkdirSync(path.dirname(this.file), { recursive: true });
-		// Under the same lock as the triage rewrites: findings are appended by every pi window, the
-		// headless host and up to `max_concurrent_runs` loop runs, while `/inbox dismiss|clear`
-		// rewrites the whole file — an append landing mid-rewrite is a finding nobody ever sees.
-		// The lock is awaited, never spun on: a leftover lock directory from a killed process would
-		// otherwise block this process's event loop for the whole stale window.
-		await withFileLock(this.lockPath, () => {
-			fs.appendFileSync(this.file, `${JSON.stringify(full)}\n`, "utf8");
-			this.rotate();
-		});
-		return full;
+	}
+
+	/** Caller holds the lock. */
+	private write(full: InboxEntry): void {
+		fs.appendFileSync(this.file, `${JSON.stringify(full)}\n`, "utf8");
+		this.rotate();
 	}
 
 	/**
@@ -114,14 +154,14 @@ export class Inbox {
 	private rotate(): void {
 		try {
 			if (fs.statSync(this.file).size < INBOX_ROTATE_BYTES) return;
-			const entries = this.list();
-			const triaged = entries.filter((e) => e.status !== "new");
+			const lines = this.lines();
+			const triaged = lines.flatMap(({ entry }) => (entry && entry.status !== "new" ? [entry] : []));
 			const drop = Math.floor(triaged.length / 2);
 			// Nothing triaged to drop means an inbox full of unread findings: rewriting it would
 			// change nothing and would cost a full read+write on every append from here on.
 			if (drop === 0) return;
-			const dropped = new Set(triaged.slice(0, drop).map((e) => e.id));
-			this.rewrite(entries.filter((e) => !dropped.has(e.id)));
+			const dropped = new Set(triaged.slice(0, drop));
+			this.rewrite(lines.filter(({ entry }) => !entry || !dropped.has(entry)));
 		} catch {
 			/* best effort: a rotation that fails must never lose the append that just succeeded */
 		}
@@ -129,6 +169,14 @@ export class Inbox {
 
 	/** All entries, oldest first. Unparseable lines are skipped. */
 	list(): InboxEntry[] {
+		return this.lines().flatMap(({ entry }) => (entry ? [entry] : []));
+	}
+
+	/**
+	 * Every non-blank line of the file, in order, with the entry it reads as; `entry` is missing for a
+	 * line that is not a finding (torn, not JSON). A rewrite writes such a line back as it found it.
+	 */
+	private lines(): Array<{ raw: string; entry?: InboxEntry }> {
 		let text: string;
 		try {
 			text = fs.readFileSync(this.file, "utf8");
@@ -136,15 +184,16 @@ export class Inbox {
 			if (err?.code === "ENOENT") return [];
 			throw err;
 		}
-		const out: InboxEntry[] = [];
-		for (const line of text.split("\n")) {
-			if (!line.trim()) continue;
+		const out: Array<{ raw: string; entry?: InboxEntry }> = [];
+		for (const raw of text.split("\n")) {
+			if (!raw.trim()) continue;
+			let entry: InboxEntry | undefined;
 			try {
-				const e = readFinding(JSON.parse(line));
-				if (e && typeof e.id === "string" && typeof e.text === "string") out.push(e);
+				entry = readFinding(JSON.parse(raw));
 			} catch {
-				/* skip corrupt line */
+				/* a corrupt line: kept as raw text, read as nothing */
 			}
+			out.push(entry ? { raw, entry } : { raw });
 		}
 		return out;
 	}
@@ -155,10 +204,20 @@ export class Inbox {
 	 * resolve numbers against it, so the order is decided once, here.
 	 */
 	listNew(): InboxEntry[] {
-		const fresh = this.list().filter((e) => e.status === "new");
+		// A finding with no id or no text names nothing a person could read or act on: not listed, not counted.
+		const fresh = this.list().filter((e) => e.status === "new" && e.id !== "" && e.text !== "");
 		return [...fresh.filter((e) => e.kind === "checkpoint"), ...fresh.filter((e) => e.kind !== "checkpoint")];
 	}
 
+	newFor(sessionId: string, since?: string): InboxEntry[] {
+		const after = since === undefined ? Number.NEGATIVE_INFINITY : Date.parse(since);
+		return this.list().filter((e) => e.status === "new" && e.session_id === sessionId && Date.parse(e.created_at) > after);
+	}
+
+	pinnedTranscripts(jobId: string): Set<string> {
+		return new Set(this.list().filter((e) => e.status === "new" && e.job_id === jobId && e.transcript).map((e) => path.resolve(e.transcript!)));
+	}
+
 	/** Count of new entries; 0 on any error (badge path must never throw). */
 	newCount(): number {
 		try {
@@ -177,38 +236,52 @@ export class Inbox {
 		}
 	}
 
-	/** `reason` is only read for a dismiss: what the person said, kept for the loop's next run. */
-	async setStatus(id: string, status: InboxStatus, claimedBy?: string, reason?: string): Promise<InboxEntry | undefined> {
-		return withFileLock(this.lockPath, () => {
-			const entries = this.list();
-			const entry = entries.find((e) => e.id === id);
-			if (!entry) return undefined;
-			entry.status = status;
-			if (claimedBy) entry.claimed_by = claimedBy;
-			if (status === "dismissed") {
+	/**
+	 * Claim or dismiss one finding, only while it is `new` (CONTRACT.md 2.3: each succeeds once).
+	 * The check and the write are one critical section under the inbox lock, against the file as it
+	 * is then: two pages, a page and a terminal, or two `pi-loops inbox claim` processes that all
+	 * listed the finding as new get one `ok` between them. `by` is who claimed it; `reason` is only
+	 * read for a dismiss — what the person said, kept for the loop's next run.
+	 *
+	 * `before` runs inside the same critical section, after the check and before the write: a claim
+	 * queues its hand-off there, so only the winner ever queues one, and a crash between the two leaves
+	 * the finding new with its hand-off queued (which the page's sweep finishes). Queued before the
+	 * check, a loser's row could be run by its holder at once, or be the row the winner collapsed onto
+	 * and then taken back. A `before` that throws leaves the finding as it was.
+	 */
+	async decide(id: string, to: "claimed" | "dismissed", opts: { by?: string; reason?: string; before?: () => void } = {}): Promise<Decision> {
+		return withFileLock(this.lockPath, (): Decision => {
+			const lines = this.lines();
+			const entry = lines.find((l) => l.entry?.id === id)?.entry;
+			if (!entry) return { missing: true };
+			if (entry.status !== "new") return entry.claimed_by === undefined ? { already: entry.status } : { already: entry.status, by: entry.claimed_by };
+			opts.before?.();
+			entry.status = to;
+			if (opts.by) entry.claimed_by = opts.by;
+			if (to === "dismissed") {
 				entry.dismissed_at = stamp();
-				const why = reason?.replace(/\s+/g, " ").trim();
+				const why = opts.reason?.replace(/\s+/g, " ").trim();
 				if (why) entry.dismiss_reason = capChars(why, DISMISS_REASON_MAX_CHARS);
 			}
-			this.rewrite(entries);
-			return entry;
+			this.rewrite(lines);
+			return { ok: entry };
 		});
 	}
 
 	/** `match` limits it to what the caller listed — `/inbox clear` must not dismiss findings it did not show. */
 	async dismissAllNew(match?: (entry: InboxEntry) => boolean): Promise<number> {
 		return withFileLock(this.lockPath, () => {
-			const entries = this.list();
+			const lines = this.lines();
 			const at = stamp();
 			let changed = 0;
-			for (const e of entries) {
-				if (e.status === "new" && (!match || match(e))) {
+			for (const { entry: e } of lines) {
+				if (e && e.status === "new" && (!match || match(e))) {
 					e.status = "dismissed";
 					e.dismissed_at = at;
 					changed++;
 				}
 			}
-			if (changed) this.rewrite(entries);
+			if (changed) this.rewrite(lines);
 			return changed;
 		});
 	}
@@ -225,8 +298,9 @@ export class Inbox {
 		return this.list().filter((e) => e.job_id === jobId && e.status === "dismissed" && !!e.dismiss_reason && !!e.dismissed_at && Date.parse(e.dismissed_at) > after);
 	}
 
-	private rewrite(entries: InboxEntry[]): void {
-		writeFileAtomic(this.file, entries.map((e) => JSON.stringify(e)).join("\n") + (entries.length ? "\n" : ""));
+	/** Write `lines` back, each finding in this version's shape and every line it could not read as it was. Caller holds the lock. */
+	private rewrite(lines: Array<{ raw: string; entry?: InboxEntry }>): void {
+		writeFileAtomic(this.file, lines.map(({ raw, entry }) => (entry ? JSON.stringify(entry) : raw)).join("\n") + (lines.length ? "\n" : ""));
 	}
 }
 
@@ -238,27 +312,30 @@ export class Inbox {
  */
 function readFinding(raw: any): InboxEntry | undefined {
 	if (!raw || typeof raw !== "object") return undefined;
-	const pick = <T>(...keys: string[]): T | undefined => {
-		for (const k of keys) if (raw[k] !== undefined && raw[k] !== null) return raw[k] as T;
+	// A line anything may have written: a field of the wrong type reads as missing, so every reader
+	// of a finding can call a string method on a string field.
+	const str = (...keys: string[]): string | undefined => {
+		for (const k of keys) if (typeof raw[k] === "string") return raw[k];
 		return undefined;
 	};
-	const status = pick<string>("status");
+	const status = str("status");
 	return {
-		id: String(raw.id ?? ""),
-		created_at: pick<string>("created_at", "createdAt") ?? "",
+		id: str("id") ?? "",
+		created_at: str("created_at", "createdAt") ?? "",
 		status: status === "claimed" || status === "dismissed" ? status : "new",
 		kind: raw.kind === "checkpoint" ? "checkpoint" : "news",
-		source: pick<string>("source") ?? "",
-		run_id: pick<string>("run_id", "trace_id", "runId") ?? "",
-		cwd: pick<string>("cwd") ?? "",
-		text: String(raw.text ?? ""),
-		verified: pick<boolean>("verified") ?? null,
-		dismiss_reason: pick<string>("dismiss_reason") ?? null,
-		job_id: pick<string>("job_id", "jobId"),
-		session_id: pick<string>("session_id", "sessionId"),
-		claimed_by: pick<string>("claimed_by", "claimedBy"),
-		verified_reason: pick<string>("verified_reason", "verifiedReason"),
-		dismissed_at: pick<string>("dismissed_at"),
+		source: str("source") ?? "",
+		run_id: str("run_id", "trace_id", "runId") ?? "",
+		cwd: str("cwd") ?? "",
+		text: str("text") ?? "",
+		verified: typeof raw.verified === "boolean" ? raw.verified : null,
+		dismiss_reason: str("dismiss_reason") ?? null,
+		job_id: str("job_id", "jobId"),
+		session_id: str("session_id", "sessionId"),
+		claimed_by: str("claimed_by", "claimedBy"),
+		verified_reason: str("verified_reason", "verifiedReason"),
+		dismissed_at: str("dismissed_at"),
+		transcript: str("transcript"),
 	};
 }
 

package/src/job-edit.ts

@@ -19,7 +19,8 @@ export interface JobEdit {
 	thinking?: string | null;
 	timeoutMs?: number | null;
 	name?: string | null;
-	/** "here" pins the job to this machine; null lets any machine run it. */
+	/** The tools the job's turns run with; null clears the list (a plain job's turns then run uncapped, as its 0.22 turns did). */
+	tools?: string[] | null;
 	prompt?: string;
 	schedule?: Schedule;
 }
@@ -64,6 +65,11 @@ export function applyJobEdit(job: LoopJob, edit: JobEdit, ctx: JobEditContext):
 	if (edit.thinking !== undefined) patch.thinking = edit.thinking ?? undefined;
 	if (edit.timeoutMs !== undefined) patch.timeoutMs = edit.timeoutMs ?? undefined;
 	if (edit.name !== undefined) patch.name = edit.name ?? undefined;
+	if (edit.tools !== undefined) {
+		patch.tools = edit.tools ?? undefined;
+		// The old list is what the job's turns were capped to, and the edit is what uncapped them.
+		changed.push(`tools changed from ${job.tools ? job.tools.join(",") : "(none)"} to ${edit.tools ? edit.tools.join(",") : "(none)"}`);
+	}
 	if (edit.prompt !== undefined) {
 		patch.prompt = edit.prompt;
 		// The old wording is otherwise unrecoverable, and it is what ties "this loop started