@pi-unipi/kanboard 3.0.0-alpha.16 → 3.0.0-alpha.18

package/index.ts

@@ -44,6 +44,7 @@ import {
   syncPiRuntime,
   runRotateTokenAction,
   runStopDaemon,
+  captureToBacklog,
   type CommandDeps,
 } from "./src/commands.js";
 import { createWriteGuard } from "./src/guard.js";
@@ -224,6 +225,12 @@ export default function (pi: ExtensionAPI) {
   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,
@@ -416,6 +423,10 @@ export default function (pi: ExtensionAPI) {
     // 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();

package/package.json

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

package/skills/kanboard/SKILL.md

@@ -22,13 +22,13 @@ be on `PATH`):
 <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> start <ID>                          # todo → in progress, claimed for your session (costs a -do slot)
-<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> 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>
@@ -94,9 +94,8 @@ lists them — read the files there directly if you need one.
    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. **Sidekicks and subagents can read the board but never write it** — every
@@ -106,7 +105,14 @@ lists them — read the files there directly if you need one.
    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.
@@ -126,6 +132,9 @@ but only to write a summary.)
 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.

package/src/commands.ts

@@ -11,6 +11,7 @@ import { join } from "node:path";
 import { promisify } from "node:util";
 
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { getSettings } from "@pi-unipi/core";
 
 import { KanboardCliError, type KanboardCli } from "./bin.js";
@@ -44,7 +45,7 @@ Priority -p: 1 none · 2 low · 3 medium · 4 high · 5 urgent`;
 export function doText(slug: string, cli: string, request: string, slots = DEFAULT_DO_TASKS, writes = DEFAULT_DO_WRITES): string {
   const s = slots === 1 ? "" : "s";
   const ws = writes === 1 ? "" : "s";
-  return `[kanboard] For this request you may use the kanboard skill on project ${slug} (CLI: \`${cli} --actor agent --project ${slug} …\`). Budget this session: ${String(slots)} task slot${s} — each \`start\` uses one — and ${String(writes)} board write${ws} (add, edit, link, order, move backlog↔todo, note on tasks you don't hold); /unipi:kanboard-do tops both back up. Always free: reads, and \`finish\`, \`move <ID> blocked --comment\` and \`note\` on tasks you started. Work the tasks yourself in this session, in whatever mode fits: \`start <ID>\` right before you work it, then \`finish <ID> --comment "<summary>"\` or \`move <ID> blocked --comment "<what you need>"\` — never leave a task you started In Progress. Before starting anything, count the tasks this request needs; if that is more than ${String(slots)}, start nothing — tell me you can do ${String(slots)} now and ask whether to raise the limit (setting kanboard.doTasks) or work in batches. Read a task with \`show <ID>\` before editing or starting it — \`list\` only shows titles and a one-line excerpt. Sidekicks and subagents can read the board but not write it: brief them with the task, then update the board yourself from their report. 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} …\`). Budget this session: ${String(slots)} task slot${s} — each \`start\` uses one — and ${String(writes)} board write${ws} (add, edit, link, order, move backlog↔todo, note on tasks you don't hold); /unipi:kanboard-do tops both back up. Always free: reads, and \`finish\`, \`move <ID> blocked --comment\`, \`note\` and \`attach\` on tasks you started. Work the tasks yourself in this session, in whatever mode fits: \`start <ID>\` right before you work it, then \`finish <ID> --comment "<summary>"\` or \`move <ID> blocked --comment "<what you need>"\` — never leave a task you started In Progress. Before starting anything, count the tasks this request needs; if that is more than ${String(slots)}, start nothing — tell me you can do ${String(slots)} now and ask whether to raise the limit (setting kanboard.doTasks) or work in batches. Read a task with \`show <ID>\` before editing or starting it — \`list\` only shows titles and a one-line excerpt. Sidekicks and subagents can read the board but not write it: brief them with the task, then update the board yourself from their report. If the request is unclear, ask me instead of guessing.
 
 Request: ${request}`;
 }
@@ -576,15 +577,18 @@ export async function runAdd(deps: CommandDeps, ctx: ExtensionCommandContext, te
     ctx.ui.notify(`kanboard: ${parsed.error} — /unipi:kanboard-add [-p 1-5] [--after ID] [--status backlog|todo] <title>`, "warning");
     return;
   }
-  if (!parsed.title) {
-    ctx.ui.notify("kanboard: add needs a title — /unipi:kanboard-add <title>", "warning");
+  const hasDescription = parsed.description.trim().length > 0;
+  if (!parsed.title && !hasDescription) {
+    ctx.ui.notify("kanboard: add needs a title or a description — /unipi:kanboard-add <title> (lines below are the description)", "warning");
     return;
   }
   if (!(await ensureOnboarded(deps, ctx))) return;
 
   let bodyFile: string | null = null;
   try {
-    const argv = ["add", parsed.title, ...parsed.flags];
+    // A description-only add omits the title positional entirely (the binary
+    // stores an empty title and derives the display title from the body).
+    const argv = ["add", ...(parsed.title ? [parsed.title] : []), ...parsed.flags];
     if (parsed.description) {
       bodyFile = join(mkdtempSync(join(tmpdir(), "kb-add-")), "body.md");
       writeFileSync(bodyFile, parsed.description);
@@ -606,6 +610,55 @@ export async function runAdd(deps: CommandDeps, ctx: ExtensionCommandContext, te
   }
 }
 
+export type CaptureToBacklogResult =
+  | { ok: true; id: string; attachments: number }
+  | { ok: false; reason: string };
+
+/**
+ * Capture editor text as a Backlog task body — the entry point the
+ * input-shortcuts K chord calls through `globalThis.__unipi_kanboard_api`.
+ * No title: the body carries the point (the binary derives the display
+ * title). No prompts: when the folder is not onboarded the capture is
+ * refused with the reason instead.
+ */
+export async function captureToBacklog(
+  deps: CommandDeps,
+  opts: { cwd: string; text: string },
+): Promise<CaptureToBacklogResult> {
+  const client = deps.cli;
+  if (!client) return { ok: false, reason: deps.unavailable ?? "kanboard binary unavailable" };
+  let slug: string | null = null;
+  try {
+    const settings = getSettings("kanboard", opts.cwd) as { slug?: string };
+    slug = typeof settings.slug === "string" && settings.slug.length > 0 ? settings.slug : null;
+  } catch {
+    slug = null;
+  }
+  if (!slug) {
+    return { ok: false, reason: "kanboard is not set up here — run /unipi:kanboard" };
+  }
+  const text = opts.text.trim();
+  if (!text) return { ok: false, reason: "nothing to add" };
+  const attaches = detectFilePaths(text);
+  let bodyFile: string | null = null;
+  try {
+    bodyFile = join(mkdtempSync(join(tmpdir(), "kb-capture-")), "body.md");
+    writeFileSync(bodyFile, text);
+    const argv = ["--project", slug, "add", "--status", "backlog", "--body-file", bodyFile];
+    for (const file of attaches) argv.push("--attach", file);
+    const task = asTask("add", await client.run<unknown>(argv, { cwd: opts.cwd }));
+    deps.debug(`captureToBacklog ${task.id} (${attaches.length} attachments)`);
+    return { ok: true, id: task.id, attachments: attaches.length };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: error instanceof KanboardCliError ? error.message : String(error),
+    };
+  } finally {
+    if (bodyFile) rmSync(join(bodyFile, ".."), { recursive: true, force: true });
+  }
+}
+
 export async function runStatus(deps: CommandDeps, ctx: ExtensionCommandContext | ExtensionContext): Promise<void> {
   const client = deps.cli;
   const lines: string[] = [];
@@ -806,6 +859,8 @@ export async function runRotateTokenAction(
 interface ShowTask {
   id: string;
   title: string;
+  /** Derived title (Rust `display_title`) — shown when `title` is empty. */
+  displayTitle?: string;
   status: string;
   priority?: string;
   order?: number;
@@ -831,6 +886,11 @@ const SHOW_EXTRA_LANES: Array<{ id: string; label: string }> = [
 const PRIO_GLYPH: Record<string, string> = { urgent: "⇈", high: "↑", medium: "·", low: "↓", none: " " };
 const PRIO_RANK: Record<string, number> = { urgent: 0, high: 1, medium: 2, low: 3, none: 4 };
 
+/** The title a row shows: the derived one when the raw title is empty. */
+function showTitle(task: ShowTask): string {
+  return task.displayTitle || task.title || "(untitled)";
+}
+
 /** Same ordering as the CLI's claim_sort: priority, then lane order, then id. */
 export function claimOrder(tasks: ShowTask[]): ShowTask[] {
   return [...tasks].sort(
@@ -875,7 +935,7 @@ function laneRows(tasks: ShowTask[], lane: string): ShowRow[] {
         number: `${number}.`,
         id: task.id,
         prio: PRIO_GLYPH[task.priority ?? "none"] ?? " ",
-        title: task.title,
+        title: showTitle(task),
         extra:
           task.ready === false || waits.length > 0
             ? `waits for ${waits.join(", ")}`
@@ -898,7 +958,7 @@ function laneRows(tasks: ShowTask[], lane: string): ShowRow[] {
       branch: "",
       id: task.id,
       prio: PRIO_GLYPH[task.priority ?? "none"] ?? " ",
-      title: task.title,
+      title: showTitle(task),
       extra:
         lane === "in_progress" && task.run?.session
           ? `· ${task.run.session}`
@@ -952,15 +1012,29 @@ export function showRenderer(
         lines.push(theme.fg("accent", lane.label));
         for (const row of laneRows(inLane, lane.id)) {
           const head = `  ${row.branch}${row.number ? `${row.number} ` : ""}${theme.fg("muted", row.id)} ${row.prio} `;
-          // visible length so far, then truncate the title to fit.
-          const prefixLen = 2 + row.branch.length + (row.number ? row.number.length + 1 : 0) + row.id.length + 2;
-          const budget = Math.max(10, width - prefixLen - (row.extra ? row.extra.length + 2 : 0));
-          const title = row.title.length > budget ? `${row.title.slice(0, Math.max(1, budget - 1))}…` : row.title;
-          const extra = row.extra ? `  ${row.tone === "error" ? theme.fg("error", row.extra) : theme.fg("dim", row.extra)}` : "";
-          lines.push(`${head}${title}${extra}`);
+          const styledExtra = row.extra
+            ? `  ${row.tone === "error" ? theme.fg("error", row.extra) : theme.fg("dim", row.extra)}`
+            : "";
+          // Budgets in visible cells (CJK ≈ 2 cells, ANSI = 0 — .length lies on both).
+          // Title takes all the room left after the extra when both fit comfortably,
+          // else it is capped at 10 cells; the extra then takes whatever remains, so a
+          // huge blockedReason is truncated instead of overflowing the terminal (which
+          // hard-crashes pi). Final truncate is the belt-and-braces guarantee.
+          const avail = Math.max(0, width - visibleWidth(head));
+          const extraW = styledExtra ? visibleWidth(styledExtra) : 0;
+          const titleBudget = Math.max(0, avail - extraW >= 10 ? avail - extraW : Math.min(avail, 10));
+          const title = truncateToWidth(row.title, titleBudget, "…");
+          let line = `${head}${title}`;
+          if (styledExtra) {
+            const extraBudget = avail - visibleWidth(title) - 2;
+            if (extraBudget > 0) line += truncateToWidth(styledExtra, extraBudget + 2, "…");
+          }
+          lines.push(line);
         }
       }
-      return lines;
+      // Hard guarantee: a line wider than the terminal hard-crashes pi, so every
+      // emitted line — header and lane labels included — is truncated to `width`.
+      return lines.map((line) => truncateToWidth(line, width));
     },
     invalidate: () => undefined,
   };
@@ -1094,19 +1168,19 @@ export async function taskCompletions(
   const needle = prefix.toLowerCase();
   const items = cache.tasks
     .filter((task) => !["cancelled", "archived"].includes(task.status))
-    .filter((task) => task.id.toLowerCase().startsWith(needle) || (titleSearch && task.title.toLowerCase().includes(needle)))
+    .filter((task) => task.id.toLowerCase().startsWith(needle) || (titleSearch && showTitle(task).toLowerCase().includes(needle)))
     .slice(0, 12)
     .map((task) =>
       rowStyle === "id-title"
         ? {
             value: fullArgs(before, task.id),
-            label: `${task.id}  ${task.title.slice(0, 64)}`,
+            label: `${task.id}  ${showTitle(task).slice(0, 64)}`,
             description: task.status,
           }
         : {
             value: fullArgs(before, task.id),
             label: task.id,
-            description: `${task.status} — ${task.title}`,
+            description: `${task.status} — ${showTitle(task)}`,
           },
     );
   return items.length > 0 ? items : null;

package/src/guard.ts

@@ -5,7 +5,7 @@
  * writes. A `/unipi:kanboard-do` grants task SLOTS (each `start` uses one)
  * and a WRITE budget (add, edit, link, order, move backlog↔todo, note on
  * tasks you don't hold). Always free: reads, and `finish`, `move <ID>
- * blocked` and `note <ID>` on claims this session started — a started task
+ * blocked`, `note <ID>` and `attach <ID>` on claims this session started — a started task
  * can always be closed. Autowork lifts both budgets (the runaway guard is
  * the per-turn add cap). In child processes every write is refused: the
  * lead updates the board.
@@ -282,9 +282,9 @@ export function createWriteGuard(options: WriteGuardOptions = {}): WriteGuard {
 					const id = firstPositional(invocation)!;
 					if (await ownsClaim(id)) continue; // closing your own claim is free
 				}
-				if (invocation.sub === "note" && firstPositional(invocation) !== undefined) {
+				if ((invocation.sub === "note" || invocation.sub === "attach") && firstPositional(invocation) !== undefined) {
 					const id = firstPositional(invocation)!;
-					if (await ownsClaim(id)) continue; // noting your own claim is free
+					if (await ownsClaim(id)) continue; // noting on / attaching to your own claim is free
 				}
 				if (autowork) continue; // autowork: unlimited slots and writes
 				if (invocation.sub === "start") {

package/src/monitor.ts

@@ -294,7 +294,7 @@ export function createKanboardMonitor(deps: MonitorDeps): KanboardMonitor {
 						source: "kanboard",
 						priority: AUTOWORK_PRIORITY,
 						customType: AUTOWORK_NUDGE_CUSTOM_TYPE,
-						content: `↻ next ready: ${next.id} ${next.title} — show it, start it, work it (autowork) ${ANTI_POISONING_SUFFIX}`,
+						content: `↻ next ready: ${next.id} ${next.displayTitle || next.title || "(untitled)"} — show it, start it, work it (autowork) ${ANTI_POISONING_SUFFIX}`,
 						display: true,
 						onDelivered: () => {
 							offersPerTask.set(next.id, offers); // counts on DELIVERY, not proposal

package/src/settings.ts

@@ -34,12 +34,6 @@ export interface KanboardSettings {
   doTasks: number;
   /** Board writes a /unipi:kanboard-do grants. */
   doWrites: number;
-  /** Strategy for unlabelled tasks ("auto" = jev decides, gated by `jevThreshold`). */
-  defaultStrategy: "auto" | "none" | "goal" | "ralph" | "swarm" | "graph";
-  /** Confidence floor for jev's strategy answer; below it (or missing) the task runs "none". */
-  jevThreshold: number;
-  /** Plan-first for unlabelled tasks (jev is never asked about plan). */
-  defaultPlan: boolean;
   /** Whether a blocked-by-confusion task may ask the user (ask) or must
    *  assume-and-note (avoid, the default). */
   blocking: "avoid" | "ask";
@@ -62,9 +56,6 @@ export const DEFAULT_SETTINGS: KanboardSettings = {
   turnAddLimit: 20,
   doTasks: 5,
   doWrites: 10,
-  defaultStrategy: "none",
-  jevThreshold: 0.8,
-  defaultPlan: false,
   blocking: "avoid",
   reminders: true,
 };
@@ -162,16 +153,6 @@ export function readKanboardSettings(cwd: string = process.cwd()): KanboardSetti
       typeof raw.doWrites === "number" && raw.doWrites >= 0 && storedDoWritesSet(cwd)
         ? raw.doWrites
         : (storedLegacyDoCredits(cwd) ?? DEFAULT_SETTINGS.doWrites),
-    defaultStrategy:
-      typeof raw.defaultStrategy === "string" &&
-      ["auto", "none", "goal", "ralph", "swarm", "graph"].includes(raw.defaultStrategy)
-        ? (raw.defaultStrategy as KanboardSettings["defaultStrategy"])
-        : DEFAULT_SETTINGS.defaultStrategy,
-    jevThreshold:
-      typeof raw.jevThreshold === "number" && raw.jevThreshold > 0 && raw.jevThreshold <= 1
-        ? raw.jevThreshold
-        : DEFAULT_SETTINGS.jevThreshold,
-    defaultPlan: raw.defaultPlan === true,
     blocking: raw.blocking === "ask" ? "ask" : "avoid",
     reminders: raw.reminders !== false,
   };

package/src/shapes.ts

@@ -45,6 +45,8 @@ export interface KanboardActivity {
 export interface KanboardTask {
   id: string;
   title: string;
+  /** Title derived from the first body line when `title` is empty (Rust `Task::display_title`). */
+  displayTitle?: string;
   body?: string;
   status: string;
   priority?: string;
@@ -115,6 +117,7 @@ export function asTask(command: string, value: unknown): KanboardTask {
     ...record,
     id: requireString(command, record, "id"),
     title: requireString(command, record, "title"),
+    displayTitle: typeof record.displayTitle === "string" ? record.displayTitle : undefined,
     status: requireString(command, record, "status"),
     deps: optionalArray<string>(record.deps) ?? [],
     activity: optionalArray<KanboardActivity>(record.activity) ?? [],