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

package/packages/kanboard/index.ts

@@ -2,40 +2,57 @@
  * @pi-unipi/kanboard — pi extension.
  *
  * Bridges the terminal to the board: `/unipi:kanboard` (open/close/onboard/
- * 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
- * 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.
+ * status/doctor/show — bare lists the commands), `/unipi:kanboard-add`,
+ * `/unipi:kanboard-do` (grants task slots + a write budget for one prompt),
+ * `/unipi:kanboard-autowork` (work every ready task in this session). The
+ * session works tasks itself — there is no runner. Continuation is the turn
+ * arbiter's job: src/monitor.ts proposes at most one nudge per settle (claims
+ * first, then the next ready autowork task). Bash calls into the Rust binary
+ * are gated by src/guard.ts: reads always pass, children never write, writes
+ * cost the -do budget (own-claim closes are free). The board itself is
+ * written by the binary; this extension never edits task files.
  */
 
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 import {
   MODULES,
   UNIPI_EVENTS,
   emitEvent,
   getPackageVersion,
+  getSettings,
+  getSharedKanboardStatus,
+  getSharedOwnerStatus,
   initUnipiDirs,
+  isChildProcess,
   registerCommandRunner,
-  getSettings,
+  registerEvidenceContributor,
+  registerNudgeProvider,
+  registerProgressRenderer,
+  setSharedKanboardStatus,
+  appendProgress,
 } from "@pi-unipi/core";
 
 import { openCli, type KanboardCli } from "./src/bin.js";
-import { createWriteGuard } from "./src/guard.js";
+import { kanboardInvocations } from "./src/guard.js";
+import { maybeBadgeToolResult, registerBadgeRenderer } from "./src/badges.js";
 import {
-  drainQueueAfterDo,
   registerKanboardCommands,
   runOpen,
   syncPiRuntime,
   runRotateTokenAction,
   runStopDaemon,
+  captureToBacklog,
   type CommandDeps,
 } from "./src/commands.js";
-import { createDebugLog, createRunner, registerPlanEventListener, type Runner } from "./src/runner.js";
+import { createWriteGuard } from "./src/guard.js";
+import { NOTICE_ENTRY, flushNotices, NoticeBuffer } from "./src/notice-buffer.js";
+import { createKanboardMonitor } from "./src/monitor.js";
+import { createDebugLog } from "./src/debug.js";
+import { createProgressTracker, registerProgressReminders, ANTI_POISONING_SUFFIX } from "./src/reminders.js";
+import { asTaskList, type KanboardTask } from "./src/shapes.js";
 import {
   ACTION_OPEN,
   ACTION_STOP_DAEMON,
@@ -52,8 +69,12 @@ export const SKILL_REVEAL_EVENT = "unipi:skills:reveal";
 export const KANBOARD_SKILL = "kanboard";
 
 export default function (pi: ExtensionAPI) {
-  // One session id shared by the runner and the agent's bash calls.
+  // One session id shared by the agent's bash calls (refined at session_start
+  // from the pi session id; children keep the value they inherited).
   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());
@@ -62,14 +83,11 @@ export default function (pi: ExtensionAPI) {
 
   let cli: KanboardCli | null = null;
   let unavailable: string | null = null;
-  let runner: Runner | null = null;
-  const guard = createWriteGuard(
-    () => {
-      const status = runner?.status();
-      return status?.phase === "running" ? status.taskId : null;
-    },
-    () => readKanboardSettings().turnAddLimit,
-  );
+  const guard = createWriteGuard({
+    addLimit: () => readKanboardSettings().turnAddLimit,
+    doTasks: () => readKanboardSettings().doTasks,
+    doWrites: () => readKanboardSettings().doWrites,
+  });
   const sessionId = (): string => process.env.UNIPI_KANBOARD_SESSION ?? `pi-${process.pid}`;
 
   const projectSlug = (): string => {
@@ -83,8 +101,87 @@ export default function (pi: ExtensionAPI) {
     }
   };
 
-  // Live getters: the command is registered before the binary is resolved, so
-  // the deps object must read the current state at call time.
+  // ── board reads (lead monitor/evidence/holder/notice) ────────────────
+  const listTasks = async (args: string[] = []): Promise<KanboardTask[]> => {
+    const client = cli;
+    const slug = projectSlug();
+    if (!client || !slug) return [];
+    const payload = await client.run<unknown>(["list", ...args, "--json"], {
+      extraEnv: { UNIPI_KANBOARD_PROJECT: slug, UNIPI_KANBOARD_SESSION: sessionId() },
+    });
+    return asTaskList(payload).tasks;
+  };
+  const ownClaims = async (): Promise<KanboardTask[]> => {
+    try {
+      const session = sessionId();
+      return (await listTasks()).filter((task) => {
+        const run = task.run as { session?: string } | null | undefined;
+        return task.status === "in_progress" && run?.session === session;
+      });
+    } catch {
+      return [];
+    }
+  };
+
+  // ── monitor: the arbiter's kanboard nudge provider (lead only) ───────
+  // User-only notices queue here and flush at agent_settled (post boundary).
+  const pendingNotices = new NoticeBuffer();
+  const monitor = createKanboardMonitor({
+    list: () => listTasks(),
+    listReady: () => listTasks(["--ready"]),
+    session: sessionId,
+    ownerStatus: () => getSharedOwnerStatus(),
+    now: () => Date.now(),
+    // User-only: only QUEUE here — a sendMessage custom message would be
+    // converted to a user-role LLM message (never what a notice wants).
+    // kanboard's agent_settled handler drains the buffer (appendEntry + toast).
+    notify: (text, level) => {
+      pendingNotices.queue(text, level);
+    },
+    // The monitor turned autowork off itself (done / stalled): the guard's
+    // budget and the footer's `▣ autowork` flag must follow.
+    onAutoworkOff: () => {
+      guard.setAutowork(false);
+      void refreshHolder();
+    },
+    cliPrefix: () => {
+      const slug = projectSlug();
+      return cli && slug ? `${cli.binary.path} --actor agent --project ${slug}` : null;
+    },
+    debug,
+  });
+
+  const refreshHolder = async (): Promise<void> => {
+    try {
+      setSharedKanboardStatus({
+        claims: (await ownClaims()).map((task) => task.id),
+        autowork: guard.remaining().autowork,
+      });
+    } catch {
+      // The footer simply shows nothing until the next refresh.
+    }
+  };
+
+  if (!isChildProcess()) {
+    try {
+      registerNudgeProvider("kanboard", 50, (info) => monitor.propose(info));
+    } catch {
+      // Registration must never block module load.
+    }
+    try {
+      registerEvidenceContributor("kanboard", async () => ({
+        blocking: (await ownClaims()).map(
+          (task) => `${task.id} is still In Progress (claimed by this session) — finish it or move it to blocked`,
+        ),
+        notes: [],
+      }));
+    } catch {
+      // Registration must never block module load.
+    }
+    registerBadgeRenderer(pi);
+  }
+
+  // ── command plumbing ─────────────────────────────────────────────────
   const buildDeps = (): CommandDeps => ({
       get cli() {
         return cli;
@@ -94,13 +191,16 @@ export default function (pi: ExtensionAPI) {
       },
       settings: () => readKanboardSettings(process.cwd()),
       revealSkill,
-      work: (ctx) => runner?.work(ctx) ?? Promise.resolve(),
-      stop: (ctx) => runner?.stop(ctx),
-      drainQueue: (ctx) => runner?.drain(ctx) ?? Promise.resolve(),
-      status: () => runner?.status() ?? { taskId: null, mode: null, phase: "idle" },
+      setAutowork: (on) => {
+        guard.setAutowork(on);
+        monitor.setAutowork(on);
+        if (on) monitor.arm("autowork");
+        void refreshHolder();
+      },
       guard,
       session: sessionId,
       debug,
+      progress: (data) => appendProgress(pi, data),
     }) as CommandDeps;
 
   const revealSkill = (ctx: ExtensionContext | { cwd?: string }): void => {
@@ -119,22 +219,33 @@ export default function (pi: ExtensionAPI) {
     cli = opened;
     unavailable = null;
     debug(`binary: ${opened.binary.path} (${opened.binary.source})`);
-    if (!runner) {
-      runner = createRunner({
-        pi,
-        cli,
-        project: projectSlug,
-        cwd: ctx.cwd,
-        settings: () => readKanboardSettings(ctx.cwd),
-        debug,
-      });
-      registerPlanEventListener(pi, runner);
-    }
     return true;
   };
 
+  registerProgressRenderer(pi);
   registerKanboardCommands(pi, buildDeps());
 
+  // ── API for other extensions (input-shortcuts K chord) ──────────────
+  // Add the editor text to this project's Backlog as a body-only task.
+  (globalThis as { __unipi_kanboard_api?: unknown }).__unipi_kanboard_api = {
+    captureToBacklog: (opts: { cwd: string; text: string }) => captureToBacklog(buildDeps(), opts),
+  };
+
+  // R1 progress reminders for hand-worked tasks (silent in child sessions).
+  registerProgressReminders(
+    pi,
+    createProgressTracker({
+      enabled: () => readKanboardSettings().reminders,
+      session: sessionId,
+      list: () => listTasks(),
+      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;
@@ -157,10 +268,78 @@ export default function (pi: ExtensionAPI) {
     await runRotateTokenAction(buildDeps(), context);
   });
 
+  // ── run hooks: monitor, badges, holder (lead only) ───────────────────
+  pi.on("before_agent_start", async (event) => {
+    try {
+      await monitor.onUserPrompt(String((event as { prompt?: unknown }).prompt ?? ""));
+    } catch {
+      // Prompt handling must never abort a turn.
+    }
+    return undefined;
+  });
+  pi.on("agent_start", () => {
+    try {
+      monitor.onAgentStart();
+    } catch {
+      // Accounting must never abort a turn.
+    }
+  });
+  pi.on("agent_end", async (event) => {
+    try {
+      guard.onAgentEnd();
+      monitor.onAgentEnd((event as { messages?: unknown[] }).messages);
+    } catch {
+      // Monitoring must never abort a turn.
+    }
+  });
+  // Post-boundary: entries append fine here (they are dropped inside the
+  // settle path), and the toast gives the notice a life outside the transcript.
+  pi.on("agent_settled", async (_event, ctx) => {
+    try {
+      const ui = ctx as unknown as { hasUI?: boolean; ui?: { notify?: (t: string, l?: string) => void } } | undefined;
+      flushNotices(
+        pi,
+        pendingNotices,
+        {
+          hasUI: ui?.hasUI,
+          notify: (text, level) => ui?.ui?.notify?.(text, level ?? "info"),
+        },
+        debug,
+      );
+      void refreshHolder();
+    } catch {
+      // The footer simply shows nothing until the next refresh.
+    }
+  });
+  pi.on("tool_result", async (event) => {
+    const toolEvent = event as { toolName?: string; input?: Record<string, unknown>; isError?: boolean };
+    try {
+      if (isChildProcess()) return undefined;
+      if (toolEvent.toolName !== "bash" && toolEvent.toolName !== "powershell") return undefined;
+      maybeBadgeToolResult(pi, String(toolEvent.toolName), toolEvent.input, toolEvent.isError === true);
+      if (toolEvent.isError) return undefined;
+      const invocations = kanboardInvocations(String(toolEvent.input?.command ?? ""));
+      if (invocations.some((inv) => inv.sub === "start" || inv.sub === "finish" || inv.sub === "move")) {
+        if (invocations.some((inv) => inv.sub === "start")) monitor.arm("start");
+        void refreshHolder();
+      }
+    } catch {
+      // Badges and holder refreshes must never abort a turn.
+    }
+    return undefined;
+  });
+
+  // ── session lifecycle ────────────────────────────────────────────────
   pi.on("session_start", async (_event, ctx) => {
     // Kanboard's own ambient children (summaries, --list-models) get this env:
     // they must not re-sync the runtime or spawn a daemon.
     if (process.env.UNIPI_KANBOARD_CHILD) return;
+    // Children keep the session id they inherited from the lead.
+    if (!isChildProcess()) {
+      // Step 0: reason is "startup" even for -c/-r — never branch on it.
+      process.env.UNIPI_KANBOARD_SESSION = `pi-${ctx.sessionManager.getSessionId()}`;
+      process.env.UNIPI_KANBOARD_PID = String(process.pid);
+    }
     initUnipiDirs();
     if (attach(ctx as unknown as ExtensionContext)) {
       const deps = buildDeps();
@@ -177,6 +356,50 @@ export default function (pi: ExtensionAPI) {
       debug(`unavailable: ${unavailable}`);
       return;
     }
+    // Reap claims whose pid died with the process (the runner used to do
+    // this): released tasks get the "session lost: <session>" activity the
+    // resume notice below keys on. The reaper acts as the system actor.
+    if (!isChildProcess()) {
+      try {
+        const reaped = await cli!.run<unknown>(["reap", "--json"], {
+          extraEnv: { UNIPI_KANBOARD_PROJECT: projectSlug(), UNIPI_KANBOARD_SESSION: sessionId() },
+        });
+        debug(`reap: ${JSON.stringify(reaped)}`);
+      } catch (error) {
+        debug(`reap failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    void refreshHolder();
+
+    // Resume notice: claims the reaper released when a previous run of THIS
+    // session died ("session lost: <session> …"), or that a shutdown released
+    // ("released: … session ended mid-task (<session>)"). Once per start.
+    // Activity entries are ordered oldest-first — the LAST one must be the
+    // release (a task that moved on afterwards is not news).
+    if (!isChildProcess()) {
+      try {
+        const session = sessionId();
+        const stale = (await listTasks()).filter((task) => {
+          if (task.status !== "todo") return false;
+          const last = task.activity?.at(-1);
+          if (!last) return false;
+          return (
+            last.text.startsWith(`session lost: ${session}`) ||
+            last.text.includes(`released: session ended mid-task (${session})`)
+          );
+        });
+        if (stale.length > 0) {
+          const ids = stale.map((task) => task.id).join(", ");
+          (ctx as unknown as { ui?: { notify?: (t: string, l?: string) => void } }).ui?.notify?.(
+            `kanboard: ${ids} was released when the last run ended — ask me to re-start it`,
+            "info",
+          );
+        }
+      } catch (error) {
+        debug(`resume notice failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+
     const client = cli!;
     const settings = readKanboardSettings(ctx.cwd);
     if (settings.archiveAfterDays > 0 || settings.retentionDays > 0) {
@@ -192,26 +415,41 @@ export default function (pi: ExtensionAPI) {
         .then((payload) => debug(`archive-sweep: ${JSON.stringify(payload)}`))
         .catch((error) => debug(`archive-sweep failed: ${error instanceof Error ? error.message : String(error)}`));
     }
-    await runner?.onSessionStart(ctx as unknown as ExtensionContext);
-  });
-
-  let drainPending = false;
-  pi.on("agent_end", async (event, ctx) => {
-    runner?.onAgentEnd(event as { messages?: unknown[] }, ctx as unknown as ExtensionContext);
-    // A -do window closes on the first real agent_end (the 150ms echo guard
-    // inside onAgentEnd skips the previous turn's late end). The drain itself
-    // runs at agent_settled: sending a task prompt while the turn is still
-    // finalizing would queue it as a follow-up that never gets delivered.
-    if (guard.onAgentEnd()) drainPending = true;
-  });
-
-  pi.on("agent_settled", async (_event, ctx) => {
-    if (!drainPending) return;
-    drainPending = false;
-    await drainQueueAfterDo(buildDeps(), ctx as unknown as ExtensionContext);
   });
 
   pi.on("session_shutdown", async (_event, ctx) => {
-    await runner?.onSessionShutdown(ctx as unknown as ExtensionContext);
+    // Release this session's open claims so the board shows the truth. The
+    // in_progress → todo transition allows the system actor only (the agent
+    // cannot release), and release requires a comment — the next run's resume
+    // notice keys on it. Best effort: a dead pid is reaped with "session
+    // lost" anyway.
+    // Children (subagents, fusion sidekicks, kanboard's own helpers) inherit
+    // the lead's session id: their shutdown must never release the lead's
+    // claims (a finished subagent used to bounce the lead's task to Todo).
+    if (isChildProcess() || process.env.UNIPI_KANBOARD_CHILD) return;
+    try {
+      const session = sessionId();
+      const claims = await ownClaims();
+      const client = cli;
+      const slug = projectSlug();
+      if (!client || !slug || claims.length === 0) return;
+      for (const task of claims) {
+        await client
+          .run([
+            "--actor", "system",
+            "--project", slug,
+            "release", task.id, "--to", "todo",
+            "--comment", `released: session ended mid-task (${session})`,
+          ], {
+            extraEnv: { UNIPI_KANBOARD_PROJECT: slug, UNIPI_KANBOARD_SESSION: session },
+          })
+          .then(() => debug(`released ${task.id} at shutdown`))
+          .catch((error) => debug(`shutdown release ${task.id} failed: ${error instanceof Error ? error.message : String(error)}`));
+      }
+      setSharedKanboardStatus({ claims: [], autowork: guard.remaining().autowork });
+    } catch {
+      // Shutdown must never hang the session teardown.
+    }
+    void ctx;
   });
 }

package/packages/kanboard/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@pi-unipi/kanboard",
-  "version": "3.0.0-alpha.2",
+  "version": "3.0.0-alpha.21",
   "description": "Kanboard v3 — deferred-work board: CLI/daemon bridge, task runner and skill",
   "type": "module",
   "main": "index.ts",
   "license": "MIT",
   "author": "Neuron Mr White",
   "scripts": {
-    "test": "npx tsx --test tests/**/*.test.ts"
+    "test": "UNIPI_FUSION_CHILD= UNIPI_SUBAGENT_CHILD= UNIPI_KANBOARD_CHILD= npx tsx --test tests/*.test.ts tests/*/*.test.ts"
   },
   "repository": {
     "type": "git",
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.2"
+    "@pi-unipi/core": "3.0.0-alpha.21"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",
@@ -48,10 +48,10 @@
     "themes": []
   },
   "optionalDependencies": {
-    "@pi-unipi/kanboard-linux-x64": "3.0.0-alpha.2",
-    "@pi-unipi/kanboard-linux-arm64": "3.0.0-alpha.2",
-    "@pi-unipi/kanboard-darwin-x64": "3.0.0-alpha.2",
-    "@pi-unipi/kanboard-darwin-arm64": "3.0.0-alpha.2",
-    "@pi-unipi/kanboard-win32-x64": "3.0.0-alpha.2"
+    "@pi-unipi/kanboard-linux-x64": "3.0.0-alpha.21",
+    "@pi-unipi/kanboard-linux-arm64": "3.0.0-alpha.21",
+    "@pi-unipi/kanboard-darwin-x64": "3.0.0-alpha.21",
+    "@pi-unipi/kanboard-darwin-arm64": "3.0.0-alpha.21",
+    "@pi-unipi/kanboard-win32-x64": "3.0.0-alpha.21"
   }
 }

package/packages/kanboard/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
@@ -16,27 +16,35 @@ Always pass the actor and the project, and call it by absolute path (it may not
 be on `PATH`):
 
 ```sh
-<binary> --actor agent --project <slug> list [--ready] [--json]
+<binary> --actor agent --project <slug> list [--ready] [--all] [--json]   # bare list = todo/in_progress/blocked/in_review/done only; --all adds backlog/cancelled/archived
 <binary> --actor agent --project <slug> show <ID>
-<binary> --actor agent --project <slug> next                     # what claim-next would pick + why
+<binary> --actor agent --project <slug> next                     # what would be picked next + why (read-only)
 <binary> --actor agent --project <slug> chain <ID>               # upstream deps + downstream dependents
 <binary> --actor agent --project <slug> search "<text>" [--all]  # id/title/body, archived excluded unless --all
 <binary> --actor agent --project <slug> add "<title>" [--status todo] [--after <ID>] [--body-file <f>] [--attach <file>]…
-<binary> --actor agent --project <slug> note <ID> "<text>"
+<binary> --actor agent --project <slug> note <ID> "<text>" [--attach <file>]…
 <binary> --actor agent --project <slug> attach <ID> <file> --note "<what it shows>"
 <binary> --actor agent --project <slug> attachments <ID>
 <binary> --actor agent --project <slug> edit <ID> --title|--body|--labels …   # only tasks you created, while in backlog/todo
-<binary> --actor agent --project <slug> move <ID> blocked --comment "<what you need>"
+<binary> --actor agent --project <slug> start <ID>                          # todo → in progress, claimed for your session (costs a -do slot)
+<binary> --actor agent --project <slug> finish <ID> --comment "<summary>" [--attach <file>]…   # in progress → in review, only a task you started (free)
+<binary> --actor agent --project <slug> move <ID> blocked --comment "<what you need>" [--attach <file>]…
 <binary> --actor agent --project <slug> link <ID> --after <DEP>
 <binary> --actor agent --project <slug> unlink <ID> --after <DEP>
 <binary> --actor agent --project <slug> order <ID> --top|--bottom|--before <ID>
-<binary> --actor agent --project <slug> queue <ID>… | queue --list            # your session's work queue (limit: setting queueMax, default 10)
-<binary> --actor agent --project <slug> unqueue [<ID>…]                      # no ids clears it
 ```
 
+There is **no queue and no runner** — the session works tasks itself
+(`/unipi:kanboard-autowork` just keeps offering the next ready task).
+`queue`, `unqueue`, `claim-next`, `set-run` and `edit --strategy/--plan` are
+removed and refused.
+
 `--json` gives machine-readable output for every subcommand (task objects carry
 `ready`, `waitingFor`, `depsStatus` and `staleness`).
 
+`list`/`search` show a one-line body excerpt; read a task's full description with
+`show <ID>` before editing or starting it.
+
 `settings show` reads the pi runtime and effective limits; `settings set`
 and `rotate-token` are user-only — the agent is refused.
 
@@ -45,10 +53,11 @@ 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 agent with `start <ID>` (claims it for its session; costs a `-do` slot) |
 | 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 agent with `finish <ID> --comment` — only a task its own session `start`ed |
 | in progress → blocked | agent, system — **comment required** (what you need) |
+| in progress → todo | user or system `release` — comment required (the session died or gave the task up) |
 | blocked → todo | user only — comment required (the answer) |
 | in review → done | user only |
 | in review → todo/backlog | user only — comment required (rework note) |
@@ -65,26 +74,45 @@ 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. **Work the tasks yourself, in this session** (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). `finish` and own-claim `blocked`/`note` are always
+   free; **`start` costs one of your `-do` task slots** — count the tasks a
+   request needs BEFORE starting anything, and if that is more than your
+   remaining slots, start none of them: say what you can do now and ask whether
+   to raise `kanboard.doTasks` or work in batches. In Review means "the agent
+   did the work, a human reviews" — never leave a task you started In Progress
+   (the board monitor will nudge you back to it). **Never move a task to
+   `done`.**
 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. **To ask the user something, block the task and stop**: `move <ID> blocked
-   --comment "<exactly what you need>"`. The answer arrives as a comment the next
-   time the task is claimed.
+4. **Follow the blocking rule in your task prompt**: by default work
+   autonomously and record assumptions with `note <ID> "assumed: <what/why>"`;
+   block (with a comment saying exactly what you need) only when you truly
+   cannot continue — `move <ID> blocked --comment "<what you need>"`.
 5. **Work only on the task you were given.** Follow-up work goes to the board as
    a new task in Backlog (`add "<title>"`), optionally `link <new> --after <ID>`.
-   A session holds one claim at a time, and at most `maxSessions` (default 2)
-   sessions may run tasks in a project — if the board refuses a claim, that is
-   why. You may
+   At most `maxSessions` (default 2) sessions may hold tasks in a project at
+   once — if the board refuses a `start`, that is 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. **Sidekicks and subagents can read the board but never write it** — every
+   write is refused with "board writes are the lead's job". Brief them with the
+   task, then update the board yourself from their reports. (The lead session
+   works tasks itself; `/unipi:kanboard-autowork` just keeps offering the next
+   ready task in the same session — there is no separate worker.)
 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
+8. **Write the `finish` / `blocked` comment as the report the user reads.** It
+   is shown as the task's status banner and opens in a reader, rendered as
+   markdown. Lead with one plain sentence (what you did, or what stops you),
+   then short paragraphs or `-` bullets separated by blank lines; put questions
+   for the user as a numbered list under `**Need from you:**`. Name files and
+   commands in backticks. Do not repeat a note you already wrote — the report
+   replaces it. Attach evidence with `--attach <file>`.
+9. Dependencies form a DAG: a task is ready only when every dep reached the chain
    gate (`in_review` by default, `done` when configured). Cancelled deps block
    forever, so unlink or re-plan instead of waiting. `chain <ID>` shows the
    whole line, `next` shows what would be picked and why others wait.
@@ -92,15 +120,21 @@ 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
-agent command set in the board's Settings, but only to write a summary.)
+task** — there is no run button. Work starts only from a terminal: the session
+itself, driven by `/unipi:kanboard-do` (a task-slot + write budget for one
+request) or `/unipi:kanboard-autowork` (the monitor keeps offering the next
+ready task in this session — no separate worker exists). (The Done column's
+"Summarize & archive" does call the agent command set in the board's Settings,
+but only to write a summary.)
 
 ## Attachments
 
 Users attach screenshots, logs and documents in the board UI; they appear in the
 text as markdown with `att:<ID>/<name>` references, and `show <ID> --json` lists
 them under `attachments` with an absolute `path` — read the file from there
-(use your image-reading tool for images). To hand back evidence, `attach` a file:
-it is stored beside the board and the comment embeds it, so the user sees the
-image or file inline.
+(use your image-reading tool for images). To hand back evidence (a screenshot,
+a log, a report), pass `--attach <file>` (repeatable) to `finish`, `move … blocked`
+or `note`, or use `attach <ID> <file> --note "…"`: the file is stored beside the
+board and the comment embeds it, so the user sees the image or file inline. A
+file's path written in the comment is replaced by the embed; otherwise the
+embed is appended. Attaching to a task you started is free.