@pi-unipi/kanboard 3.0.0-alpha.11 → 3.0.0-alpha.13

package/README.md

@@ -91,6 +91,7 @@ resume it or releases it to Todo.
 | `queueMax` | `10` | Tasks a session may queue (0 = unlimited); passed to the CLI as `UNIPI_KANBOARD_QUEUE_MAX` |
 | `maxSessions` | `2` | Distinct sessions running tasks per project (`UNIPI_KANBOARD_MAX_SESSIONS`) |
 | `turnAddLimit` | `20` | `add` calls allowed per -do turn or runner task (0 = unlimited) |
+| `reminders` | `true` | Progress reminders for hand-worked tasks: a steer on the first file-changing call while a mentioned task is still Todo (R1), and a follow-up at turn end while a started task is still In Progress (R2, max 2 per task). Text only, silent in runner runs |
 | *actions* | | `Open board…`, `Stop daemon`, `Summary agent command…`, `Rotate access token` |
 
 `Summary agent command…` writes through `settings set agent-command` and

package/index.ts

@@ -5,7 +5,9 @@
  * status/doctor — bare lists the commands), `/unipi:kanboard-add`,
  * `/unipi:kanboard-do` (opens the board-write window for one turn),
  * `/unipi:kanboard-autowork` (the runner loop: queue first, then claim-next).
- * The runner owns claim → In Progress and run-end → In Review. The board itself
+ * The runner owns claim → In Progress and run-end → In Review for queued work;
+ * an agent working a task by hand uses `start`/`finish` (free), nudged by the
+ * progress reminders (src/reminders.ts). The board itself
  * is written by the Rust binary (`crates/kanboard`); this extension never edits
  * task files. Bash calls into the binary are gated by the write window
  * (src/guard.ts): reads always pass, writes need a -do turn or a running task.
@@ -38,6 +40,8 @@ import {
   type CommandDeps,
 } from "./src/commands.js";
 import { createDebugLog, createRunner, registerPlanEventListener, type Runner } from "./src/runner.js";
+import { createProgressTracker, registerProgressReminders, sendReminder } from "./src/reminders.js";
+import { asTaskList } from "./src/shapes.js";
 import {
   ACTION_OPEN,
   ACTION_STOP_DAEMON,
@@ -56,6 +60,9 @@ export const KANBOARD_SKILL = "kanboard";
 export default function (pi: ExtensionAPI) {
   // One session id shared by the runner and the agent's bash calls.
   process.env.UNIPI_KANBOARD_SESSION ??= `pi-${process.pid}`;
+  // `start` claims belong to this pi process: the stale-claim reaper releases
+  // them to Todo when it dies (the agent's bash inherits the env).
+  process.env.UNIPI_KANBOARD_PID ??= String(process.pid);
   // Limits travel through the environment; refresh on load and before every
   // tool_call (see the guard registration in commands.ts).
   applyLimitEnv(readKanboardSettings());
@@ -140,6 +147,26 @@ export default function (pi: ExtensionAPI) {
   registerProgressRenderer(pi);
   registerKanboardCommands(pi, buildDeps());
 
+  // R1/R2 progress reminders for hand-worked tasks (silent in runner runs).
+  const reminders = registerProgressReminders(
+    pi,
+    createProgressTracker({
+      enabled: () => readKanboardSettings().reminders,
+      runnerOwned: () => (runner?.status().phase ?? "idle") !== "idle",
+      session: sessionId,
+      list: async () => {
+        const slug = projectSlug();
+        if (!cli || !slug) return [];
+        return asTaskList(await cli.run<unknown>(["list"], { extraEnv: { UNIPI_KANBOARD_PROJECT: slug } })).tasks;
+      },
+      cliPrefix: () => {
+        const slug = projectSlug();
+        return cli && slug ? `${cli.binary.path} --actor agent --project ${slug}` : null;
+      },
+      debug,
+    }),
+  );
+
   registerCommandRunner(ACTION_OPEN, async (ctx) => {
     const context = ctx as ExtensionContext | undefined;
     if (!context?.ui) return;
@@ -211,9 +238,13 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("agent_settled", async (_event, ctx) => {
-    if (!drainPending) return;
-    drainPending = false;
-    await drainQueueAfterDo(buildDeps(), ctx as unknown as ExtensionContext);
+    const reminder = reminders.takePending();
+    if (drainPending) {
+      drainPending = false;
+      await drainQueueAfterDo(buildDeps(), ctx as unknown as ExtensionContext);
+    }
+    // A drained queue hands the session to the runner: the reminder is moot.
+    if (reminder && (runner?.status().phase ?? "idle") === "idle") sendReminder(pi, reminder);
   });
 
   pi.on("session_shutdown", async (_event, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/kanboard",
-  "version": "3.0.0-alpha.11",
+  "version": "3.0.0-alpha.13",
   "description": "Kanboard v3 — deferred-work board: CLI/daemon bridge, task runner and skill",
   "type": "module",
   "main": "index.ts",
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.11"
+    "@pi-unipi/core": "3.0.0-alpha.13"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",
@@ -48,10 +48,10 @@
     "themes": []
   },
   "optionalDependencies": {
-    "@pi-unipi/kanboard-linux-x64": "3.0.0-alpha.11",
-    "@pi-unipi/kanboard-linux-arm64": "3.0.0-alpha.11",
-    "@pi-unipi/kanboard-darwin-x64": "3.0.0-alpha.11",
-    "@pi-unipi/kanboard-darwin-arm64": "3.0.0-alpha.11",
-    "@pi-unipi/kanboard-win32-x64": "3.0.0-alpha.11"
+    "@pi-unipi/kanboard-linux-x64": "3.0.0-alpha.13",
+    "@pi-unipi/kanboard-linux-arm64": "3.0.0-alpha.13",
+    "@pi-unipi/kanboard-darwin-x64": "3.0.0-alpha.13",
+    "@pi-unipi/kanboard-darwin-arm64": "3.0.0-alpha.13",
+    "@pi-unipi/kanboard-win32-x64": "3.0.0-alpha.13"
   }
 }

package/skills/kanboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kanboard
-description: "Kanboard — the project's deferred-work board. Use when the user asks to note a task for later, to see what is on the board, or while working a board task: read it with `unipi-kanboard show`, add notes, block with a question, or file follow-up work."
+description: "Kanboard — the project's deferred-work board. Use when the user asks to note a task for later, to see what is on the board, or to work board tasks (e.g. do UNI-5): `start` a task before working on it and `finish` it with a summary when done; while working a board task: read it with `unipi-kanboard show`, add notes, block with a question, or file follow-up work."
 ---
 
 # Kanboard
@@ -28,6 +28,8 @@ be on `PATH`):
 <binary> --actor agent --project <slug> edit <ID> --title|--body|--labels …   # only tasks you created, while in backlog/todo
 <binary> --actor agent --project <slug> edit <ID> --strategy none|goal|ralph|swarm|graph|auto  # how the runner works it (auto/unset = jev decides)
 <binary> --actor agent --project <slug> edit <ID> --plan yes|no|auto        # plan+approve first (auto/unset = jev decides)
+<binary> --actor agent --project <slug> start <ID>                          # todo → in progress, claimed for your session (free)
+<binary> --actor agent --project <slug> finish <ID> --comment "<summary>"   # in progress → in review, only a task you started (free)
 <binary> --actor agent --project <slug> move <ID> blocked --comment "<what you need>"
 <binary> --actor agent --project <slug> link <ID> --after <DEP>
 <binary> --actor agent --project <slug> unlink <ID> --after <DEP>
@@ -50,9 +52,9 @@ and `rotate-token` are user-only — the agent is refused.
 | Move | Who |
 |---|---|
 | backlog ↔ todo | user, agent |
-| todo → in progress | **the runner only** (`claim-next`) |
+| todo → in progress | the runner (`claim-next`), or the agent with `start <ID>` (claims it for its session) |
 | edit a task | agent — only tasks it created, and only in backlog/todo |
-| in progress → in review | **the runner only** (when your turn ends) |
+| in progress → in review | the runner (when a runner task's turn ends), or the agent with `finish <ID> --comment` — only a task its own session `start`ed |
 | in progress → blocked | agent, system — **comment required** (what you need) |
 | blocked → todo | user only — comment required (the answer) |
 | in review → done | user only |
@@ -70,8 +72,15 @@ lists them — read the files there directly if you need one.
 
 1. **Never pass `--actor user`.** That is an honour system: pretending to be the
    user to cancel a task or mark it done breaks the board's whole contract.
-2. **Never move a task to `in_review` or `done`.** The runner writes those when
-   your turn ends; claiming them yourself loses the summary and the review step.
+2. **Working a task by hand** (the user says "do UNI-5"): **`start` a task
+   before working on it, `finish` it with a summary when done** —
+   `start <ID>` before your first edit, `finish <ID> --comment "<what you did>"`
+   before your turn ends (or `move <ID> blocked --comment "<what you need>"` if
+   you cannot). Both are free and need no `/unipi:kanboard-do`. In Review means
+   "the agent did the work, a human reviews" — never leave a task you worked in
+   Todo or In Progress. You may have several tasks started. **Never move a task
+   to `done`**, and never `finish` a task the runner gave you: the runner writes
+   in_review for its own tasks when your turn ends (`finish` refuses them).
 3. **Never cancel.** If a task should be dropped, block it with
    `move <ID> blocked --comment "suggest cancel: <why>"` and let the user decide.
 4. **Follow the blocking rule in your task prompt**: by default work
@@ -85,9 +94,10 @@ lists them — read the files there directly if you need one.
    why. You may
    block only the task your own session is running (`move <ID> blocked` checks
    `--session`/`UNIPI_KANBOARD_SESSION` against the claim).
-6. **To have tasks worked during a `/unipi:kanboard-do` turn, queue them** with
-   `queue <IDs>` (Todo tasks, up to the queue limit — setting `queueMax`, default 10) — the runner starts them one by one
-   after the turn ends. Never claim or start them yourself.
+6. **To have tasks worked by the runner after a `/unipi:kanboard-do` turn, queue
+   them** with `queue <IDs>` (Todo tasks, up to the queue limit — setting
+   `queueMax`, default 10) — the runner starts them one by one after the turn
+   ends. Never `claim-next` yourself, and don't `start` a task you queued.
 7. Use `note <ID> "<text>"` for progress worth remembering (decisions, what you
    verified, what you left undone) — it is the activity log the next reader sees.
 8. Dependencies form a DAG: a task is ready only when every dep reached the chain
@@ -98,8 +108,9 @@ lists them — read the files there directly if you need one.
 ## Terminal-only execution
 
 The web UI can create, edit, reorder, link and move tasks, but it **never runs a
-task** — there is no run button. Work starts only from a terminal with
-`/unipi:kanboard-autowork start` (or the queue after a `/unipi:kanboard-do`). (The Done column's "Summarize & archive" does call the
+task** — there is no run button. Work starts only from a terminal: the runner
+(`/unipi:kanboard-autowork start`, or the queue after a `/unipi:kanboard-do`), or
+an agent that `start`s a task the user asked it to do. (The Done column's "Summarize & archive" does call the
 agent command set in the board's Settings, but only to write a summary.)
 
 ## Attachments

package/src/commands.ts

@@ -42,7 +42,7 @@ Priority -p: 1 none · 2 low · 3 medium · 4 high · 5 urgent`;
 
 export function doText(slug: string, cli: string, request: string, queueMax = 10, credits = 0): string {
   const limit = queueMax === 0 ? "Todo tasks" : `Todo tasks, at most ${queueMax}`;
-  return `[kanboard] For this request you may use the kanboard skill on project ${slug} (CLI: \`${cli} --actor agent --project ${slug} …\`). You have ${credits} write credit${credits === 1 ? "" : "s"} remaining this session — each board write (add, move, edit, note, link, order, queue) costs 1, reads are free; /unipi:kanboard-do tops the credits back up. You can add tasks, move them between backlog and todo, link, order, note, and edit tasks you created. To have tasks worked, queue them in order with \`queue <IDs>\` (${limit}); the runner starts them one by one after this turn, so do not start the work yourself. Read a task with \`show <ID>\` before editing, linking or queueing it — \`list\` only shows titles and a one-line excerpt. To choose how a task is worked, label it with \`edit <ID> --strategy none|goal|ralph|swarm|graph\` and \`--plan yes|no\`; leave it unset to let the runner decide. If the request is unclear, ask me instead of guessing.
+  return `[kanboard] For this request you may use the kanboard skill on project ${slug} (CLI: \`${cli} --actor agent --project ${slug} …\`). You have ${credits} write credit${credits === 1 ? "" : "s"} remaining this session — each board write (add, move, edit, note, link, order, queue) costs 1, reads are free; /unipi:kanboard-do tops the credits back up. You can add tasks, move them between backlog and todo, link, order, note, and edit tasks you created. To have tasks worked by the runner, queue them in order with \`queue <IDs>\` (${limit}); the runner starts them one by one after this turn. If you work a task yourself in this turn instead, \`start <ID>\` it before working on it and \`finish <ID> --comment "<summary>"\` it when done (both free) — never leave a task you worked in Todo or In Progress. Read a task with \`show <ID>\` before editing, linking or queueing it — \`list\` only shows titles and a one-line excerpt. To choose how a task is worked, label it with \`edit <ID> --strategy none|goal|ralph|swarm|graph\` and \`--plan yes|no\`; leave it unset to let the runner decide. If the request is unclear, ask me instead of guessing.
 
 Request: ${request}`;
 }

package/src/guard.ts

@@ -19,6 +19,13 @@ export const ADD_CAP_REASON = addCapReason(ADD_CAP);
 /** Subcommands that never write to the board. */
 const READONLY = new Set(["list", "show", "attachments", "next", "chain", "search", "status"]);
 
+/**
+ * Writes that cost nothing and need no -do window: `start`/`finish` only touch
+ * tasks the session claims itself (the binary enforces ownership), and the
+ * board should always show what is being worked.
+ */
+const FREE_WRITES = new Set(["start", "finish"]);
+
 /** Global flags that take a value; `--json` is the only valueless one. */
 const GLOBAL_VALUE_FLAGS = new Set(["--actor", "--project", "--gate", "--session"]);
 
@@ -60,6 +67,11 @@ export function kanboardInvocations(command: string): KanboardInvocation[] {
   return out;
 }
 
+/** A write that is free and allowed without a -do window (`start`, `finish`). */
+export function isFreeWrite(invocation: KanboardInvocation): boolean {
+  return FREE_WRITES.has(invocation.sub);
+}
+
 /** Read-only means: no writes, and the board does not change. */
 export function isReadonly(invocation: KanboardInvocation): boolean {
   if (READONLY.has(invocation.sub)) return true;
@@ -96,7 +108,7 @@ export interface WriteGuard {
 
 /**
  * Writes cost session credits (one per write subcommand in the command line);
- * reads are free and never blocked. A runner task keeps unlimited access
+ * reads and `start`/`finish` are free and never blocked. A runner task keeps unlimited access
  * (still add-capped). Credits persist across turns and follow-up questions
  * until spent; /unipi:kanboard-do tops up to N without stacking past N.
  */
@@ -149,7 +161,7 @@ export function createWriteGuard(
         lastTask = task;
       }
       for (const invocation of invocations) {
-        if (isReadonly(invocation)) continue;
+        if (isReadonly(invocation) || isFreeWrite(invocation)) continue;
         if (task !== null) {
           const cap = countAdd(invocation);
           if (cap) return cap;

package/src/reminders.ts

@@ -0,0 +1,284 @@
+/**
+ * @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,
+ * `finish <ID> --comment` hands it to In Review. Two text-only reminders keep
+ * that honest:
+ *
+ *   R1  the first file-changing tool call of an agent turn, while a mentioned
+ *       task is still Todo and this session has nothing started → a steer is
+ *       appended to that tool result (once per turn, at most twice per task).
+ *   R2  agent_end with a task this session started still In Progress → one
+ *       follow-up message (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. Both reminders are silent in
+ * runner-owned runs, in kanboard's own child sessions and when the setting
+ * `kanboard.reminders` is off.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { kanboardInvocations } from "./guard.js";
+import type { KanboardTask } from "./shapes.js";
+
+export const REMINDER_CUSTOM_TYPE = "unipi:kanboard-reminder";
+/** Reminders per task id (R1 and R2 each). */
+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",
+]);
+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.
+ */
+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 = trimmed.split(/&&|\|\||[;|\n]/).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"));
+    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 function r2Text(open: string[], cli: string | null): string {
+  const prefix = cli ? `${cli} ` : "";
+  const lines = open.map(
+    (id) =>
+      `${id} is still In Progress. If done: \`${prefix}finish ${id} --comment "<summary>"\`. ` +
+      `If not: say what remains, or \`${prefix}move ${id} blocked --comment "<what you need>"\`.`,
+  );
+  return `[kanboard] ${lines.join("\n")}\n${ANTI_POISONING_SUFFIX}`;
+}
+
+export interface TrackerDeps {
+  /** Reminders on (setting `kanboard.reminders`). */
+  enabled(): boolean;
+  /** The runner owns this turn (a queued/claimed task is running) → silent. */
+  runnerOwned(): 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>;
+  /** agent_end: the R2 text when due (the caller delivers it). */
+  onAgentEnd(event: { messages?: unknown[] }): Promise<string | null>;
+  /** For tests / status. */
+  state(): { mentioned: string[]; started: string[]; r1: Record<string, number>; r2: Record<string, number> };
+}
+
+function aborted(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";
+  }
+  return false;
+}
+
+function ownedStart(task: KanboardTask, session: string): boolean {
+  const run = task.run as { session?: string; owner?: string } | null | undefined;
+  return task.status === "in_progress" && run?.session === session && run?.owner === "agent";
+}
+
+export function createProgressTracker(deps: TrackerDeps): ProgressTracker {
+  const mentioned = new Set<string>();
+  /** Ids this session ran `start` on (candidates; the board is the truth). */
+  const started = new Set<string>();
+  const r1Count = new Map<string, number>();
+  const r2Count = new Map<string, number>();
+  let checkedThisTurn = false;
+  const debug = (message: string): void => deps.debug?.(`reminders: ${message}`);
+  const silent = (): boolean => !deps.enabled() || deps.runnerOwned() || 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, and a
+      // runner task prompt belongs to the runner. (A -do request counts: its
+      // text carries the user's request verbatim.)
+      if (text.includes(ANTI_POISONING_SUFFIX) || deps.runnerOwned()) return;
+      for (const id of taskIdsIn(text)) mentioned.add(id);
+    },
+
+    onTurnStart() {
+      checkedThisTurn = false;
+    },
+
+    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 (checkedThisTurn || !isFileChangingCall(toolName, event.input)) return undefined;
+      // Only the first file-changing call of the turn is considered.
+      checkedThisTurn = true;
+      if (silent() || mentioned.size === 0) return undefined;
+      const candidates = [...mentioned].filter((id) => (r1Count.get(id) ?? 0) < MAX_REMINDERS_PER_TASK);
+      if (candidates.length === 0) return undefined;
+      const tasks = await safeList();
+      if (!tasks) return undefined;
+      const session = deps.session();
+      if (tasks.some((task) => ownedStart(task, session))) 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) r1Count.set(id, (r1Count.get(id) ?? 0) + 1);
+      debug(`R1 for ${todo.join(", ")}`);
+      return { content: [...(event.content ?? []), { type: "text", text: `\n\n${r1Text(todo, deps.cliPrefix())}` }] };
+    },
+
+    async onAgentEnd(event) {
+      if (silent() || started.size === 0 || aborted(event.messages)) return null;
+      const tasks = await safeList();
+      if (!tasks) return null;
+      const session = deps.session();
+      const byId = new Map(tasks.map((task) => [task.id, task]));
+      const open: string[] = [];
+      for (const id of [...started]) {
+        const task = byId.get(id);
+        if (!task || !ownedStart(task, session)) {
+          started.delete(id); // finished, blocked, reaped or someone else's now
+          continue;
+        }
+        if ((r2Count.get(id) ?? 0) >= MAX_REMINDERS_PER_TASK) continue;
+        r2Count.set(id, (r2Count.get(id) ?? 0) + 1);
+        open.push(id);
+      }
+      if (open.length === 0) return null;
+      debug(`R2 for ${open.join(", ")}`);
+      return r2Text(open, deps.cliPrefix());
+    },
+
+    state() {
+      return {
+        mentioned: [...mentioned],
+        started: [...started],
+        r1: Object.fromEntries(r1Count),
+        r2: Object.fromEntries(r2Count),
+      };
+    },
+  };
+}
+
+/**
+ * Wire the tracker into pi's events. R2 is computed at agent_end and handed
+ * back through `takePending()`: the caller sends it at agent_settled — a
+ * message sent while the turn is still finalizing is queued as a follow-up
+ * that never gets delivered (same reason the -do queue drains there).
+ */
+export function registerProgressReminders(pi: ExtensionAPI, tracker: ProgressTracker): { takePending(): string | null } {
+  let pending: string | null = null;
+  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;
+  });
+  pi.on("agent_end", async (event) => {
+    pending = await tracker.onAgentEnd(event as { messages?: unknown[] });
+  });
+  return {
+    takePending() {
+      const text = pending;
+      pending = null;
+      return text;
+    },
+  };
+}
+
+/** Deliver an R2 reminder as a visible custom message that starts a turn. */
+export function sendReminder(pi: ExtensionAPI, text: string): void {
+  pi.sendMessage({ customType: REMINDER_CUSTOM_TYPE, content: text, display: true }, { triggerTurn: true });
+}

package/src/settings.ts

@@ -42,6 +42,9 @@ export interface KanboardSettings {
   /** Whether a blocked-by-confusion task may ask the user (ask) or must
    *  assume-and-note (avoid, the default). */
   blocking: "avoid" | "ask";
+  /** Progress reminders when the agent works board tasks by hand: `start`
+   *  before the first edit, `finish` (or block) before the turn ends. */
+  reminders: boolean;
 }
 
 export const DEFAULT_SETTINGS: KanboardSettings = {
@@ -62,6 +65,7 @@ export const DEFAULT_SETTINGS: KanboardSettings = {
   jevThreshold: 0.8,
   defaultPlan: false,
   blocking: "avoid",
+  reminders: true,
 };
 
 export const KANBOARD_NAMESPACE = "kanboard";
@@ -119,6 +123,12 @@ export function registerKanboardSettings(): void {
           { key: "queueMax", type: "number", label: "-do queue limit", min: 0, zeroLabel: "unlimited", description: "Tasks a session may queue for the runner" },
           { key: "maxSessions", type: "number", label: "Sessions working at once (per project)", min: 1, description: "Distinct sessions holding in_progress tasks" },
           { key: "turnAddLimit", type: "number", label: "New tasks per turn", min: 0, zeroLabel: "unlimited", description: "`add` calls allowed per -do turn or runner task" },
+          {
+            key: "reminders",
+            type: "boolean",
+            label: "Progress reminders",
+            description: "Remind the agent to `start` a mentioned Todo task before editing and to `finish` it before the turn ends (text only, never blocks; off in runner runs)",
+          },
           { key: "doCredits", type: "number", label: "-do write credits", min: 0, zeroLabel: "off", description: "Write credits a /unipi:kanboard-do grants; each board write costs 1, reads are free" },
         ],
       },
@@ -210,6 +220,7 @@ export function readKanboardSettings(cwd: string = process.cwd()): KanboardSetti
         : DEFAULT_SETTINGS.jevThreshold,
     defaultPlan: raw.defaultPlan === true,
     blocking: raw.blocking === "ask" ? "ask" : "avoid",
+    reminders: raw.reminders !== false,
   };
 }
 

package/src/shapes.ts

@@ -32,6 +32,8 @@ export interface KanboardRun {
   mode?: string;
   goal?: string | null;
   started?: string;
+  /** "system" (runner claim) or "agent" (`start` self-claim). */
+  owner?: string;
 }
 
 export interface KanboardActivity {