@pi-unipi/kanboard 3.0.0-alpha.2 → 3.0.0-alpha.21

package/src/monitor.ts

@@ -0,0 +1,330 @@
+/**
+ * @pi-unipi/kanboard — the turn arbiter's kanboard nudge provider.
+ *
+ * Replaces the runner and the R2 reminder: when the lead settles with claims
+ * of its own still In Progress, the monitor proposes ONE continuation nudge
+ * (priority 50, claims; priority 40, autowork-next). The arbiter delivers at
+ * most one nudge per settle, so the monitor never fights the long-horizon
+ * owner (priority 100) or a pending event. Lead only — children never
+ * register it.
+ */
+
+import type { Nudge, SettleInfo } from "@pi-unipi/core";
+import { harnessMetadata, kanboardGlanceLabel } from "@pi-unipi/core";
+
+import { ANTI_POISONING_SUFFIX, taskIdsIn } from "./reminders.js";
+import type { KanboardTask } from "./shapes.js";
+
+export const CLAIMS_NUDGE_CUSTOM_TYPE = "unipi:kanboard-continue";
+export const AUTOWORK_NUDGE_CUSTOM_TYPE = "unipi:kanboard-next";
+export const CLAIMS_PRIORITY = 50;
+export const AUTOWORK_PRIORITY = 40;
+/** Hard cap of continuation nudges per task. */
+export const MAX_NUDGES_PER_TASK = 5;
+/** Consecutive nudged runs with zero tool calls before the monitor gives up. */
+export const STALL_LIMIT = 2;
+/** Offers of the SAME ready task before autowork gives up on it. */
+export const MAX_OFFERS_PER_TASK = 3;
+
+export interface MonitorDeps {
+	/** `list --json` on this session's project (board order). */
+	list(): Promise<KanboardTask[]>;
+	/** `list --ready --json` (todo tasks whose deps are met), board order. */
+	listReady(): Promise<KanboardTask[]>;
+	/** This session's id (UNIPI_KANBOARD_SESSION). */
+	session(): string;
+	/** Shared long-horizon owner status holder. */
+	ownerStatus(): { owner?: { kind: string; status: string }; lastStop?: { kind: string; at: number } } | undefined;
+	/** Wall clock (injectable in tests). */
+	now(): number;
+	/** User-only notices (never LLM context) — implementations must only queue. */
+	notify(text: string, level?: "info" | "warning"): void;
+	/** The monitor itself turned autowork off (done / stalled) — guard + holder follow. */
+	onAutoworkOff?(): void;
+	/** `<binary> --actor agent --project <slug>` for the nudge text, or null. */
+	cliPrefix(): string | null;
+	debug?(line: string): void;
+}
+
+export interface KanboardMonitor {
+	/** agent_start: the run that is about to start; stamps runStartedAt. */
+	onAgentStart(): void;
+	/** A user prompt: re-arm when it names one of our claimed ids. */
+	onUserPrompt(text: string): Promise<void>;
+	/** agent_end: an aborted or errored run disarms (kanboard never re-nudges after Esc). */
+	onAgentEnd(messages: unknown[] | undefined): void;
+	/** Arm the monitor (from -do, autowork start, or a successful lead `start`). */
+	arm(reason?: string): void;
+	disarm(): void;
+	setAutowork(on: boolean): void;
+	/** The nudge provider body (throws are caught by the arbiter, not here). */
+	propose(info: SettleInfo): Promise<Nudge | null>;
+	/** For tests / the status holder. */
+	state(): {
+		armed: boolean;
+		autowork: boolean;
+		nudgesPerTask: Record<string, number>;
+		noProgressRuns: number;
+	};
+}
+
+/** Last assistant message aborted or errored (Step 0 Q1d: stopReason). */
+function runFailed(messages: unknown[] | undefined): boolean {
+	if (!Array.isArray(messages)) return false;
+	for (let index = messages.length - 1; index >= 0; index -= 1) {
+		const message = messages[index] as { role?: string; stopReason?: string };
+		if (message?.role === "assistant") return message.stopReason === "aborted" || message.stopReason === "error";
+	}
+	return false;
+}
+
+/** The final non-empty paragraph of a text, trimmed. */
+function finalParagraph(text: string): string {
+	const paragraphs = text.trim().split(/\n\s*\n/).filter((part) => part.trim().length > 0);
+	return (paragraphs.at(-1) ?? "").trim();
+}
+
+function ownClaim(task: KanboardTask, session: string): boolean {
+	const run = task.run as { session?: string } | null | undefined;
+	return task.status === "in_progress" && run?.session === session;
+}
+
+/** Our own runtime texts never count as user prompts naming claimed ids. */
+function isOwnRuntimeText(text: string): boolean {
+	return (
+		text.includes(ANTI_POISONING_SUFFIX) ||
+		text.includes(CLAIMS_NUDGE_CUSTOM_TYPE) ||
+		text.includes(AUTOWORK_NUDGE_CUSTOM_TYPE)
+	);
+}
+
+export function createKanboardMonitor(deps: MonitorDeps): KanboardMonitor {
+	const debug = (line: string): void => deps.debug?.(`monitor: ${line}`);
+	let armed = false;
+	let autowork = false;
+	let runStartedAt = 0;
+	let lastRunWasNudge = false;
+	let nudgeDelivered = false;
+	let noProgressRuns = 0;
+	/** Continuation nudges per task id (delivered, not proposed). */
+	const nudgesPerTask = new Map<string, number>();
+	/** Autowork offers per ready task id (delivered; reset when it leaves ready). */
+	const offersPerTask = new Map<string, number>();
+	/** Notice dedupe per condition; cleared on re-arm. */
+	const notified = new Set<string>();
+	const notifyOnce = (key: string, text: string, level: "info" | "warning" = "info"): void => {
+		if (notified.has(key)) return;
+		notified.add(key);
+		deps.notify(text, level);
+	};
+	const autoworkOff = (why: string): void => {
+		autowork = false;
+		try {
+			deps.onAutoworkOff?.();
+		} catch {
+			// A broken callback must never break settlement.
+		}
+		debug(`autowork off (${why})`);
+	};
+	const disarmNow = (): void => {
+		if (armed) debug("disarmed");
+		armed = false;
+	};
+
+	const claimedFrom = (tasks: KanboardTask[]): KanboardTask[] => {
+		const session = deps.session();
+		return tasks.filter((task) => ownClaim(task, session));
+	};
+
+	return {
+		onAgentStart() {
+			// The run that just started was nudged iff the previous settle delivered.
+			lastRunWasNudge = nudgeDelivered;
+			nudgeDelivered = false;
+			runStartedAt = deps.now();
+		},
+
+		async onUserPrompt(text) {
+			if (isOwnRuntimeText(text)) return;
+			const named = taskIdsIn(text);
+			if (named.length === 0) return;
+			try {
+				const claimed = claimedFrom(await deps.list()).map((task) => task.id);
+				if (named.some((id) => claimed.includes(id))) {
+					armed = true;
+					notified.clear();
+					debug(`re-armed by user prompt naming ${claimed.join(", ")}`);
+				}
+			} catch (error) {
+				debug(`prompt re-arm list failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		},
+
+		onAgentEnd(messages) {
+			if (runFailed(messages)) {
+				// Esc (or a provider error): kanboard never re-nudges over the user.
+				disarmNow();
+			}
+		},
+
+		arm(reason) {
+			armed = true;
+			notified.clear();
+			debug(`armed${reason ? ` (${reason})` : ""}`);
+		},
+
+		disarm() {
+			disarmNow();
+		},
+
+		setAutowork(on) {
+			autowork = on;
+		},
+
+		async propose(info) {
+			if (!armed) return null;
+			let tasks: KanboardTask[];
+			try {
+				tasks = await deps.list();
+			} catch (error) {
+				debug(`list failed: ${error instanceof Error ? error.message : String(error)}`);
+				return null;
+			}
+			const claims = claimedFrom(tasks);
+
+			// A long-horizon owner drives continuation: kanboard stays quiet.
+			// An owner that STOPPED this run matters: complete → kanboard takes
+			// over again; paused/budget/other → tell the user what was left.
+			const owner = deps.ownerStatus();
+			if (owner?.owner?.status === "active") return null;
+			const stop = owner?.lastStop;
+			if (stop && stop.at >= runStartedAt && stop.kind !== "complete") {
+				if (claims.length > 0) {
+					const ids = claims.map((task) => task.id).join(", ");
+					const kindWord = stop.kind === "paused" ? "paused" : stop.kind === "budget" ? "hit its budget" : "stopped";
+					notifyOnce(
+						`goal-stop:${ids}`,
+						`kanboard: goal ${kindWord} — ${ids} left In Progress`,
+					);
+				}
+				disarmNow();
+				return null;
+			}
+
+			if (claims.length > 0) {
+				// Question heuristic: the agent ended by asking the user something —
+				// a nudge would talk over the question. Notice only, no count.
+				if (!info.lastAssistantHadToolCalls && finalParagraph(info.lastAssistantText).endsWith("?")) {
+					const ids = claims.map((task) => task.id).join(", ");
+					notifyOnce(`question:${ids}`, `kanboard: ${ids} left In Progress — the agent asked you a question`);
+					return null;
+				}
+				// Stall guard: nudged runs that did nothing.
+				if (lastRunWasNudge && info.toolCallsThisRun === 0) noProgressRuns += 1;
+				else if (info.toolCallsThisRun > 0) noProgressRuns = 0;
+				if (noProgressRuns >= STALL_LIMIT) {
+					const ids = claims.map((task) => task.id).join(", ");
+					notifyOnce(`stall:${ids}`, `kanboard: ⚠ ${ids} stalled — no progress after ${String(STALL_LIMIT)} nudges`, "warning");
+					disarmNow();
+					return null;
+				}
+				const rest = claims.slice(1).map((task) => task.id);
+				const target = claims.find((task) => (nudgesPerTask.get(task.id) ?? 0) < MAX_NUDGES_PER_TASK);
+				if (!target) {
+					const ids = claims.map((task) => task.id).join(", ");
+					notifyOnce(`cap:${ids}`, `kanboard: ⚠ ${ids} stalled — nudge cap (${String(MAX_NUDGES_PER_TASK)}) reached`, "warning");
+					disarmNow();
+					return null;
+				}
+				const n = (nudgesPerTask.get(target.id) ?? 0) + 1;
+				const prefix = deps.cliPrefix() ?? "unipi-kanboard";
+				const also = rest.length > 0 ? ` · also open: ${rest.join(", ")}` : "";
+				const content =
+					`↻ ${target.id} still In Progress — continue, or finish/block it (${String(n)}/${String(MAX_NUDGES_PER_TASK)})${also}\n` +
+					`\`${prefix} finish ${target.id} --comment "<summary>"\` / \`${prefix} move ${target.id} blocked --comment "<what you need>"\` ` +
+					ANTI_POISONING_SUFFIX;
+				return {
+					source: "kanboard",
+					priority: CLAIMS_PRIORITY,
+					customType: CLAIMS_NUDGE_CUSTOM_TYPE,
+					details: { unipiHarness: harnessMetadata({ source: "Kanboard", title: "Unfinished task", synopsis: String(target.id), severity: "warning" }, "boundary") },
+					content,
+					display: true,
+					onDelivered: () => {
+						nudgesPerTask.set(target.id, n); // counts on DELIVERY, not proposal
+						nudgeDelivered = true;
+					},
+				};
+			}
+
+			if (autowork) {
+				// The same stall rule as claims: an offered run that did nothing.
+				if (lastRunWasNudge && info.toolCallsThisRun === 0) noProgressRuns += 1;
+				else if (info.toolCallsThisRun > 0) noProgressRuns = 0;
+				if (noProgressRuns >= STALL_LIMIT) {
+					notifyOnce(
+						"autowork-stall",
+						`kanboard: ⚠ autowork stalled — no progress after ${String(STALL_LIMIT)} offers`,
+						"warning",
+					);
+					autoworkOff("stalled");
+					disarmNow();
+					return null;
+				}
+				let ready: KanboardTask[];
+				try {
+					ready = (await deps.listReady()).filter((task) => task.status === "todo");
+				} catch (error) {
+					debug(`listReady failed: ${error instanceof Error ? error.message : String(error)}`);
+					return null;
+				}
+				const next = ready[0];
+				if (next) {
+					// A task that left the ready list gets a fresh offer budget.
+					for (const id of [...offersPerTask.keys()]) {
+						if (!ready.some((task) => task.id === id)) offersPerTask.delete(id);
+					}
+					const offers = (offersPerTask.get(next.id) ?? 0) + 1;
+					if (offers > MAX_OFFERS_PER_TASK) {
+						notifyOnce(`autowork-cap:${next.id}`, `kanboard: ⚠ autowork stalled on ${next.id}`, "warning");
+						autoworkOff(`cap:${next.id}`);
+						disarmNow();
+						return null;
+					}
+					return {
+						source: "kanboard",
+						priority: AUTOWORK_PRIORITY,
+						customType: AUTOWORK_NUDGE_CUSTOM_TYPE,
+						details: { unipiHarness: harnessMetadata({ source: "Kanboard", title: "Next task", synopsis: String(next.id) }, "boundary") },
+						content: `↻ next ready: ${next.id} ${next.displayTitle || next.title || "(untitled)"} — show it, start it, work it (autowork) ${ANTI_POISONING_SUFFIX}`,
+						display: true,
+						onDelivered: () => {
+							offersPerTask.set(next.id, offers); // counts on DELIVERY, not proposal
+							nudgeDelivered = true;
+						},
+					};
+				}
+				const inReview = tasks.filter((task) => task.status === "in_review").length;
+				const blocked = tasks.filter((task) => task.status === "blocked").length;
+				notifyOnce("autowork-done", `kanboard: autowork done · ${String(inReview)} in review · ${String(blocked)} blocked`);
+				autoworkOff("done");
+				disarmNow();
+				return null;
+			}
+
+			return null;
+		},
+
+		state() {
+			return {
+				armed,
+				autowork,
+				nudgesPerTask: Object.fromEntries(nudgesPerTask),
+				noProgressRuns,
+			};
+		},
+	};
+}
+
+/** Glance label for the current claims/autowork snapshot (re-exported read). */
+export const monitorGlanceLabel = kanboardGlanceLabel;

package/src/notice-buffer.ts

@@ -0,0 +1,74 @@
+/**
+ * Kanboard monitor notices — user-only, never LLM context.
+ *
+ * The monitor proposes during the settle boundary, where `appendEntry` is
+ * dropped and a `sendMessage` custom message would be converted to a
+ * user-role LLM message (dist/core/messages.js `case "custom"`). So the
+ * monitor only QUEUES text here; kanboard's `agent_settled` handler (post
+ * boundary) drains it via `flushNotices`: an `appendEntry` custom entry
+ * (rendered by the entry renderer, transcript-only) plus a UI toast.
+ */
+
+export type NoticeLevel = "info" | "warning";
+
+export interface NoticeItem {
+	text: string;
+	level: NoticeLevel;
+}
+
+export const NOTICE_ENTRY = "unipi:kanboard-notice";
+
+export class NoticeBuffer {
+	private items: NoticeItem[] = [];
+
+	queue(text: string, level: NoticeLevel = "info"): void {
+		this.items.push({ text, level });
+	}
+
+	/** Return everything queued (newest last) and clear the buffer. */
+	drain(): NoticeItem[] {
+		return this.items.splice(0);
+	}
+
+	get pending(): number {
+		return this.items.length;
+	}
+}
+
+export interface NoticeFlushPi {
+	/** Custom entries are transcript-only — never serialized into LLM context. */
+	appendEntry(customType: string, data?: unknown): void;
+}
+
+export interface NoticeFlushUi {
+	hasUI?: boolean;
+	notify?(text: string, level?: NoticeLevel): void;
+}
+
+/**
+ * Drain the buffer: one appendEntry per notice (user-only entry) and, when a
+ * dialog-capable UI is attached, a toast. Never sends a message. appendEntry
+ * failures are reported to `debug` (the toast still fires, so a notice is
+ * never lost even if entries are dropped in odd phases).
+ */
+export function flushNotices(
+	pi: NoticeFlushPi,
+	buffer: NoticeBuffer,
+	ui?: NoticeFlushUi,
+	debug?: (line: string) => void,
+): void {
+	for (const item of buffer.drain()) {
+		try {
+			pi.appendEntry(NOTICE_ENTRY, { text: item.text, level: item.level });
+		} catch (error) {
+			debug?.(`appendEntry dropped: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (ui?.hasUI !== false) {
+			try {
+				ui?.notify?.(item.text, item.level);
+			} catch {
+				// A failed toast must never break settlement.
+			}
+		}
+	}
+}

package/src/progress.ts

@@ -0,0 +1,27 @@
+/**
+ * Board progress bar (user-only entry):
+ *   ▣ Board · unipi  ██████████▒▒░░░░░░░░  5/10 tasks  1 blocked
+ * Solid = in review + done, shade = in progress, light = todo + blocked.
+ * Backlog, cancelled and archived tasks are outside the bar.
+ */
+
+import type { ProgressData } from "@pi-unipi/core";
+
+const COUNTED = new Set(["todo", "in_progress", "in_review", "done", "blocked"]);
+
+export function boardProgressData(tasks: ReadonlyArray<{ status: string }>, slug: string): ProgressData | undefined {
+  const counted = tasks.filter((t) => COUNTED.has(t.status));
+  if (counted.length === 0) return undefined;
+  const n = (s: string) => counted.filter((t) => t.status === s).length;
+  const blocked = n("blocked");
+  return {
+    icon: "▣",
+    label: slug ? `Board · ${slug}` : "Board",
+    done: n("in_review") + n("done"),
+    active: n("in_progress"),
+    total: counted.length,
+    unit: "tasks",
+    detail: blocked > 0 ? `${String(blocked)} blocked` : undefined,
+    color: "success",
+  };
+}

package/src/reminders.ts

@@ -0,0 +1,234 @@
+/**
+ * @pi-unipi/kanboard — progress reminders (no LLM, never blocking).
+ *
+ * When the agent works board tasks by hand ("do UNI-5 and UNI-8"), the board
+ * should show it: `start <ID>` moves a task to In Progress for this session.
+ * Continuation after that is the arbiter's job (src/monitor.ts); what stays
+ * here is:
+ *
+ *   R1  every file-changing tool call of an agent turn, for each mentioned
+ *       task that is still Todo and has not been reminded this turn (one
+ *       steer per task per turn, at most twice per task).
+ *
+ * "Mentioned" = task ids in the user's prompts plus ids the agent `show`ed;
+ * only ids that exist on the board count. R1 is silent in child sessions
+ * (children only read the board) and when the setting `kanboard.reminders`
+ * is off.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isChildProcess, harnessToolResultDetails } from "@pi-unipi/core";
+
+import { kanboardInvocations, shellSegments } from "./guard.js";
+import type { KanboardTask } from "./shapes.js";
+
+export const REMINDER_CUSTOM_TYPE = "unipi:kanboard-reminder";
+/** R1 reminders per task id. */
+export const MAX_REMINDERS_PER_TASK = 2;
+
+/** Same wording long-horizon's runaway guard uses: the reminder must not stick. */
+export const ANTI_POISONING_SUFFIX =
+  "This is a temporary runtime reminder for the current Turn only, not a user preference " +
+  "or a durable rule; do not save this reminder or generalize it into Memory, Skills, or " +
+  "other persistent instruction files.";
+
+/** Board task ids: PREFIX-123 (the prefix is letters/digits, starting with a letter). */
+const TASK_ID = /\b[A-Z][A-Z0-9]{0,15}-\d+\b/g;
+
+/** Tools that change files. bash/powershell count unless the command only reads. */
+const EDIT_TOOLS = new Set(["edit", "write", "multi_edit", "multiedit", "apply_patch", "notebook_edit"]);
+const SHELL_TOOLS = new Set(["bash", "powershell"]);
+
+/** First words of shell segments that never change files. */
+const READ_COMMANDS = new Set([
+  "ls", "pwd", "cat", "head", "tail", "wc", "echo", "printf", "which", "type", "rg", "grep", "egrep",
+  "fgrep", "find", "fd", "stat", "file", "du", "df", "env", "printenv", "date", "whoami", "tree", "less",
+  "more", "true", "false", "test", "[", "diff", "cmp", "jq", "realpath", "dirname", "basename", "uname",
+  "hostname", "id", "ps", "cd",
+]);
+/** Interpreters/package managers whose version-check arms never write. */
+const VERSION_CHECKED = new Set(["node", "npm", "npx", "python", "python3"]);
+const isVersionFlag = (word: string): boolean => word === "--version" || word === "-v" || word === "-V";
+const GIT_READS = new Set(["status", "log", "diff", "show", "branch", "remote", "rev-parse", "blame", "ls-files", "describe", "tag"]);
+
+export function taskIdsIn(text: string): string[] {
+  return [...new Set(text.match(TASK_ID) ?? [])];
+}
+
+/**
+ * Whether a shell command may change files. Conservative toward "yes": any
+ * segment that is not a known read (or a kanboard CLI call) counts, and so
+ * does an output redirection. Quoted spans are masked before both the
+ * redirect test and the segment split, so `grep -c "a;b" f` stays one
+ * read-only segment.
+ */
+export function shellChangesFiles(command: string): boolean {
+  const trimmed = command.trim();
+  if (!trimmed) return false;
+  // `>`/`>>` into a file (but not `2>&1` / `>/dev/null`).
+  if (/(^|[^0-9&>])>{1,2}\s*(?!&|\/dev\/null)[^\s|;&]/.test(trimmed.replace(/(["'])(?:\\.|(?!\1).)*\1/g, '""'))) return true;
+  const segments = shellSegments(trimmed).map((part) => part.trim()).filter(Boolean);
+  return segments.some((segment) => {
+    const words = segment.split(/\s+/).filter((word) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(word));
+    const first = (words[0] ?? "").replace(/^.*\//, "");
+    if (!first) return false;
+    // Board writes go through the binary, not files.
+    if (/^unipi-kanboard(\.exe)?$/.test(first)) return false;
+    if (READ_COMMANDS.has(first)) return false;
+    if (first === "git") return !GIT_READS.has(words[1] ?? "");
+    if (first === "sed") return words.includes("-i") || words.some((word) => word.startsWith("-i"));
+    // `sort` writes only through -o/--output (a `>` redirect is caught above).
+    if (first === "sort") return words.some((word) => /^-[^-]*o/.test(word) || word.startsWith("--output"));
+    // node/npm/npx/python are reads only as version checks (`node --version`,
+    // `npx tsx --version`); scripts, installs and builds still count.
+    if (VERSION_CHECKED.has(first)) return !words.slice(1).some(isVersionFlag);
+    return true;
+  });
+}
+
+export function isFileChangingCall(toolName: string, input: Record<string, unknown> | undefined): boolean {
+  if (EDIT_TOOLS.has(toolName)) return true;
+  if (!SHELL_TOOLS.has(toolName)) return false;
+  return shellChangesFiles(String(input?.command ?? ""));
+}
+
+export function r1Text(todo: string[], cli: string | null): string {
+  const ids = todo.join(", ");
+  const verb = todo.length === 1 ? "is" : "are";
+  const how = cli ? `\`${cli} start <ID>\`` : "`start <ID>`";
+  return (
+    `[kanboard] ${ids} ${verb} still Todo. ${how} the one you're on before changing files ` +
+    `(it moves it to In Progress for this session), and \`finish <ID> --comment "<summary>"\` when done. ` +
+    ANTI_POISONING_SUFFIX
+  );
+}
+
+export interface TrackerDeps {
+  /** Reminders on (setting `kanboard.reminders`). */
+  enabled(): boolean;
+  /** This session's id (UNIPI_KANBOARD_SESSION). */
+  session(): string;
+  /** `list` on the current project; [] when unavailable. */
+  list(): Promise<KanboardTask[]>;
+  /** `<binary> --actor agent --project <slug>` for the reminder text, or null. */
+  cliPrefix(): string | null;
+  debug?(message: string): void;
+}
+
+type ToolResultContent = Array<{ type: string; text?: string; [key: string]: unknown }>;
+
+export interface ToolResultLike {
+  toolName?: string;
+  input?: Record<string, unknown>;
+  content?: ToolResultContent;
+  isError?: boolean;
+}
+
+export interface ProgressTracker {
+  /** A user prompt (or -do request): remember the task ids it names. */
+  onPrompt(text: string): void;
+  /** A new agent turn (agent_start): re-arm R1. */
+  onTurnStart(): void;
+  /** tool_result: record `show`/`start`, and return R1 content when due. */
+  onToolResult(event: ToolResultLike): Promise<{ content: ToolResultContent } | undefined>;
+  /** For tests / status. */
+  state(): { mentioned: string[]; started: string[]; r1: Record<string, number> };
+}
+
+export function createProgressTracker(deps: TrackerDeps): ProgressTracker {
+  const mentioned = new Set<string>();
+  /** Ids this session ran `start` on (bookkeeping; the board is the truth). */
+  const started = new Set<string>();
+  const r1Count = new Map<string, number>();
+  /** Task ids already reminded this turn (per-task re-arm, not one shot). */
+  const remindedThisTurn = new Set<string>();
+  const debug = (message: string): void => deps.debug?.(`reminders: ${message}`);
+  const silent = (): boolean => !deps.enabled() || isChildProcess() || Boolean(process.env.UNIPI_KANBOARD_CHILD);
+
+  const safeList = async (): Promise<KanboardTask[] | null> => {
+    try {
+      return await deps.list();
+    } catch (error) {
+      debug(`list failed: ${error instanceof Error ? error.message : String(error)}`);
+      return null;
+    }
+  };
+
+  return {
+    onPrompt(text) {
+      // Our own reminders name started tasks; they are not new mentions. (A
+      // -do request counts: its text carries the user's request verbatim.)
+      if (text.includes(ANTI_POISONING_SUFFIX)) return;
+      for (const id of taskIdsIn(text)) mentioned.add(id);
+    },
+
+    onTurnStart() {
+      remindedThisTurn.clear();
+    },
+
+    async onToolResult(event) {
+      const toolName = String(event.toolName ?? "");
+      if (SHELL_TOOLS.has(toolName)) {
+        for (const invocation of kanboardInvocations(String(event.input?.command ?? ""))) {
+          const id = invocation.args.find((arg) => !arg.startsWith("-"));
+          if (!id) continue;
+          if (invocation.sub === "show") mentioned.add(id);
+          if (invocation.sub === "start" && !event.isError) started.add(id);
+
+        }
+      }
+      if (!isFileChangingCall(toolName, event.input)) return undefined;
+      if (silent() || mentioned.size === 0) return undefined;
+      // Per task, at most once per turn: candidates are mentioned ids not yet
+      // reminded this turn and under the per-task cap (a started task leaves
+      // Todo and is never re-reminded).
+      const candidates = [...mentioned].filter(
+        (id) => !remindedThisTurn.has(id) && (r1Count.get(id) ?? 0) < MAX_REMINDERS_PER_TASK,
+      );
+      if (candidates.length === 0) return undefined;
+      const tasks = await safeList();
+      if (!tasks) return undefined;
+      const byId = new Map(tasks.map((task) => [task.id, task]));
+      const todo = candidates.filter((id) => byId.get(id)?.status === "todo");
+      if (todo.length === 0) return undefined;
+      for (const id of todo) {
+        remindedThisTurn.add(id);
+        r1Count.set(id, (r1Count.get(id) ?? 0) + 1);
+      }
+      debug(`R1 for ${todo.join(", ")}`);
+      const annotation = `\n\n${r1Text(todo, deps.cliPrefix())}`;
+      return {
+        content: [...(event.content ?? []), { type: "text", text: annotation }],
+        details: harnessToolResultDetails(
+          (event as { details?: unknown }).details,
+          { source: "Kanboard", title: "R1 progress reminder", synopsis: `${todo.join(", ")} still Todo`, severity: "warning" },
+          "boundary",
+          annotation,
+        ),
+      };
+    },
+
+    state() {
+      return {
+        mentioned: [...mentioned],
+        started: [...started],
+        r1: Object.fromEntries(r1Count),
+      };
+    },
+  };
+}
+
+/** Wire the tracker into pi's events. */
+export function registerProgressReminders(pi: ExtensionAPI, tracker: ProgressTracker): void {
+  pi.on("before_agent_start", (event) => {
+    tracker.onPrompt(String((event as { prompt?: unknown }).prompt ?? ""));
+    return undefined;
+  });
+  pi.on("agent_start", () => {
+    tracker.onTurnStart();
+  });
+  pi.on("tool_result", async (event) => {
+    const result = await tracker.onToolResult(event as unknown as ToolResultLike);
+    return result as never;
+  });
+}