@pi-unipi/kanboard 2.20.5 → 3.0.0-alpha.1

package/README.md

@@ -1,92 +1,210 @@
 # @pi-unipi/kanboard
 
-Visualization for workflow data. An HTTP server with htmx + Alpine.js UI shows your milestones, specs, plans, and tasks in a web browser. A TUI overlay gives you a kanban board without leaving Pi.
+The pi half of **kanboard v3**: a per-project board for deferred work. The
+storage, transition rules and web UI live in the Rust binary
+([`crates/kanboard`](../../crates/kanboard) — one writer for every change); this
+package is the terminal-side bridge: commands, the task runner, hub settings and
+the `kanboard` skill.
 
-Parses 8 document types from `.unipi/docs/` — specs, plans, milestones, quick-work, debug, fix, chore, and review — and renders them as cards with progress indicators.
+Spec: [`docs/specs/2026-09-24-kanboard-v3-design.md`](../../docs/specs/2026-09-24-kanboard-v3-design.md).
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `/unipi:kanboard` | Toggle kanboard server on/off |
-| `/unipi:kanboard-doctor` | Diagnose and fix parser issues |
+`/unipi:kanboard [open|close|onboard|status|doctor]` — bare lists everything
+(display-only, never enters the LLM context):
+
+| Sub | What it does |
+|---|---|
+| `open [--host H] [--port N]` | Ensure the daemon (reuse a healthy one, else spawn `serve` detached) and print `http://127.0.0.1:<port>/p/<slug>`. The browser opens only when `openBrowser` is on. |
+| `onboard` | `project add` for this workspace and remembers the slug. Idempotent. |
+| `close` | Shut down the board daemon — the web UI goes offline until the next `open`. Running tasks are unaffected. |
+| `status` | Daemon pid/port, project counts, active claims (session/pid/host/staleness), this session's queue, and the runner's current task. |
+| `doctor` | ✓/✗ setup check (binary, daemon health, project, summary agent, bind, claims) as a display-only message. |
+
+The other three commands are separate slash commands:
+
+| Command | What it does |
+|---|---|
+| `/unipi:kanboard-add [-p 1-5] [--after ID] [--status backlog\|todo] <title>` | Capture a task — no agent turn. Lines below the title are the body; existing file paths pasted there are attached. `-p` maps 1 none · 2 low · 3 medium · 4 high · 5 urgent. |
+| `/unipi:kanboard-do <request>` | Reveal the skill and hand the request to the agent with board writes enabled for that turn. The agent may add/move/queue/note; it cannot run tasks — queued ids are drained by the runner when the turn ends. |
+| `/unipi:kanboard-autowork start\|stop` | `start` runs ready tasks one by one (queue order first, then `claim-next`); `stop` finishes the current task, then stops. |
+
+The old `add`/`work`/`stop` subcommands and bare-text capture now just point at
+these commands.
+
+## Runner (`/unipi:kanboard-autowork start`)
+
+One job per session. The **runner owns the lifecycle transitions** the agent is
+not allowed to write:
+
+1. `claim-next --session <sid> --pid <ppid> --host <host> --gate <chainGate>` —
+   nothing ready → `Nothing ready (N waiting on deps, M blocked)`.
+2. **jev picks the mode** (one `choice` call over title + body ≤2000 chars):
+   `direct` (small clear change) · `plan` (needs an approved plan) · `goal`
+   (multi-turn objective with verification). jev null → `direct`; the choice is
+   logged to `~/.unipi/logs/kanboard.log` with `UNIPI_DEBUG_KANBOARD=1`.
+3. `set-run --mode`, then the task goes to the agent as a user message: title,
+   body, last 10 activity entries, each dependency with its status and last note,
+   and the rules (block with a comment to ask a question; never write
+   `in_review`/`done`/`cancelled`; work only on this task).
+   - **plan** → plan mode is entered through workflow's `unipi:plan-enter` runner
+     first; approval stays interactive; a discarded plan releases the task to Todo
+     with `plan discarded`.
+   - **goal** → long-horizon's `unipi:goal-start` runner starts a goal with the
+     task as the objective; the goal id is recorded with `set-run --goal` and
+     completion is read back with `unipi:goal-status`.
+4. Run end (a `/plan` settle after the last `agent_end`, once the agent reports
+   idle with no queued messages): the task is re-read — if the agent blocked it,
+   that is respected and reported (`▣ UNI-12 blocked: <comment>`) and the loop
+   continues; otherwise `release --to in_review --comment <last assistant text
+   ≤500 chars>`. `Esc` (aborted turn) → `release --to todo --comment "interrupted
+   by user"` and the loop stops. Session shutdown → `release --to todo` with
+   `session ended`.
+5. After each task: `✓ UNI-12 → In Review: <first line>`, then the loop takes
+   the next id from the session **queue** (`claim-next --id`; entries that went
+   stale are dropped with a notice), falls back to `claim-next` while autowork
+   is on, and stops when nothing is ready. The event loop is never blocked.
+
+Footer: `▣ UNI-12 · direct` while a task runs. The claimed task is persisted with
+`pi.appendEntry("unipi:kanboard-runner", …)`, so `/reload` or a resume offers to
+resume it or releases it to Todo.
+
+## Settings (hub section "Kanboard")
+
+| Setting | Default | Notes |
+|---|---|---|
+| `chainGate` | `in_review` | `done` waits for a finished dependency |
+| `idleMin` | `10` | Passed to `serve --idle-min` |
+| `port` | `0` | Passed to `serve --port` (0 = OS-assigned) |
+| `archiveAfterDays` | `0` | > 0 → `archive-sweep --after-days N` on session start (fire and forget) |
+| `openBrowser` | `false` | Open the board in a browser on `open` |
+| `requireAuth` | `false` | Also require the access token on 127.0.0.1 (remote always does) |
+| `keepToken` | `false` | Reuse `<home>/token` across daemon restarts |
+| `queueMax` | `10` | Tasks a session may queue (0 = unlimited); passed to the CLI as `UNIPI_KANBOARD_QUEUE_MAX` |
+| `maxSessions` | `2` | Distinct sessions running tasks per project (`UNIPI_KANBOARD_MAX_SESSIONS`) |
+| `turnAddLimit` | `20` | `add` calls allowed per -do turn or runner task (0 = unlimited) |
+| *actions* | | `Open board…`, `Stop daemon`, `Summary agent command…`, `Rotate access token` |
+
+`Summary agent command…` writes through `settings set agent-command` and
+`Rotate access token` runs `rotate-token` — both are **user-only** (actor=agent
+is refused), as are `settings set` calls generally. `settings show` is read-only.
+
+## Binary resolution
+
+1. `UNIPI_KANBOARD_BIN` (explicit path)
+2. `@pi-unipi/kanboard-<platform>-<arch>/bin/unipi-kanboard[.exe]` (K4 ships these)
+3. the dev build `<repo>/crates/kanboard/target/{release,debug}/unipi-kanboard`
+
+Nothing found → every command reports
+`kanboard binary unavailable for <platform>-<arch>` and does nothing else.
+
+**Agent bash env:** pi has no extension-level mechanism to add env vars to the
+`bash` tool (only replacing bash via `registerTool` + `BashToolOptions`, which
+would change tool schemas mid-session and break the prefix cache — spec principle
+4 forbids that). So the task prompt and the skill pass `--actor agent --project
+<slug>` explicitly and call the binary by absolute path.
+
+## Skill
+
+`skills/kanboard/SKILL.md` describes the CLI, the lanes, who may move what, and
+the rules agents must follow. It is a normal pi skill (jev skill-judging can
+reveal it on intent), and `/unipi:kanboard-do` force-reveals it by emitting
+`unipi:skills:reveal`, which utility turns into the usual append-only reveal
+message — the system prompt is never touched.
+
+## Platforms and packaging
+
+| Platform | npm package | Rust target | Notes |
+|---|---|---|---|
+| Linux x64 | `@pi-unipi/kanboard-linux-x64` | `x86_64-unknown-linux-musl` | static-pie, 3.9 MB |
+| Linux arm64 | `@pi-unipi/kanboard-linux-arm64` | `aarch64-unknown-linux-musl` | static |
+| macOS arm64 | `@pi-unipi/kanboard-darwin-arm64` | `aarch64-apple-darwin` | |
+| macOS x64 | `@pi-unipi/kanboard-darwin-x64` | `x86_64-apple-darwin` | cross-built from macos-14 |
+| Windows x64 | `@pi-unipi/kanboard-win32-x64` | `x86_64-pc-windows-msvc` | |
+
+They are **optional dependencies** of this package (`os`/`cpu` gated), so `npm install`
+pulls exactly one. `.github/workflows/kanboard-binaries.yml` builds them (tests +
+clippy on native targets, release build per target, artifact per platform) and, on
+a `v*` tag, attaches the binaries to the GitHub release. Publishing to npm:
+
+```bash
+npm run publish:kanboard -- --dry-run   # what would ship
+npm run publish:kanboard                # publishes, or skips loudly
+```
 
-## Web Pages
+The script **skips any platform package whose `bin/` is empty** (and exits 2), so
+an empty platform package can never be published. CI publishes only when an
+`NPM_TOKEN` secret exists — this repository has none, so the release job attaches
+artifacts and says so.
 
-### Milestones (`/`)
-- Phases with progress bars
-- Checklist items with status indicators (done/todo)
-- Collapsible sections per phase
+Local packaging proof (no registry, no network):
 
-### Workflow (`/workflow`)
-- Cards grouped by document type
-- Progress indicators per card
-- Filtering by status (All, To Do, In Progress, Done)
+```bash
+node scripts/test-kanboard-packaging.mjs
+# packs packages/kanboard + the linux-x64 platform package, installs both into a
+# temp node_modules, resolves the binary through src/bin.ts and runs --version
+```
 
-## TUI Overlay
+## Remote access
 
-Two tabs accessible via the kanboard overlay:
+The daemon binds `127.0.0.1` by default — local only, no token. For access from
+another machine either **tunnel** it (nothing to configure):
 
-- **Tasks** — Flat list of all tasks from all documents with status icons
-- **Board** — Kanban columns (To Do / In Progress / Done)
+```bash
+ssh -N -L 37473:127.0.0.1:37473 <hostname>   # then open http://127.0.0.1:37473
+```
 
-### Controls
+…or bind a reachable interface, which turns on the **token gate**:
 
-| Key | Action |
-|-----|--------|
-| `j/k` | Navigate up/down |
-| `h/l` | Switch columns (Board tab) |
-| `Tab` or `b` | Switch between Tasks/Board tabs |
-| `t` | Switch to Tasks tab |
-| `gg/G` | Jump to top/bottom |
-| `q/Esc` | Close overlay |
+```bash
+/unipi:kanboard open --host 0.0.0.0 --port 37473     # every interface
+/unipi:kanboard open --host tailscale                # the tailnet IPv4
+```
 
-## Special Triggers
+`--host` and `--port` override the `host`/`port` settings for that invocation
+only. `tailscale` resolves through `tailscale ip -4` (clear error when tailscale
+is not installed). For a wildcard bind the printed URLs cover the machine
+hostname, every non-internal IPv4 and the tailnet address, and a warning says
+`board is reachable from the network; anyone with the link can edit it`.
 
-Kanboard registers with the info-screen dashboard, showing document count, tasks done, total tasks, and completion percentage. The footer subscribes to kanboard registry data to display task stats in the status bar.
+**Token model.** Any non-loopback bind generates a 32-byte token (base64url) and
+writes it to `daemon.json` alongside `host`. Every request must carry it:
 
-## Parser System
+- `?t=<token>` — sets an `HttpOnly; SameSite=Strict` cookie and 303-redirects to
+  the same URL without the parameter (so the token leaves the address bar),
+- the `kb_token` cookie, or
+- `Authorization: Bearer <token>`.
 
-Kanboard parses 8 document types:
+Missing or wrong tokens answer `401` with a page saying to open the link printed
+by `/unipi:kanboard open`. `/api/health` stays reachable but returns only
+`{ok, version}` (no pid) off-loopback, and POSTs are refused when their `Origin`
+does not match the request `Host` (drive-by CSRF), in both modes. Loopback binds
+keep no token at all.
 
-| Type | Directory | What's Parsed |
-|------|-----------|---------------|
-| Spec | `specs/` | `- [ ]` / `- [x]` checklist items |
-| Plan | `plans/` | `unstarted:` / `in-progress:` / `completed:` statuses |
-| Milestone | `MILESTONES.md` | Phase headers + checklist items |
-| Quick-work | `quick-work/` | Title + checklist items |
-| Debug | `debug/` | Headers + checklists |
-| Fix | `fix/` | Headers + checklists + related debug ref |
-| Chore | `chore/` | Chore steps as checklist items |
-| Review | `reviews/` | Review remarks as checklist items |
+Changing the binding needs a restart: if a daemon already runs with a different
+host/port, `serve` reports `bindingChanged` and `/unipi:kanboard open` stops the
+old one and starts the new one (`restarted kanboard on 0.0.0.0:37473`). The
+daemon runs no jobs, so nothing is lost.
 
-Parsers are resilient — they collect warnings per file and return partial results. Warnings are surfaced in the kanboard-doctor skill.
+## Storage
 
-## API Endpoints
+`~/.unipi/kanboard/` (`UNIPI_KANBOARD_HOME` overrides it): `daemon.json` +
+`daemon.lock` for the daemon, and `projects/<slug>/{project.json,board.lock,tasks/*.md,queues/<session>.json}`.
+The extension never edits those files — the binary owns them.
 
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/` | Milestone page |
-| GET | `/workflow` | Workflow page |
-| GET | `/api/milestones` | Milestone JSON data |
-| GET | `/api/workflow` | Workflow JSON data |
-| POST | `/api/docs/:type/:file/items/:line` | Update item status |
+## Troubleshooting
 
-## Configurables
+| Symptom | Fix |
+|---|---|
+| `kanboard binary unavailable for <platform>-<arch>` | No `UNIPI_KANBOARD_BIN`, no platform package and no dev build. Build `crates/kanboard` (`cargo build --release`) or set `UNIPI_KANBOARD_BIN`. |
+| The board says *"N task file(s) need repair"* | A file was edited by hand. One bad file no longer blocks the board (it is skipped and reported); run `unipi-kanboard validate --fix`, then `validate`. |
+| `UNI-5 is unreadable: … (line N)` | That task's own file is broken — repair it before moving/noting it. |
+| The daemon looks stale | `unipi-kanboard status` (pid + liveness), then `/unipi:kanboard close`, `unipi-kanboard stop` (SIGTERM, ≤3s) or the hub's **Stop daemon** action. |
+| Nothing is ready | `unipi-kanboard list --ready --json` shows `waitingFor`; a cancelled dependency blocks forever — `link`/`unlink` to re-plan. |
+| The runner prompts for permission on every board call | Fixed in auto mode: `unipi-kanboard … --actor agent` is allow-listed by the permission gate (ask mode still asks). |
 
-Default port configuration from `@pi-unipi/core`:
+## Tests
 
-```typescript
-KANBOARD_DEFAULTS = {
-  PORT: 8165,      // Starting port
-  MAX_PORT: 8175,  // Maximum port to try
-}
+```bash
+npm test -w packages/kanboard     # bin resolution, commands, runner, settings
 ```
-
-- Port allocation: tries 8165, increments on EADDRINUSE
-- PID file: `.unipi/kanboard.pid`
-- Graceful shutdown on SIGINT/SIGTERM
-
-## License
-
-MIT

package/index.ts

@@ -1,71 +1,217 @@
 /**
- * @pi-unipi/kanboard — Extension entry
+ * @pi-unipi/kanboard — pi extension.
  *
- * Visualization layer for unipi workflow data.
- * HTTP server with htmx + Alpine.js UI, modular parsers, TUI overlay, and kanban board.
+ * 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.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { MODULES, KANBOARD_COMMANDS } from "@pi-unipi/core";
-import { registerCommands } from "./commands.js";
-
-/** Package version */
-const VERSION = "0.1.0";
-
-export default function (pi: ExtensionAPI): void {
-
-  // Register commands
-  registerCommands(pi);
-
-  // Note: Badge generation on first message is handled by the utility module.
-  // Kanboard no longer manages badge generation to avoid duplication.
-
-  // Register info-screen group
-  const registry = globalThis.__unipi_info_registry;
-  if (registry) {
-    registry.registerGroup({
-      id: "kanboard",
-      name: "Kanboard",
-      icon: "📋",
-      priority: 50,
-      config: {
-        showByDefault: true,
-        stats: [
-          { id: "status", label: "Server Status", show: true },
-          { id: "url", label: "URL", show: true },
-          { id: "docs", label: "Documents", show: true },
-          { id: "tasks", label: "Tasks", show: true },
-        ],
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  MODULES,
+  UNIPI_EVENTS,
+  emitEvent,
+  getPackageVersion,
+  initUnipiDirs,
+  registerCommandRunner,
+  getSettings,
+} from "@pi-unipi/core";
+
+import { openCli, type KanboardCli } from "./src/bin.js";
+import { createWriteGuard } from "./src/guard.js";
+import {
+  drainQueueAfterDo,
+  registerKanboardCommands,
+  runOpen,
+  syncPiRuntime,
+  runRotateTokenAction,
+  runStopDaemon,
+  type CommandDeps,
+} from "./src/commands.js";
+import { createDebugLog, createRunner, registerPlanEventListener, type Runner } from "./src/runner.js";
+import {
+  ACTION_OPEN,
+  ACTION_STOP_DAEMON,
+  ACTION_ROTATE_TOKEN,
+  readKanboardSettings,
+  registerKanboardSettings,
+  applyLimitEnv,
+} from "./src/settings.js";
+
+const VERSION = getPackageVersion(dirname(fileURLToPath(import.meta.url)));
+
+/** Utility owns the frozen judged set, so kanboard asks it to reveal the skill. */
+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.
+  process.env.UNIPI_KANBOARD_SESSION ??= `pi-${process.pid}`;
+  // Limits travel through the environment; refresh on load and before every
+  // tool_call (see the guard registration in commands.ts).
+  applyLimitEnv(readKanboardSettings());
+  const debug = createDebugLog();
+  registerKanboardSettings();
+
+  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 sessionId = (): string => process.env.UNIPI_KANBOARD_SESSION ?? `pi-${process.pid}`;
+
+  const projectSlug = (): string => {
+    const fromEnv = process.env.UNIPI_KANBOARD_PROJECT?.trim();
+    if (fromEnv) return fromEnv;
+    try {
+      const settings = getSettings("kanboard", process.cwd()) as { slug?: string };
+      return typeof settings.slug === "string" ? settings.slug : "";
+    } catch {
+      return "";
+    }
+  };
+
+  // Live getters: the command is registered before the binary is resolved, so
+  // the deps object must read the current state at call time.
+  const buildDeps = (): CommandDeps => ({
+      get cli() {
+        return cli;
       },
-      dataProvider: async () => {
-        const { createDefaultRegistry } = await import("./parser/index.js");
-        const registry = await createDefaultRegistry();
-        const docs = registry.parseAll(".unipi/docs");
-        const totalItems = docs.reduce((sum, d) => sum + d.items.length, 0);
-        const doneItems = docs.reduce(
-          (sum, d) => sum + d.items.filter((i) => i.status === "done").length,
-          0,
-        );
-
-        return {
-          status: {
-            value: "Ready",
-            detail: "Server not running (use /unipi:kanboard to start)",
-          },
-          url: {
-            value: "—",
-            detail: "Start server to get URL",
-          },
-          docs: {
-            value: String(docs.length),
-            detail: `${docs.length} documents parsed`,
-          },
-          tasks: {
-            value: `${doneItems}/${totalItems}`,
-            detail: `${totalItems > 0 ? Math.round((doneItems / totalItems) * 100) : 0}% complete`,
-          },
-        };
+      get unavailable() {
+        return unavailable;
       },
+      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" },
+      guard,
+      session: sessionId,
+      debug,
+    }) as CommandDeps;
+
+  const revealSkill = (ctx: ExtensionContext | { cwd?: string }): void => {
+    // Append-only reveal (never the system prompt), so the prefix cache holds.
+    emitEvent(pi, SKILL_REVEAL_EVENT, { names: [KANBOARD_SKILL], ctx });
+    debug(`reveal requested for ${KANBOARD_SKILL}`);
+  };
+
+  const attach = (ctx: ExtensionContext): boolean => {
+    if (cli) return true;
+    const opened = openCli();
+    if ("error" in opened) {
+      unavailable = opened.error;
+      return false;
+    }
+    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;
+  };
+
+  registerKanboardCommands(pi, buildDeps());
+
+  registerCommandRunner(ACTION_OPEN, async (ctx) => {
+    const context = ctx as ExtensionContext | undefined;
+    if (!context?.ui) return;
+    if (!attach(context)) {
+      context.ui.notify(`kanboard: ${unavailable}`, "warning");
+      return;
+    }
+    await runOpen(buildDeps(), context);
+  });
+
+  registerCommandRunner(ACTION_STOP_DAEMON, async (ctx) => {
+    const context = ctx as ExtensionContext | undefined;
+    if (!context?.ui) return;
+    await runStopDaemon(buildDeps(), context);
+  });
+
+  registerCommandRunner(ACTION_ROTATE_TOKEN, async (ctx) => {
+    const context = ctx as ExtensionContext | undefined;
+    if (!context?.ui) return;
+    await runRotateTokenAction(buildDeps(), context);
+  });
+
+  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;
+    initUnipiDirs();
+    if (attach(ctx as unknown as ExtensionContext)) {
+      const deps = buildDeps();
+      if (deps.cli) void syncPiRuntime(deps, ctx as unknown as ExtensionContext);
+    }
+    emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
+      name: MODULES.KANBOARD,
+      version: VERSION,
+      commands: ["kanboard"],
+      tools: [],
     });
-  }
+
+    if (!attach(ctx as unknown as ExtensionContext)) {
+      debug(`unavailable: ${unavailable}`);
+      return;
+    }
+    const client = cli!;
+    const settings = readKanboardSettings(ctx.cwd);
+    if (settings.archiveAfterDays > 0 || settings.retentionDays > 0) {
+      // Fire and forget: sweeping must never delay startup.
+      void client
+        .run([
+          "archive-sweep",
+          "--after-days",
+          String(settings.archiveAfterDays),
+          "--retention-days",
+          String(settings.retentionDays),
+        ])
+        .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);
+  });
 }

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@pi-unipi/kanboard",
-  "version": "2.20.5",
-  "description": "Visualization layer for unipi workflow — HTTP server with htmx/Alpine.js UI, modular parsers, TUI overlay, and kanban board",
+  "version": "3.0.0-alpha.1",
+  "description": "Kanboard v3 \u2014 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"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Neuron-Mr-White/unipi.git",
@@ -14,40 +17,25 @@
   "keywords": [
     "pi-package",
     "pi-extension",
-    "pi-coding-agent",
     "unipi",
     "kanboard",
-    "kanban",
-    "visualization",
-    "milestones",
-    "workflow"
+    "tasks"
   ],
   "files": [
     "index.ts",
-    "commands.ts",
-    "types.ts",
-    "parser/**/*.ts",
-    "server/**/*.ts",
-    "tui/**/*.ts",
-    "ui/**/*.ts",
-    "ui/**/*.css",
-    "ui/**/*.js",
-    "skills/**/*",
+    "src/**/*.ts",
+    "skills/**/*.md",
     "README.md"
   ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.20.5"
+    "@pi-unipi/core": "3.0.0-alpha.1"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.0",
-    "@earendil-works/pi-tui": "^0.84.0"
-  },
-  "devDependencies": {
-    "@types/node": "^25.6.0",
-    "typescript": "^6.0.0"
+    "@earendil-works/pi-coding-agent": "^0.87.1",
+    "typebox": "^1.1.38"
   },
   "pi": {
     "extensions": [
@@ -58,5 +46,12 @@
     ],
     "prompts": [],
     "themes": []
+  },
+  "optionalDependencies": {
+    "@pi-unipi/kanboard-linux-x64": "3.0.0-alpha.1",
+    "@pi-unipi/kanboard-linux-arm64": "3.0.0-alpha.1",
+    "@pi-unipi/kanboard-darwin-x64": "3.0.0-alpha.1",
+    "@pi-unipi/kanboard-darwin-arm64": "3.0.0-alpha.1",
+    "@pi-unipi/kanboard-win32-x64": "3.0.0-alpha.1"
   }
 }