@pi-unipi/kanboard 3.0.0-alpha.12 → 3.0.0-alpha.14

package/package.json

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

package/src/guard.ts

@@ -10,7 +10,8 @@
 import { tokenizeArgs } from "./commands.js";
 
 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 WRITE_CREDITS_USED_UP =
+  "kanboard write credits used up — run /unipi:kanboard-do to reload (board reads, `start` and `finish` are always free)";
 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;
@@ -29,6 +30,45 @@ 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"]);
 
+/** Quoted spans (single or double quotes), masked before splitting segments. */
+const QUOTED_SPAN = /(["'])(?:\\.|(?!\1).)*\1/g;
+
+/**
+ * Split a command line into shell segments on `&&`, `||`, `;`, `|` and
+ * newlines — ignoring separators inside quoted spans (the mask keeps the
+ * original length, so the cut positions map back onto the input exactly).
+ */
+export function shellSegments(command: string): string[] {
+  const masked = command.replace(QUOTED_SPAN, (span) => " ".repeat(span.length));
+  const out: string[] = [];
+  let at = 0;
+  for (const match of masked.matchAll(/&&|\|\||[;|\n]/g)) {
+    out.push(command.slice(at, match.index));
+    at = match.index + match[0].length;
+  }
+  out.push(command.slice(at));
+  return out;
+}
+
+/** `VAR=value` prefixes that may sit in front of the command word. */
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+/** Wrappers that keep the wrapped word in command position. */
+const COMMAND_PREFIXES = new Set(["exec", "command", "env"]);
+
+/**
+ * Every subcommand the CLI understands (crates/kanboard/src/cli.rs `Command`,
+ * kebab-case as clap spells it). Anything else — a typo like `done`, a bare
+ * binary with no subcommand — is the binary's own usage error; the guard
+ * neither charges nor blocks it.
+ */
+export const KNOWN_SUBCOMMANDS = new Set([
+  "project", "add", "list", "show", "move", "note", "attach", "attachments",
+  "edit", "link", "unlink", "order", "claim-next", "start", "finish", "next",
+  "reap", "queue", "unqueue", "chain", "search", "release", "set-run",
+  "duplicate", "archive-sweep", "serve", "settings", "rotate-token", "status",
+  "stop", "validate",
+]);
+
 export interface KanboardInvocation {
   /** First positional after the binary name ("" when absent). */
   sub: string;
@@ -36,15 +76,25 @@ export interface KanboardInvocation {
   args: string[];
 }
 
-/** Every `unipi-kanboard` invocation inside a shell command line. */
+/**
+ * Every `unipi-kanboard` invocation inside a shell command line. A token
+ * counts only when it is positioned like a command: the first word of its
+ * segment (segments split on `&&`/`||`/`;`/`|`/newlines, quotes masked),
+ * past leading `VAR=value` assignments and the `exec`/`command`/`env`
+ * wrappers. `which unipi-kanboard` or `find -name "unipi-kanboard"` merely
+ * mention the binary and are not invocations.
+ */
 export function kanboardInvocations(command: string): KanboardInvocation[] {
-  const tokens = tokenizeArgs(command);
   const out: KanboardInvocation[] = [];
-  for (let index = 0; index < tokens.length; index += 1) {
-    const token = tokens[index]!;
+  for (const segment of shellSegments(command)) {
+    const tokens = tokenizeArgs(segment);
+    let head = 0;
+    while (head < tokens.length && (ASSIGNMENT.test(tokens[head]!) || COMMAND_PREFIXES.has(tokens[head]!))) {
+      head += 1;
+    }
     // The binary may be a bare name or an absolute path (and .exe on Windows).
-    if (!/unipi-kanboard(\.exe)?$/.test(token)) continue;
-    const rest = tokens.slice(index + 1);
+    if (head >= tokens.length || !/unipi-kanboard(\.exe)?$/.test(tokens[head]!)) continue;
+    const rest = tokens.slice(head + 1);
     let cursor = 0;
     while (cursor < rest.length) {
       const arg = rest[cursor]!;
@@ -108,9 +158,12 @@ export interface WriteGuard {
 
 /**
  * Writes cost session credits (one per write subcommand in the command line);
- * 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.
+ * reads and `start`/`finish` are free and never blocked. Invocations whose
+ * subcommand does not exist are skipped: the binary itself rejects them with
+ * a usage error, and one typo must not block the rest of a compound call. 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,
@@ -161,6 +214,9 @@ export function createWriteGuard(
         lastTask = task;
       }
       for (const invocation of invocations) {
+        // An unknown subcommand (a typo, a bare binary) is the binary's own
+        // usage error — never a reason to block or charge the whole call.
+        if (!KNOWN_SUBCOMMANDS.has(invocation.sub)) continue;
         if (isReadonly(invocation) || isFreeWrite(invocation)) continue;
         if (task !== null) {
           const cap = countAdd(invocation);

package/src/reminders.ts

@@ -6,9 +6,9 @@
  * `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).
+ *   R1  every file-changing tool call of an agent turn, for each mentioned
+ *       task that is still Todo and has not been reminded this turn (one
+ *       steer per task per turn, at most twice per task).
  *   R2  agent_end with a task this session started still In Progress → one
  *       follow-up message (at most twice per task).
  *
@@ -20,7 +20,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { kanboardInvocations } from "./guard.js";
+import { kanboardInvocations, shellSegments } from "./guard.js";
 import type { KanboardTask } from "./shapes.js";
 
 export const REMINDER_CUSTOM_TYPE = "unipi:kanboard-reminder";
@@ -47,6 +47,9 @@ const READ_COMMANDS = new Set([
   "more", "true", "false", "test", "[", "diff", "cmp", "jq", "realpath", "dirname", "basename", "uname",
   "hostname", "id", "ps", "cd",
 ]);
+/** Interpreters/package managers whose version-check arms never write. */
+const VERSION_CHECKED = new Set(["node", "npm", "npx", "python", "python3"]);
+const isVersionFlag = (word: string): boolean => word === "--version" || word === "-v" || word === "-V";
 const GIT_READS = new Set(["status", "log", "diff", "show", "branch", "remote", "rev-parse", "blame", "ls-files", "describe", "tag"]);
 
 export function taskIdsIn(text: string): string[] {
@@ -56,14 +59,16 @@ export function taskIdsIn(text: string): string[] {
 /**
  * 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.
+ * does an output redirection. Quoted spans are masked before both the
+ * redirect test and the segment split, so `grep -c "a;b" f` stays one
+ * read-only segment.
  */
 export function shellChangesFiles(command: string): boolean {
   const trimmed = command.trim();
   if (!trimmed) return false;
   // `>`/`>>` into a file (but not `2>&1` / `>/dev/null`).
   if (/(^|[^0-9&>])>{1,2}\s*(?!&|\/dev\/null)[^\s|;&]/.test(trimmed.replace(/(["'])(?:\\.|(?!\1).)*\1/g, '""'))) return true;
-  const segments = trimmed.split(/&&|\|\||[;|\n]/).map((part) => part.trim()).filter(Boolean);
+  const segments = shellSegments(trimmed).map((part) => part.trim()).filter(Boolean);
   return segments.some((segment) => {
     const words = segment.split(/\s+/).filter((word) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(word));
     const first = (words[0] ?? "").replace(/^.*\//, "");
@@ -73,6 +78,11 @@ export function shellChangesFiles(command: string): boolean {
     if (READ_COMMANDS.has(first)) return false;
     if (first === "git") return !GIT_READS.has(words[1] ?? "");
     if (first === "sed") return words.includes("-i") || words.some((word) => word.startsWith("-i"));
+    // `sort` writes only through -o/--output (a `>` redirect is caught above).
+    if (first === "sort") return words.some((word) => /^-[^-]*o/.test(word) || word.startsWith("--output"));
+    // node/npm/npx/python are reads only as version checks (`node --version`,
+    // `npx tsx --version`); scripts, installs and builds still count.
+    if (VERSION_CHECKED.has(first)) return !words.slice(1).some(isVersionFlag);
     return true;
   });
 }
@@ -160,7 +170,8 @@ export function createProgressTracker(deps: TrackerDeps): ProgressTracker {
   const started = new Set<string>();
   const r1Count = new Map<string, number>();
   const r2Count = new Map<string, number>();
-  let checkedThisTurn = false;
+  /** Task ids already reminded this turn (per-task re-arm, not one shot). */
+  const remindedThisTurn = new Set<string>();
   const debug = (message: string): void => deps.debug?.(`reminders: ${message}`);
   const silent = (): boolean => !deps.enabled() || deps.runnerOwned() || Boolean(process.env.UNIPI_KANBOARD_CHILD);
 
@@ -183,7 +194,7 @@ export function createProgressTracker(deps: TrackerDeps): ProgressTracker {
     },
 
     onTurnStart() {
-      checkedThisTurn = false;
+      remindedThisTurn.clear();
     },
 
     async onToolResult(event) {
@@ -196,20 +207,24 @@ export function createProgressTracker(deps: TrackerDeps): ProgressTracker {
           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 (!isFileChangingCall(toolName, event.input)) return undefined;
       if (silent() || mentioned.size === 0) return undefined;
-      const candidates = [...mentioned].filter((id) => (r1Count.get(id) ?? 0) < MAX_REMINDERS_PER_TASK);
+      // Per task, at most once per turn: candidates are mentioned ids not yet
+      // reminded this turn and under the per-task cap (a started task leaves
+      // Todo and is never re-reminded).
+      const candidates = [...mentioned].filter(
+        (id) => !remindedThisTurn.has(id) && (r1Count.get(id) ?? 0) < MAX_REMINDERS_PER_TASK,
+      );
       if (candidates.length === 0) return undefined;
       const tasks = await safeList();
       if (!tasks) return undefined;
-      const 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);
+      for (const id of todo) {
+        remindedThisTurn.add(id);
+        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())}` }] };
     },