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

package/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/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/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/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;
     },

package/src/runner.ts

@@ -436,6 +436,22 @@ export function createRunner(deps: RunnerDeps): Runner {
     return true;
   }
 
+  /** Latest [parked goal: …] marker from the task's release comments, if any. */
+  async function parkedGoalFromNotes(taskId: string): Promise<string | null> {
+    try {
+      const shown = asTask(
+        "show",
+        await runCli<unknown>(["show", taskId], { extraEnv: { UNIPI_KANBOARD_PROJECT: project() } }),
+      );
+      const matches = (shown.activity ?? [])
+        .map((entry) => entry.text.match(/\[parked goal: ([\w-]+)\]/)?.[1])
+        .filter((goal): goal is string => typeof goal === "string");
+      return matches.at(-1) ?? null;
+    } catch {
+      return null;
+    }
+  }
+
   /** Wire the chosen strategy for the work turn; falls back toward "none". */
   async function applyStrategy(ctx: ExtensionContext, task: KanboardTask, strategy: Strategy): Promise<void> {
     const setRun = (mode: RunMode, goal?: string): void => {
@@ -447,6 +463,22 @@ export function createRunner(deps: RunnerDeps): Runner {
         .catch((error) => deps.debug(`set-run failed: ${error instanceof Error ? error.message : String(error)}`));
     };
     const goalStart = async (): Promise<boolean> => {
+      // A goal parked for THIS task (interrupted/released earlier) resumes
+      // instead of starting fresh; a stale id falls through to goal-start.
+      const priorGoal = task.run?.goal ?? (await parkedGoalFromNotes(task.id));
+      if (priorGoal) {
+        const resumed = await callCommandRunner<{ ok?: boolean; reason?: string }>(
+          "unipi:goal-resume",
+          ctx,
+          { goalId: priorGoal },
+        );
+        if (resumed.found && resumed.result?.ok) {
+          state.goalId = priorGoal;
+          state.mode = "goal";
+          setRun("goal", priorGoal);
+          return true;
+        }
+      }
       const started = await callCommandRunner<{ ok?: boolean; goalId?: string; reason?: string }>(
         "unipi:goal-start",
         ctx,
@@ -530,14 +562,14 @@ ${body}`.trim() },
   }
 
   /** Ask the goal engine whether the goal reached a terminal state. */
-  async function goalStatus(): Promise<{ status: string; objective?: string } | null> {
-    const looked = await callCommandRunner<{ found?: boolean; status?: string; objective?: string }>(
+  async function goalStatus(): Promise<{ status: string; reason?: string; objective?: string } | null> {
+    const looked = await callCommandRunner<{ found?: boolean; status?: string; reason?: string; objective?: string }>(
       "unipi:goal-status",
       undefined,
       { goalId: state.goalId },
     );
     if (!looked.found || !looked.result?.found || !looked.result.status) return null;
-    return { status: looked.result.status, objective: looked.result.objective };
+    return { status: looked.result.status, reason: looked.result.reason, objective: looked.result.objective };
   }
 
   function planStillActive(): boolean {
@@ -553,21 +585,57 @@ ${body}`.trim() },
         "show",
         await runCli<unknown>(["show", task.id], { extraEnv: { UNIPI_KANBOARD_PROJECT: project() } }),
       );
-      if (value.status === "blocked") {
+      // The user moved the task out from under the runner (done/cancelled/
+      // backlog): stop its goal, leave the board alone.
+      const movedAway = ["done", "cancelled", "backlog"].includes(value.status);
+      if (movedAway && state.goalId) {
+        await callCommandRunner("unipi:goal-stop", ctx, { goalId: state.goalId });
+      }
+      // A still-drivable goal is parked so re-claiming this task resumes it.
+      // The id rides the release comment (activity survives; the run block
+      // does not — release clears it).
+      let parkedMarker = "";
+      if (!movedAway && state.mode === "goal" && state.goalId) {
+        const paused = await callCommandRunner<{ ok?: boolean; reason?: string }>(
+          "unipi:goal-pause",
+          ctx,
+          { goalId: state.goalId },
+        );
+        if (paused.found && paused.result?.ok) {
+          deps.debug(`goal ${state.goalId} parked for ${task.id}`);
+          parkedMarker = ` [parked goal: ${state.goalId}]`;
+        }
+      }
+      if (movedAway) {
+        // The user's move stands — no release, just reset the runner.
+        ctx.ui.notify(`▣ ${task.id} was moved to ${value.status} outside the runner — goal stopped`, "warning");
+      } else if (value.status === "blocked") {
         const note = (value.activity ?? []).slice(-1)[0]?.text ?? "blocked";
         ctx.ui.notify(`▣ ${task.id} blocked: ${note}`, "warning");
       } else if (outcome === "in_review") {
-        await runCli(["release", task.id, "--to", "in_review", "--comment", comment], {
+        await runCli(["release", task.id, "--to", "in_review", "--comment", comment + parkedMarker], {
           extraEnv: { UNIPI_KANBOARD_PROJECT: project() },
         });
         const first = comment.split("\n")[0]?.slice(0, 120) ?? "";
         ctx.ui.notify(`✓ ${task.id} → In Review: ${first}`, "info");
       } else {
-        await runCli(["release", task.id, "--to", outcome, "--comment", comment], {
+        await runCli(["release", task.id, "--to", outcome, "--comment", comment + parkedMarker], {
           extraEnv: { UNIPI_KANBOARD_PROJECT: project() },
         });
         ctx.ui.notify(`↩ ${task.id} → ${outcome === "todo" ? "Todo" : "Blocked"}: ${comment.slice(0, 120)}`, "warning");
       }
+      if (movedAway) {
+        state.consumedText = state.lastText.trim();
+        state.task = null;
+        state.goalId = null;
+        state.endsSinceSend = 0;
+        state.phase = "idle";
+        persist("idle");
+        setStatus(ctx, state.stopAfterCurrent ? undefined : describe());
+        await postBoardProgress();
+        await continueLoop(ctx);
+        return;
+      }
     } catch (error) {
       ctx.ui.notify(
         `kanboard: could not release ${task.id} — ${error instanceof KanboardCliError ? error.message : String(error)}`,
@@ -878,13 +946,20 @@ ${body}`.trim() },
     }
     if (state.mode === "goal" && state.goalId) {
       const goal = await goalStatus();
-      if (goal && goal.status !== "complete") {
-        if (["failed", "blocked", "stalled", "abandoned", "budget_exhausted"].includes(goal.status)) {
-          await finishTask(ctx, "todo", `goal ${goal.status}`);
+      if (goal) {
+        // A user-stopped goal is NOT success: the task goes back to Todo.
+        if (goal.status === "complete" && goal.reason === "complete(user_requested)") {
+          await finishTask(ctx, "todo", "goal stopped by user");
+          return;
+        }
+        if (goal.status !== "complete") {
+          if (["failed", "blocked", "stalled", "abandoned", "budget_exhausted"].includes(goal.status)) {
+            await finishTask(ctx, "todo", `goal ${goal.status}`);
+            return;
+          }
+          deps.debug(`settle deferred: goal ${goal.status}`);
           return;
         }
-        deps.debug(`settle deferred: goal ${goal.status}`);
-        return;
       }
     }
 

package/src/settings.ts

@@ -31,6 +31,8 @@ export interface KanboardSettings {
   maxSessions: number;
   /** `add` calls allowed per -do/runner window (0 = unlimited). */
   turnAddLimit: number;
+  /** Write credits a /unipi:kanboard-do grants (each board write costs 1). */
+  doCredits: number;
   /** Strategy for unlabelled tasks ("auto" = jev decides). */
   defaultStrategy: "auto" | "none" | "goal" | "ralph" | "swarm" | "graph";
   /** Plan-first for unlabelled tasks (jev is never asked about plan). */
@@ -53,6 +55,7 @@ export const DEFAULT_SETTINGS: KanboardSettings = {
   queueMax: 10,
   maxSessions: 2,
   turnAddLimit: 20,
+  doCredits: 10,
   defaultStrategy: "auto",
   defaultPlan: false,
   blocking: "avoid",
@@ -113,6 +116,7 @@ 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: "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" },
         ],
       },
       {
@@ -183,6 +187,7 @@ export function readKanboardSettings(cwd: string = process.cwd()): KanboardSetti
     queueMax: typeof raw.queueMax === "number" && raw.queueMax >= 0 ? raw.queueMax : DEFAULT_SETTINGS.queueMax,
     maxSessions: typeof raw.maxSessions === "number" && raw.maxSessions >= 1 ? raw.maxSessions : DEFAULT_SETTINGS.maxSessions,
     turnAddLimit: typeof raw.turnAddLimit === "number" && raw.turnAddLimit >= 0 ? raw.turnAddLimit : DEFAULT_SETTINGS.turnAddLimit,
+    doCredits: typeof raw.doCredits === "number" && raw.doCredits >= 0 ? raw.doCredits : DEFAULT_SETTINGS.doCredits,
     defaultStrategy:
       typeof raw.defaultStrategy === "string" &&
       ["auto", "none", "goal", "ralph", "swarm", "graph"].includes(raw.defaultStrategy)