@pi-unipi/unipi 3.0.0-alpha.8 → 3.0.0-alpha.9

package/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [3.0.0-alpha.9] — 2026-09-29
+
+### Added
+- `long-horizon`: `/unipi:goal|swarm|graph stop` — terminally ends the active owner (goal → `complete(user_requested)`; pending proposal discarded; no further continuation follow-up). `/unipi:clear` on an active owner now points at stop instead of silently doing nothing.
+- `long-horizon`: `/unipi:regular` — stops any active owner (incl. ralph loops) and pins the session to plain mode; an explicit mode command unlatches it.
+- `long-horizon`: command runners `unipi:goal-pause` / `unipi:goal-resume` / `unipi:goal-stop` for cross-module callers.
+- `kanboard`: `/unipi:kanboard-do` grants session **write credits** (setting `kanboard.doCredits`, default 10) instead of a turn-scoped window — credits persist across turns, each board write costs 1, reads stay free, runner tasks keep unlimited access, `off` revokes.
+
+### Changed
+- `long-horizon`: verifier resilience — evaluator failures retry once, then pause `paused(verifier_unavailable)`; two consecutive inconclusive verdicts pause `paused(verifier_inconclusive)`; five consecutive `not_met` claims pause unconditionally (stall-cap coupling removed). Paused goals park the owner so `/unipi:goal resume` works.
+- `long-horizon`: tokens — provider usage now read in both pi shapes (`{input, output, …}` and `{inputTokens, outputTokens}`); usage-less turns estimate tokens (chars/4) and flag `tokens_estimated` in `get_goal` and the continuation hint.
+- `long-horizon`: no-progress guard keys "identical arguments" on real tool arguments (captured per `toolCallId`), exempts search no-matches, `get_goal`/`update_goal`, and kanboard reads — no more false "ran 3 times with identical arguments" after three different commands.
+- `kanboard`: an interrupted/released task parks its goal (id recorded in the release note) and resumes it on re-claim; a user-stopped goal releases the task to Todo ("goal stopped by user") instead of In Review; a task cancelled outside the runner stops its goal.
+- `kanboard`: `-do` suggestions only for task-id-like tokens (no more task rows under free prose).
 ## [3.0.0-alpha.7] — 2026-09-28
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "3.0.0-alpha.8",
+  "version": "3.0.0-alpha.9",
   "description": "All-in-one extension suite for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -83,26 +83,26 @@
     "typebox": "^1.1.38"
   },
   "dependencies": {
-    "@pi-unipi/ask-user": "3.0.0-alpha.8",
-    "@pi-unipi/background-tasks": "3.0.0-alpha.8",
-    "@pi-unipi/btw": "3.0.0-alpha.8",
-    "@pi-unipi/command-enchantment": "3.0.0-alpha.8",
-    "@pi-unipi/compactor": "3.0.0-alpha.8",
-    "@pi-unipi/core": "3.0.0-alpha.8",
-    "@pi-unipi/footer": "3.0.0-alpha.8",
-    "@pi-unipi/fusion": "3.0.0-alpha.8",
-    "@pi-unipi/info-screen": "3.0.0-alpha.8",
-    "@pi-unipi/input-shortcuts": "3.0.0-alpha.8",
-    "@pi-unipi/kanboard": "3.0.0-alpha.8",
-    "@pi-unipi/mcp": "3.0.0-alpha.8",
-    "@pi-unipi/memory": "3.0.0-alpha.8",
-    "@pi-unipi/notify": "3.0.0-alpha.8",
-    "@pi-unipi/skill-registry": "3.0.0-alpha.8",
-    "@pi-unipi/subagents": "3.0.0-alpha.8",
-    "@pi-unipi/updater": "3.0.0-alpha.8",
-    "@pi-unipi/utility": "3.0.0-alpha.8",
-    "@pi-unipi/web-api": "3.0.0-alpha.8",
-    "@pi-unipi/workflow": "3.0.0-alpha.8"
+    "@pi-unipi/ask-user": "3.0.0-alpha.9",
+    "@pi-unipi/background-tasks": "3.0.0-alpha.9",
+    "@pi-unipi/btw": "3.0.0-alpha.9",
+    "@pi-unipi/command-enchantment": "3.0.0-alpha.9",
+    "@pi-unipi/compactor": "3.0.0-alpha.9",
+    "@pi-unipi/core": "3.0.0-alpha.9",
+    "@pi-unipi/footer": "3.0.0-alpha.9",
+    "@pi-unipi/fusion": "3.0.0-alpha.9",
+    "@pi-unipi/info-screen": "3.0.0-alpha.9",
+    "@pi-unipi/input-shortcuts": "3.0.0-alpha.9",
+    "@pi-unipi/kanboard": "3.0.0-alpha.9",
+    "@pi-unipi/mcp": "3.0.0-alpha.9",
+    "@pi-unipi/memory": "3.0.0-alpha.9",
+    "@pi-unipi/notify": "3.0.0-alpha.9",
+    "@pi-unipi/skill-registry": "3.0.0-alpha.9",
+    "@pi-unipi/subagents": "3.0.0-alpha.9",
+    "@pi-unipi/updater": "3.0.0-alpha.9",
+    "@pi-unipi/utility": "3.0.0-alpha.9",
+    "@pi-unipi/web-api": "3.0.0-alpha.9",
+    "@pi-unipi/workflow": "3.0.0-alpha.9"
   },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.87.1",

package/packages/ask-user/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ask-user",
-  "version": "3.0.0-alpha.8",
+  "version": "3.0.0-alpha.9",
   "description": "Structured user input tool for Pi coding agent — single-select, multi-select, freeform",
   "type": "module",
   "main": "index.ts",
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.8"
+    "@pi-unipi/core": "3.0.0-alpha.9"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",

package/packages/autocomplete/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/command-enchantment",
-  "version": "3.0.0-alpha.8",
+  "version": "3.0.0-alpha.9",
   "description": "Enhanced TUI autocomplete for /unipi:* commands — colored, sorted, and grouped by package",
   "type": "module",
   "main": "src/index.ts",

package/packages/autocomplete/src/constants.ts

@@ -42,11 +42,12 @@ export const COMMAND_REGISTRY: Record<string, string> = {
   "unipi:plan":           "workflow",
   "unipi:permission":     "workflow",
 
-  // long-horizon (4 commands)
+  // long-horizon (5 commands)
   "unipi:goal":           "long-horizon",
   "unipi:ralph":          "long-horizon",
   "unipi:swarm":          "long-horizon",
   "unipi:graph":          "long-horizon",
+  "unipi:regular":        "long-horizon",
 
   // memory (7 commands)
   "unipi:memory":              "memory",
@@ -140,6 +141,7 @@ export const COMMAND_DESCRIPTIONS: Record<string, string> = {
   "unipi:ralph":          "Checklist grind over iterations · enumerable chores · low cost, solid success",
   "unipi:swarm":          "Parallel fan-out + synthesis · complex decomposable · higher cost, high coverage",
   "unipi:graph":          "Dependent multi-step work · later steps need earlier results · highest cost",
+  "unipi:regular":        "Regular mode — stop the active owner and run prompts without long-horizon routing",
 
   "unipi:memory":             "Memory palace — status, migrate, recall/write toggles",
   "unipi:memory-process":     "Analyze text and store extracted memories",

package/packages/background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/background-tasks",
-  "version": "3.0.0-alpha.8",
+  "version": "3.0.0-alpha.9",
   "description": "Background tasks for UniPi — durable shell jobs and delegated background agents with a footer dock",
   "type": "module",
   "main": "src/index.ts",
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-ai": "^0.87.1",
-    "@pi-unipi/core": "3.0.0-alpha.8",
+    "@pi-unipi/core": "3.0.0-alpha.9",
     "turndown": "^7.2.4"
   },
   "devDependencies": {

package/packages/btw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/btw",
-  "version": "3.0.0-alpha.8",
+  "version": "3.0.0-alpha.9",
   "description": "A pi extension for parallel side conversations with /unipi:btw — part of the Unipi suite",
   "type": "module",
   "main": "extensions/btw.ts",
@@ -37,7 +37,7 @@
     "@earendil-works/pi-tui": "^0.87.1"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.8"
+    "@pi-unipi/core": "3.0.0-alpha.9"
   },
   "pi": {
     "extensions": [

package/packages/compactor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/compactor",
-  "version": "3.0.0-alpha.8",
+  "version": "3.0.0-alpha.9",
   "description": "Compaction for Pi — lossless zero-LLM or model summaries, rebuilt from full history, with session recall",
   "type": "module",
   "main": "src/index.ts",
@@ -33,8 +33,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.8",
-    "@pi-unipi/info-screen": "3.0.0-alpha.8",
+    "@pi-unipi/core": "3.0.0-alpha.9",
+    "@pi-unipi/info-screen": "3.0.0-alpha.9",
     "@earendil-works/pi-agent-core": "^0.87.1"
   },
   "peerDependencies": {

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/core",
-  "version": "3.0.0-alpha.8",
+  "version": "3.0.0-alpha.9",
   "description": "Shared utilities, event types, and constants for Unipi extension suite",
   "type": "module",
   "license": "MIT",

package/packages/footer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/footer",
-  "version": "3.0.0-alpha.8",
+  "version": "3.0.0-alpha.9",
   "description": "Persistent status bar for Unipi — subscribes to UNIPI_EVENTS and renders key stats from all unipi packages",
   "type": "module",
   "main": "index.ts",
@@ -32,8 +32,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.8",
-    "@pi-unipi/background-tasks": "3.0.0-alpha.8"
+    "@pi-unipi/core": "3.0.0-alpha.9",
+    "@pi-unipi/background-tasks": "3.0.0-alpha.9"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",

package/packages/fusion/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/fusion",
-  "version": "3.0.0-alpha.8",
+  "version": "3.0.0-alpha.9",
   "description": "Devin-style model picker, fusion presets (lead + sidekick), and Local Fusion runtime for UniPi",
   "type": "module",
   "main": "src/index.ts",
@@ -32,8 +32,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.8",
-    "@pi-unipi/subagents": "3.0.0-alpha.8"
+    "@pi-unipi/core": "3.0.0-alpha.9",
+    "@pi-unipi/subagents": "3.0.0-alpha.9"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.87.1",

package/packages/info-screen/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/info-screen",
-  "version": "3.0.0-alpha.8",
+  "version": "3.0.0-alpha.9",
   "description": "Dashboard and module registry for Unipi — configurable info overlay with tabbed groups",
   "type": "module",
   "main": "index.ts",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.8"
+    "@pi-unipi/core": "3.0.0-alpha.9"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",

package/packages/input-shortcuts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/input-shortcuts",
-  "version": "3.0.0-alpha.8",
+  "version": "3.0.0-alpha.9",
   "description": "Keyboard shortcuts for stash/restore, undo/redo, clipboard, and thinking toggle — chord-based overlay system",
   "type": "module",
   "main": "src/index.ts",
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.8"
+    "@pi-unipi/core": "3.0.0-alpha.9"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",

package/packages/kanboard/index.ts

@@ -71,6 +71,7 @@ export default function (pi: ExtensionAPI) {
       return status?.phase === "running" ? status.taskId : null;
     },
     () => readKanboardSettings().turnAddLimit,
+    () => readKanboardSettings().doCredits,
   );
   const sessionId = (): string => process.env.UNIPI_KANBOARD_SESSION ?? `pi-${process.pid}`;
 

package/packages/kanboard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/kanboard",
-  "version": "3.0.0-alpha.8",
+  "version": "3.0.0-alpha.9",
   "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.8"
+    "@pi-unipi/core": "3.0.0-alpha.9"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",
@@ -48,10 +48,10 @@
     "themes": []
   },
   "optionalDependencies": {
-    "@pi-unipi/kanboard-linux-x64": "3.0.0-alpha.8",
-    "@pi-unipi/kanboard-linux-arm64": "3.0.0-alpha.8",
-    "@pi-unipi/kanboard-darwin-x64": "3.0.0-alpha.8",
-    "@pi-unipi/kanboard-darwin-arm64": "3.0.0-alpha.8",
-    "@pi-unipi/kanboard-win32-x64": "3.0.0-alpha.8"
+    "@pi-unipi/kanboard-linux-x64": "3.0.0-alpha.9",
+    "@pi-unipi/kanboard-linux-arm64": "3.0.0-alpha.9",
+    "@pi-unipi/kanboard-darwin-x64": "3.0.0-alpha.9",
+    "@pi-unipi/kanboard-darwin-arm64": "3.0.0-alpha.9",
+    "@pi-unipi/kanboard-win32-x64": "3.0.0-alpha.9"
   }
 }

package/packages/kanboard/src/commands.ts

@@ -40,9 +40,9 @@ export const HELP = `Kanboard commands
   /unipi:kanboard-autowork start|stop   work ready tasks chain by chain; stop finishes the current one first
 Priority -p: 1 none · 2 low · 3 medium · 4 high · 5 urgent`;
 
-export function doText(slug: string, cli: string, request: string, queueMax = 10): string {
+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} …\`). Board writes are allowed until this turn ends. 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, 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.
 
 Request: ${request}`;
 }
@@ -1093,7 +1093,21 @@ export function kanboardCompletions(prefix: string): CompletionItem[] | null {
 /** Live task list for `--after` / `-do` completions, cached ~5s per client. */
 const taskCache = new WeakMap<KanboardCli, { at: number; tasks: ShowTask[] }>();
 
-export async function taskCompletions(deps: CommandDeps, prefix: string, before: string): Promise<CompletionItem[] | null> {
+export interface TaskCompletionOptions {
+  /** Also match task TITLES (default true); false = id prefixes only. */
+  titleSearch?: boolean;
+  /** Row style: "status" = label id, description "<status> — <title>";
+   *  "id-title" = label "<id>  <title>", description "<status>". */
+  rowStyle?: "status" | "id-title";
+}
+
+export async function taskCompletions(
+  deps: CommandDeps,
+  prefix: string,
+  before: string,
+  opts: TaskCompletionOptions = {},
+): Promise<CompletionItem[] | null> {
+  const { titleSearch = true, rowStyle = "status" } = opts;
   const client = deps.cli;
   if (!client) return null;
   let cache = taskCache.get(client);
@@ -1109,13 +1123,21 @@ export async function taskCompletions(deps: CommandDeps, prefix: string, before:
   const needle = prefix.toLowerCase();
   const items = cache.tasks
     .filter((task) => !["cancelled", "archived"].includes(task.status))
-    .filter((task) => task.id.toLowerCase().startsWith(needle) || task.title.toLowerCase().includes(needle))
+    .filter((task) => task.id.toLowerCase().startsWith(needle) || (titleSearch && task.title.toLowerCase().includes(needle)))
     .slice(0, 12)
-    .map((task) => ({
-      value: fullArgs(before, task.id),
-      label: task.id,
-      description: `${task.status} — ${task.title}`,
-    }));
+    .map((task) =>
+      rowStyle === "id-title"
+        ? {
+            value: fullArgs(before, task.id),
+            label: `${task.id}  ${task.title.slice(0, 64)}`,
+            description: task.status,
+          }
+        : {
+            value: fullArgs(before, task.id),
+            label: task.id,
+            description: `${task.status} — ${task.title}`,
+          },
+    );
   return items.length > 0 ? items : null;
 }
 
@@ -1191,15 +1213,19 @@ export async function kanboardAddCompletions(deps: CommandDeps, prefix: string):
   return null;
 }
 
-/** /unipi:kanboard-do … — complete a trailing task-id prefix. */
+/** /unipi:kanboard-do … — complete a trailing task-id token; plain prose never matches. */
 export async function kanboardDoCompletions(deps: CommandDeps, prefix: string): Promise<CompletionItem[] | null> {
   const raw = prefix ?? "";
-  const match = /^(.*?)(\S*)$/.exec(raw)!;
-  const before = match[1]!;
-  const token = match[2]!;
-  // Only when the last token looks like a task id prefix (ABC-…).
-  if (!/^[A-Za-z]{2,6}-?[0-9]*$/.test(token) || token.length < 2) return null;
-  return taskCompletions(deps, token, before);
+  const at = raw.lastIndexOf(" ");
+  const before = at === -1 ? "" : raw.slice(0, at + 1);
+  const token = raw.slice(at + 1);
+  // Only a task-id-like tail ("UNI-1", "uni", "UNI-") completes; words that
+  // match no id shape or prefix ("note", "set") yield nothing.
+  if (!/^[A-Za-z]{2,10}-?\d*$/.test(token)) return null;
+  // Title search only when the token looks like a real id prefix (has a digit
+  // or ends with the dash); otherwise id prefixes only.
+  const idLike = /\d/.test(token) || token.endsWith("-");
+  return taskCompletions(deps, token, before, { titleSearch: idLike, rowStyle: "id-title" });
 }
 
 export function registerKanboardCommands(pi: ExtensionAPI, deps: CommandDeps): void {
@@ -1308,10 +1334,15 @@ export function registerKanboardCommands(pi: ExtensionAPI, deps: CommandDeps): v
   });
 
   pi.registerCommand("unipi:kanboard-do", {
-    description: "Let the agent use the kanboard for this turn — writes are allowed until the turn ends",
+    description: "Grant kanboard write credits to the agent (/unipi:kanboard-do <request>; off revokes)",
     getArgumentCompletions: (prefix: string) => kanboardDoCompletions(deps, prefix ?? ""),
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       const request = (args ?? "").trim();
+      if (request.toLowerCase() === "off") {
+        deps.guard.revoke();
+        ctx.ui.notify("kanboard: write credits revoked — reads stay free", "info");
+        return;
+      }
       if (!request) {
         ctx.ui.notify("kanboard: -do needs a request — /unipi:kanboard-do <what the agent may do on the board>", "warning");
         return;
@@ -1328,9 +1359,12 @@ export function registerKanboardCommands(pi: ExtensionAPI, deps: CommandDeps): v
       const busy = typeof (ctx as unknown as { isIdle?: () => boolean }).isIdle === "function"
         ? !(ctx as unknown as { isIdle: () => boolean }).isIdle!()
         : false;
-      pi.sendUserMessage(doText(slug, client.binary.path, request, deps.settings().queueMax), busy ? { deliverAs: "followUp" } : undefined);
+      pi.sendUserMessage(
+        doText(slug, client.binary.path, request, deps.settings().queueMax, deps.guard.remaining()),
+        busy ? { deliverAs: "followUp" } : undefined,
+      );
       deps.guard.noteSent();
-      deps.debug(`do window open (${slug})`);
+      deps.debug(`do credits open (${slug}): ${deps.guard.remaining()} remaining`);
     },
   });
 

package/packages/kanboard/src/guard.ts

@@ -9,8 +9,8 @@
 
 import { tokenizeArgs } from "./commands.js";
 
-export const WRITE_BLOCK_REASON =
-  "kanboard board writes are only allowed during /unipi:kanboard-do or a runner task";
+export const DEFAULT_DO_CREDITS = 10;
+export const WRITE_CREDITS_USED_UP = "kanboard write credits used up — run /unipi:kanboard-do to reload";
 export const addCapReason = (limit: number): string => `at most ${limit} new tasks per turn`;
 /** @deprecated tests should read the limit through the guard's getter instead. */
 export const ADD_CAP = 20;
@@ -80,35 +80,55 @@ export function isReadonly(invocation: KanboardInvocation): boolean {
 }
 
 export interface WriteGuard {
-  /** Open the window for a `/unipi:kanboard-do` turn. */
+  /** Grant / top up the session's write credits to N (kanboard.doCredits). */
   open(): void;
+  /** Revoke remaining credits (/unipi:kanboard-do off). */
+  revoke(): void;
+  /** Credits left this session. */
+  remaining(): number;
   /** Arm the agent_end closer right after the -do prompt was sent. */
   noteSent(): void;
-  /**
-   * A window opened by -do closes on the first agent_end that isn't the
-   * pre-send echo (>150ms after noteSent). Returns true when it just closed.
-   */
+  /** Credits persist across turns; this only closes the -do window label. */
   onAgentEnd(): boolean;
   /** null when the command is allowed; otherwise the block reason. */
   check(command: string): string | null;
 }
 
 /**
- * The window is open during a -do turn (`doOpen`) or while the runner has a
- * task in phase `running`. `runnerTask` returns that task's id (null when the
- * runner is not running one) — the `add` counter resets whenever the running
- * task changes, so autowork/queue drains get a fresh 20 per task.
+ * Writes cost session credits (one per write subcommand in the command line);
+ * reads 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.
  */
-export function createWriteGuard(runnerTask: () => string | null, addLimit: () => number = () => ADD_CAP): WriteGuard {
+export function createWriteGuard(
+  runnerTask: () => string | null,
+  addLimit: () => number = () => ADD_CAP,
+  doCredits: () => number = () => DEFAULT_DO_CREDITS,
+): WriteGuard {
+  let credits = 0;
   let doOpen = false;
   let sentAt = 0;
   let adds = 0;
   let lastTask: string | null = null;
+  const countAdd = (invocation: KanboardInvocation): string | null => {
+    if (invocation.sub !== "add") return null;
+    adds += 1;
+    const limit = addLimit();
+    return limit > 0 && adds > limit ? addCapReason(limit) : null;
+  };
   return {
     open() {
-      doOpen = true;
+      credits = Math.max(credits, Math.max(0, doCredits()));
       adds = 0;
       lastTask = null;
+      doOpen = true;
+    },
+    revoke() {
+      credits = 0;
+      doOpen = false;
+    },
+    remaining() {
+      return credits;
     },
     noteSent() {
       sentAt = Date.now();
@@ -130,12 +150,15 @@ export function createWriteGuard(runnerTask: () => string | null, addLimit: () =
       }
       for (const invocation of invocations) {
         if (isReadonly(invocation)) continue;
-        if (!(doOpen || task !== null)) return WRITE_BLOCK_REASON;
-        if (invocation.sub === "add") {
-          adds += 1;
-          const limit = addLimit();
-          if (limit > 0 && adds > limit) return addCapReason(limit);
+        if (task !== null) {
+          const cap = countAdd(invocation);
+          if (cap) return cap;
+          continue;
         }
+        if (credits <= 0) return WRITE_CREDITS_USED_UP;
+        credits -= 1;
+        const cap = countAdd(invocation);
+        if (cap) return cap;
       }
       return null;
     },