@pi-unipi/unipi 2.20.2 → 2.20.3

package/CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [2.20.3] — 2026-09-17
+
+### Fixed
+
+- `background-tasks`: **distinguish persistent dev servers from finite jobs in `bg_run` prompt guidelines.** The prompt guidance previously grouped dev servers and test suites under the same "do not set `triggerOnCompletion:false`" rule. For persistent servers and watchers (e.g. `npm run dev`, `vite`), `triggerOnCompletion: true` caused the UI to show an indefinite "waiting on 1 bg task" spinner and caused `SidekickRuntime` in Fusion to hang waiting for `openBgTasks` to reach zero. `BgRunParams` and `promptGuidelines` in `packages/background-tasks/src/tools.ts` now explicitly instruct agents to set `triggerOnCompletion: false` for long-running servers/daemons so neither the harness nor sidekicks wait indefinitely for exit.
+
 ## [2.20.2] — 2026-09-17
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "description": "All-in-one extension suite for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -84,29 +84,29 @@
     "typebox": "^1.1.38"
   },
   "dependencies": {
-    "@pi-unipi/ask-user": "2.20.2",
-    "@pi-unipi/background-tasks": "2.20.2",
-    "@pi-unipi/btw": "2.20.2",
-    "@pi-unipi/command-enchantment": "2.20.2",
-    "@pi-unipi/compactor": "2.20.2",
-    "@pi-unipi/core": "2.20.2",
-    "@pi-unipi/footer": "2.20.2",
-    "@pi-unipi/image": "2.20.2",
-    "@pi-unipi/fusion": "2.20.2",
-    "@pi-unipi/info-screen": "2.20.2",
-    "@pi-unipi/input-shortcuts": "2.20.2",
-    "@pi-unipi/kanboard": "2.20.2",
-    "@pi-unipi/mcp": "2.20.2",
-    "@pi-unipi/memory": "2.20.2",
-    "@pi-unipi/milestone": "2.20.2",
-    "@pi-unipi/notify": "2.20.2",
-    "@pi-unipi/ralph": "2.20.2",
-    "@pi-unipi/subagents": "2.20.2",
-    "@pi-unipi/trajectory": "2.20.2",
-    "@pi-unipi/updater": "2.20.2",
-    "@pi-unipi/utility": "2.20.2",
-    "@pi-unipi/web-api": "2.20.2",
-    "@pi-unipi/workflow": "2.20.2"
+    "@pi-unipi/ask-user": "2.20.3",
+    "@pi-unipi/background-tasks": "2.20.3",
+    "@pi-unipi/btw": "2.20.3",
+    "@pi-unipi/command-enchantment": "2.20.3",
+    "@pi-unipi/compactor": "2.20.3",
+    "@pi-unipi/core": "2.20.3",
+    "@pi-unipi/footer": "2.20.3",
+    "@pi-unipi/image": "2.20.3",
+    "@pi-unipi/fusion": "2.20.3",
+    "@pi-unipi/info-screen": "2.20.3",
+    "@pi-unipi/input-shortcuts": "2.20.3",
+    "@pi-unipi/kanboard": "2.20.3",
+    "@pi-unipi/mcp": "2.20.3",
+    "@pi-unipi/memory": "2.20.3",
+    "@pi-unipi/milestone": "2.20.3",
+    "@pi-unipi/notify": "2.20.3",
+    "@pi-unipi/ralph": "2.20.3",
+    "@pi-unipi/subagents": "2.20.3",
+    "@pi-unipi/trajectory": "2.20.3",
+    "@pi-unipi/updater": "2.20.3",
+    "@pi-unipi/utility": "2.20.3",
+    "@pi-unipi/web-api": "2.20.3",
+    "@pi-unipi/workflow": "2.20.3"
   },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.84.0",

package/packages/ask-user/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ask-user",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "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": "2.20.2"
+    "@pi-unipi/core": "2.20.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/autocomplete/package.json

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

package/packages/background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/background-tasks",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "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.84.0",
-    "@pi-unipi/core": "2.20.2",
+    "@pi-unipi/core": "2.20.3",
     "turndown": "^7.2.4"
   },
   "devDependencies": {

package/packages/background-tasks/src/tools.ts

@@ -52,13 +52,13 @@ export const BgRunParams = Type.Object({
   notifyOnCompletion: Type.Optional(
     Type.Boolean({
       description:
-        "Deliver a durable terminal notification when the task finishes. Default true. Do not disable unless opting out of completion handling.",
+        "Deliver a durable terminal notification when the task finishes. Default true for finite tasks. Set false or pair with triggerOnCompletion:false for persistent servers/daemons/watchers.",
     }),
   ),
   triggerOnCompletion: Type.Optional(
     Type.Boolean({
       description:
-        "Start a follow-up agent turn on terminal notification. Default true for bg_run. Requires notifyOnCompletion.",
+        "Start a follow-up agent turn on terminal notification. Default true for finite tasks (tests, builds, exports). MUST set false for persistent background services/servers (e.g. dev servers, watchers) so the harness and subagents do not wait indefinitely for the server to finish. Requires notifyOnCompletion.",
     }),
   ),
 });
@@ -185,14 +185,14 @@ export function registerToolsAndCommands(options: RegisterSurfaceOptions): void
     promptSnippet:
       "Start a named long-running shell command; default terminal notification wakes a follow-up turn, so yield instead of polling",
     promptGuidelines: [
-      "Use bg_run instead of bash for commands expected to run for a long time, such as test suites, dev servers, watchers, or builds.",
+      "Use bg_run instead of bash for commands expected to run in the background (test suites, builds, dev servers, watchers).",
+      "For FINITE tasks (tests, builds, exports, scripts): leave triggerOnCompletion:true and notifyOnCompletion:true (defaults) to automatically wake the agent when finished.",
+      "For PERSISTENT servers/daemons/watchers (e.g. 'npm run dev', vite, live dev servers, background listeners): MUST set triggerOnCompletion:false (and optionally notifyOnCompletion:false) so the agent and sidekick do not wait for the server to exit.",
       "Set isAgent:true only when the background task launches an LLM/agent process; false for scripts, tests, dev servers, sleeps.",
       "Always set name to a concise 2-6 word human-readable label; do not use the raw command as the name.",
-      "bg_run returns immediately. With notifyOnCompletion:true and triggerOnCompletion:true (both defaults), completed, failed, or killed terminal state is delivered as <background-task-notification> and automatically starts a follow-up agent turn.",
-      "After a default bg_run launch, continue only independent useful work that does not merely wait for the task; otherwise briefly acknowledge it if useful, then end the current turn. Do not call sleep, bg_status, or bg_logs merely to wait; the terminal notification will wake you.",
+      "bg_run returns immediately. For finite tasks with default wake-up, continue only independent useful work that does not merely wait for the task; otherwise end the current turn. Do not call sleep, bg_status, or bg_logs merely to wait; the terminal notification will wake you.",
       "A running result is not an instruction to poll again.",
       "Treat <background-task-notification> as durable terminal truth. Do not call bg_status to reconfirm it.",
-      "Do not set notifyOnCompletion:false or triggerOnCompletion:false unless intentionally opting out.",
     ],
     parameters: BgRunParams,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {

package/packages/btw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/btw",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "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.84.0"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.20.2"
+    "@pi-unipi/core": "2.20.3"
   },
   "pi": {
     "extensions": [

package/packages/compactor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/compactor",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "description": "Context engine for Pi — zero-LLM compaction, session continuity, sandbox execution, and tool display optimization",
   "type": "module",
   "main": "src/index.ts",
@@ -34,8 +34,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.20.2",
-    "@pi-unipi/info-screen": "2.20.2",
+    "@pi-unipi/core": "2.20.3",
+    "@pi-unipi/info-screen": "2.20.3",
     "@earendil-works/pi-agent-core": "^0.84.0"
   },
   "peerDependencies": {

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/core",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "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": "2.20.2",
+  "version": "2.20.3",
   "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": "2.20.2",
-    "@pi-unipi/background-tasks": "2.20.2"
+    "@pi-unipi/core": "2.20.3",
+    "@pi-unipi/background-tasks": "2.20.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/fusion/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/fusion",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "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": "2.20.2",
-    "@pi-unipi/subagents": "2.20.2"
+    "@pi-unipi/core": "2.20.3",
+    "@pi-unipi/subagents": "2.20.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.0",

package/packages/image/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/image",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "description": "Image generation and image recognition tools for the Pi coding agent",
   "type": "module",
   "main": "src/index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.20.2"
+    "@pi-unipi/core": "2.20.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.0",

package/packages/info-screen/package.json

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

package/packages/input-shortcuts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/input-shortcuts",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "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": "2.20.2"
+    "@pi-unipi/core": "2.20.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/kanboard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/kanboard",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "description": "Visualization layer for unipi workflow — HTTP server with htmx/Alpine.js UI, modular parsers, TUI overlay, and kanban board",
   "type": "module",
   "main": "index.ts",
@@ -39,7 +39,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.20.2"
+    "@pi-unipi/core": "2.20.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/mcp",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "description": "MCP server management extension for Pi coding agent — browse, add, configure, and use MCP servers",
   "type": "module",
   "main": "src/index.ts",
@@ -30,7 +30,7 @@
     "test": "npx tsx --test tests/**/*.test.ts"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.20.2"
+    "@pi-unipi/core": "2.20.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/memory",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "description": "Persistent cross-session memory with MemPalace backend (auto-installed) and SQLite fallback for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -39,8 +39,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@pi-unipi/core": "2.20.2",
-    "@pi-unipi/info-screen": "2.20.2",
+    "@pi-unipi/core": "2.20.3",
+    "@pi-unipi/info-screen": "2.20.3",
     "js-yaml": "^4.1.0"
   },
   "peerDependencies": {

package/packages/milestone/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/milestone",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "description": "Lifecycle layer for project-level goals — MILESTONES.md tracking, session hooks, auto-sync",
   "type": "module",
   "main": "index.ts",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.20.2"
+    "@pi-unipi/core": "2.20.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/notify/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/notify",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "description": "Cross-platform notification extension for Pi — native OS, Gotify, and Telegram notifications for agent lifecycle events",
   "type": "module",
   "main": "index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.20.2",
+    "@pi-unipi/core": "2.20.3",
     "node-notifier": "^10.0.1"
   },
   "peerDependencies": {

package/packages/ralph/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ralph",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "description": "Long-running iterative development loops for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -31,8 +31,8 @@
     "test": "npx tsx --test reminder.test.ts"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.20.2",
-    "@pi-unipi/info-screen": "2.20.2"
+    "@pi-unipi/core": "2.20.3",
+    "@pi-unipi/info-screen": "2.20.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.0",

package/packages/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/subagents",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "description": "Subagents for UniPi — parallel execution, file locking, workflow integration",
   "type": "module",
   "main": "src/index.ts",
@@ -9,7 +9,7 @@
     "test": "npx tsx --test src/__tests__/*.test.ts"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.20.2",
+    "@pi-unipi/core": "2.20.3",
     "@earendil-works/pi-agent-core": "^0.84.0",
     "acorn": "8.18.0"
   },

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/trajectory",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "description": "Live UniPi trajectory inspector for Pi sessions",
   "type": "module",
   "main": "index.ts",

package/packages/unipi/bundled.js

@@ -22204,12 +22204,12 @@ var BgRunParams = Type4.Object({
   ),
   notifyOnCompletion: Type4.Optional(
     Type4.Boolean({
-      description: "Deliver a durable terminal notification when the task finishes. Default true. Do not disable unless opting out of completion handling."
+      description: "Deliver a durable terminal notification when the task finishes. Default true for finite tasks. Set false or pair with triggerOnCompletion:false for persistent servers/daemons/watchers."
     })
   ),
   triggerOnCompletion: Type4.Optional(
     Type4.Boolean({
-      description: "Start a follow-up agent turn on terminal notification. Default true for bg_run. Requires notifyOnCompletion."
+      description: "Start a follow-up agent turn on terminal notification. Default true for finite tasks (tests, builds, exports). MUST set false for persistent background services/servers (e.g. dev servers, watchers) so the harness and subagents do not wait indefinitely for the server to finish. Requires notifyOnCompletion."
     })
   )
 });
@@ -22299,14 +22299,14 @@ Command: ${task.command}`,
     description: `Start a named long-running shell command in the background and return immediately with a task ID and output path. By default, terminal state is delivered automatically as <background-task-notification> and starts a follow-up agent turn; do not sleep or poll merely to wait. Output is written under the OS temp root and model-visible logs are bounded.`,
     promptSnippet: "Start a named long-running shell command; default terminal notification wakes a follow-up turn, so yield instead of polling",
     promptGuidelines: [
-      "Use bg_run instead of bash for commands expected to run for a long time, such as test suites, dev servers, watchers, or builds.",
+      "Use bg_run instead of bash for commands expected to run in the background (test suites, builds, dev servers, watchers).",
+      "For FINITE tasks (tests, builds, exports, scripts): leave triggerOnCompletion:true and notifyOnCompletion:true (defaults) to automatically wake the agent when finished.",
+      "For PERSISTENT servers/daemons/watchers (e.g. 'npm run dev', vite, live dev servers, background listeners): MUST set triggerOnCompletion:false (and optionally notifyOnCompletion:false) so the agent and sidekick do not wait for the server to exit.",
       "Set isAgent:true only when the background task launches an LLM/agent process; false for scripts, tests, dev servers, sleeps.",
       "Always set name to a concise 2-6 word human-readable label; do not use the raw command as the name.",
-      "bg_run returns immediately. With notifyOnCompletion:true and triggerOnCompletion:true (both defaults), completed, failed, or killed terminal state is delivered as <background-task-notification> and automatically starts a follow-up agent turn.",
-      "After a default bg_run launch, continue only independent useful work that does not merely wait for the task; otherwise briefly acknowledge it if useful, then end the current turn. Do not call sleep, bg_status, or bg_logs merely to wait; the terminal notification will wake you.",
+      "bg_run returns immediately. For finite tasks with default wake-up, continue only independent useful work that does not merely wait for the task; otherwise end the current turn. Do not call sleep, bg_status, or bg_logs merely to wait; the terminal notification will wake you.",
       "A running result is not an instruction to poll again.",
-      "Treat <background-task-notification> as durable terminal truth. Do not call bg_status to reconfirm it.",
-      "Do not set notifyOnCompletion:false or triggerOnCompletion:false unless intentionally opting out."
+      "Treat <background-task-notification> as durable terminal truth. Do not call bg_status to reconfirm it."
     ],
     parameters: BgRunParams,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {

package/packages/updater/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/updater",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "description": "Auto-updater, changelog browser, and readme browser for Unipi — checks npm registry, renders CHANGELOG.md and README.md files in TUI overlays",
   "type": "module",
   "main": "index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.20.2"
+    "@pi-unipi/core": "2.20.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.0",

package/packages/utility/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/utility",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "description": "Utility commands and tools for Pi coding agent — lifecycle, diagnostics, cache, analytics, display, batch execution",
   "type": "module",
   "main": "src/index.ts",
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.20.2"
+    "@pi-unipi/core": "2.20.3"
   },
   "devDependencies": {},
   "peerDependencies": {

package/packages/web-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/web-api",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "description": "Web search, read, and summarize tools with provider-based backend selection for Pi coding agent",
   "type": "module",
   "main": "src/index.ts",
@@ -31,7 +31,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@pi-unipi/core": "2.20.2",
+    "@pi-unipi/core": "2.20.3",
     "defuddle": "^0.18.1",
     "linkedom": "^0.18.12",
     "wreq-js": "^2.3.0"

package/packages/workflow/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/workflow",
-  "version": "2.20.2",
+  "version": "2.20.3",
   "description": "Structured development workflow commands for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -30,7 +30,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.20.2"
+    "@pi-unipi/core": "2.20.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.0",