@pi-unipi/unipi 2.20.1 → 2.20.3

package/CHANGELOG.md

@@ -6,6 +6,18 @@ 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
+
+- `core`, `background-tasks`, `fusion`: **panes waiting on an auto-resume wake read `working` in herdr, not `idle`.** When the lead's turn ended while background work will re-invoke the agent — a bg task with wake-on-completion, or a Fusion sidekick handoff — herdr's sidebar flipped to `idle` the moment `agent_settled` fired, even as the session's own wake line said "agent resumes automatically when done". New key-scoped claim helper `setHerdrWorking()` in `@pi-unipi/core` emits `herdr:working {active,label}` exactly once per claim transition (the same refcounted event protocol `herdr:blocked` uses); `background-tasks` holds the claim while its bg-wake line is installed and `fusion` holds it while the sidekick wake line is up. Consumed by a one-listener patch to herdr's pi integration (held-working refcount in `desiredState()`, `blocked` still outranks it) — herdr enforces one status authority per pane and ignores second-source `pane.report_agent` reports, so the event protocol is the only channel. Until herdr upstreams the protocol, the patched integration file is local (`herdr integration install pi` reverts it; pristine v8 backup at `~/.pi/agent/herdr-agent-state.v8.orig.bak`).
+
 ## [2.20.1] — 2026-09-17
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "2.20.1",
+  "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.1",
-    "@pi-unipi/background-tasks": "2.20.1",
-    "@pi-unipi/btw": "2.20.1",
-    "@pi-unipi/command-enchantment": "2.20.1",
-    "@pi-unipi/compactor": "2.20.1",
-    "@pi-unipi/core": "2.20.1",
-    "@pi-unipi/footer": "2.20.1",
-    "@pi-unipi/image": "2.20.1",
-    "@pi-unipi/fusion": "2.20.1",
-    "@pi-unipi/info-screen": "2.20.1",
-    "@pi-unipi/input-shortcuts": "2.20.1",
-    "@pi-unipi/kanboard": "2.20.1",
-    "@pi-unipi/mcp": "2.20.1",
-    "@pi-unipi/memory": "2.20.1",
-    "@pi-unipi/milestone": "2.20.1",
-    "@pi-unipi/notify": "2.20.1",
-    "@pi-unipi/ralph": "2.20.1",
-    "@pi-unipi/subagents": "2.20.1",
-    "@pi-unipi/trajectory": "2.20.1",
-    "@pi-unipi/updater": "2.20.1",
-    "@pi-unipi/utility": "2.20.1",
-    "@pi-unipi/web-api": "2.20.1",
-    "@pi-unipi/workflow": "2.20.1"
+    "@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.1",
+  "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.1"
+    "@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.1",
+  "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.1",
+  "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.1",
+    "@pi-unipi/core": "2.20.3",
     "turndown": "^7.2.4"
   },
   "devDependencies": {

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

@@ -10,7 +10,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { createSpinnerLine } from "@pi-unipi/core";
+import { createSpinnerLine, setHerdrWorking } from "@pi-unipi/core";
 import { loadBackgroundTasksConfig } from "./config.js";
 import { BackgroundTaskRegistry } from "./registry.js";
 import {
@@ -134,9 +134,21 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
           { placement: "aboveEditor" },
         );
         wakeLineInstalled = true;
+        // The pane is not done: a running task will re-invoke the agent. Keep
+        // herdr at `working` instead of `idle` for exactly as long as the wake
+        // line is up (one claim transition per widget install, not per tick).
+        const wakeCount = registry
+          .allTasks()
+          .filter((task) => task.status === "running" && task.triggerOnCompletion).length;
+        setHerdrWorking(
+          pi,
+          "bg-wake",
+          `${wakeCount === 1 ? "1 bg task" : `${String(wakeCount)} bg tasks`} will resume agent`,
+        );
       } else if (!wantWakeLine && wakeLineInstalled) {
         target.ui.setWidget("background-tasks", undefined);
         wakeLineInstalled = false;
+        setHerdrWorking(pi, "bg-wake", null);
       }
       if (running.length === 0 && unseenFinishedCount === 0) {
         target.ui.setStatus("background-tasks", undefined);

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.1",
+  "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.1"
+    "@pi-unipi/core": "2.20.3"
   },
   "pi": {
     "extensions": [

package/packages/compactor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/compactor",
-  "version": "2.20.1",
+  "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.1",
-    "@pi-unipi/info-screen": "2.20.1",
+    "@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.1",
+  "version": "2.20.3",
   "description": "Shared utilities, event types, and constants for Unipi extension suite",
   "type": "module",
   "license": "MIT",

package/packages/core/utils.ts

@@ -304,6 +304,42 @@ export async function withHerdrBlocked<T>(
   }
 }
 
+/**
+ * Claim herdr `working` state for a long-lived "the agent will auto-resume" wait
+ * (bg task wake, fusion sidekick handoff) — the states where pi has already
+ * settled but background work holds a pending wake.
+ *
+ * Key-scoped and level-based, not a wrapper: each key claims exactly once and
+ * emits `herdr:working` {active:true,label} on claim, {active:false,label} on
+ * clear — the same refcounted protocol `herdr:blocked` uses, so the herdr pi
+ * integration can keep the pane `working` after agent_settled.
+ *
+ * - label !== null && no previous claim  → emit active
+ * - label !== null && same label         → no emit (still claimed)
+ * - label !== null && different label    → emit inactive(previous) then active
+ * - label === null && claimed             → emit inactive, drop claim
+ * - label === null && not claimed         → no emit
+ */
+const herdrWorkingClaims = new Map<string, string>();
+
+export function setHerdrWorking(
+  pi: { events: { emit: (name: string, payload: unknown) => void } },
+  key: string,
+  label: string | null,
+): void {
+  const previous = herdrWorkingClaims.get(key);
+  if (label === null) {
+    if (previous === undefined) return;
+    herdrWorkingClaims.delete(key);
+    emitEvent(pi, "herdr:working", { active: false, label: previous });
+    return;
+  }
+  if (previous === label) return;
+  if (previous !== undefined) emitEvent(pi, "herdr:working", { active: false, label: previous });
+  herdrWorkingClaims.set(key, label);
+  emitEvent(pi, "herdr:working", { active: true, label });
+}
+
 /** Format a token count for display (e.g. 1234 → "1.2k", 1500000 → "1.5M"). */
 export function formatTokens(n: number): string {
   if (n < 1000) return String(n);

package/packages/footer/package.json

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

package/packages/fusion/src/index.ts

@@ -16,7 +16,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { AutocompleteProvider, AutocompleteSuggestions } from "@earendil-works/pi-tui";
-import { createSpinnerLine, setSharedFusionStatus, UNIPI_PREFIX } from "@pi-unipi/core";
+import { createSpinnerLine, setHerdrWorking, setSharedFusionStatus, UNIPI_PREFIX } from "@pi-unipi/core";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import {
@@ -85,6 +85,8 @@ export interface SidekickWakeLine {
 export function createSidekickWakeLine(deps: {
   isBusy: () => boolean;
   progress: () => { toolCalls: number; startedAt: number } | undefined;
+  /** Claim hook: called with a label when the line goes up, null when it comes down. */
+  onHeld?: (label: string | null) => void;
 }): SidekickWakeLine {
   let installed = false;
 
@@ -102,14 +104,17 @@ export function createSidekickWakeLine(deps: {
           { placement: "aboveEditor" },
         );
         installed = true;
+        deps.onHeld?.("sidekick working — resumes automatically");
       } else if (!want && installed) {
         ctx.ui.setWidget(SIDEKICK_WAKE_WIDGET_KEY, undefined);
         installed = false;
+        deps.onHeld?.(null);
       }
     },
     clear(ctx) {
       if (!installed) return;
       installed = false;
+      deps.onHeld?.(null);
       if (!removable(ctx)) return;
       ctx.ui.setWidget(SIDEKICK_WAKE_WIDGET_KEY, undefined);
     },
@@ -190,6 +195,10 @@ export default function fusionExtension(pi: ExtensionAPI): void {
   const wakeLine = createSidekickWakeLine({
     isBusy: () => runtime?.isBusy() === true,
     progress: () => runtime?.progress(),
+    // While the wake line is up the pane must read `working` in herdr (the
+    // sidekick will re-invoke the lead), not `idle` — same claim the bg-tasks
+    // wake line makes.
+    onHeld: (label) => setHerdrWorking(pi, "fusion-sidekick", label),
   });
 
   function identity(ctx: ExtensionContext): FusionIdentity {

package/packages/image/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/image",
-  "version": "2.20.1",
+  "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.1"
+    "@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.1",
+  "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.1"
+    "@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.1",
+  "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.1"
+    "@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.1",
+  "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.1"
+    "@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.1",
+  "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.1"
+    "@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.1",
+  "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.1",
-    "@pi-unipi/info-screen": "2.20.1",
+    "@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.1",
+  "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.1"
+    "@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.1",
+  "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.1",
+    "@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.1",
+  "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.1",
-    "@pi-unipi/info-screen": "2.20.1"
+    "@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.1",
+  "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.1",
+    "@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.1",
+  "version": "2.20.3",
   "description": "Live UniPi trajectory inspector for Pi sessions",
   "type": "module",
   "main": "index.ts",

package/packages/unipi/bundled.js

@@ -624,6 +624,19 @@ async function withHerdrBlocked(pi, label, fn) {
     event(false);
   }
 }
+function setHerdrWorking(pi, key, label) {
+  const previous = herdrWorkingClaims.get(key);
+  if (label === null) {
+    if (previous === void 0) return;
+    herdrWorkingClaims.delete(key);
+    emitEvent(pi, "herdr:working", { active: false, label: previous });
+    return;
+  }
+  if (previous === label) return;
+  if (previous !== void 0) emitEvent(pi, "herdr:working", { active: false, label: previous });
+  herdrWorkingClaims.set(key, label);
+  emitEvent(pi, "herdr:working", { active: true, label });
+}
 function formatTokens(n) {
   if (n < 1e3) return String(n);
   if (n < 1e4) return `${(n / 1e3).toFixed(1)}k`;
@@ -652,11 +665,12 @@ function compareVersions(a, b) {
 function isNewerVersion(latest, current) {
   return compareVersions(latest, current) > 0;
 }
-var cachedPiVersion;
+var cachedPiVersion, herdrWorkingClaims;
 var init_utils = __esm({
   "packages/core/utils.ts"() {
     "use strict";
     cachedPiVersion = null;
+    herdrWorkingClaims = /* @__PURE__ */ new Map();
   }
 });
 
@@ -1102,6 +1116,7 @@ __export(core_exports, {
   safeRepeat: () => safeRepeat,
   safeRepeatCount: () => safeRepeatCount,
   sanitize: () => sanitize,
+  setHerdrWorking: () => setHerdrWorking,
   setSharedFusionStatus: () => setSharedFusionStatus,
   shouldRenderBorder: () => shouldRenderBorder,
   tryDelete: () => tryDelete,
@@ -22189,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."
     })
   )
 });
@@ -22284,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) {
@@ -25680,9 +25695,16 @@ function backgroundTasksExtension(pi) {
           { placement: "aboveEditor" }
         );
         wakeLineInstalled = true;
+        const wakeCount = registry3.allTasks().filter((task) => task.status === "running" && task.triggerOnCompletion).length;
+        setHerdrWorking(
+          pi,
+          "bg-wake",
+          `${wakeCount === 1 ? "1 bg task" : `${String(wakeCount)} bg tasks`} will resume agent`
+        );
       } else if (!wantWakeLine && wakeLineInstalled) {
         target.ui.setWidget("background-tasks", void 0);
         wakeLineInstalled = false;
+        setHerdrWorking(pi, "bg-wake", null);
       }
       if (running.length === 0 && unseenFinishedCount === 0) {
         target.ui.setStatus("background-tasks", void 0);
@@ -52125,14 +52147,17 @@ function createSidekickWakeLine(deps) {
           { placement: "aboveEditor" }
         );
         installed = true;
+        deps.onHeld?.("sidekick working \u2014 resumes automatically");
       } else if (!want && installed) {
         ctx.ui.setWidget(SIDEKICK_WAKE_WIDGET_KEY, void 0);
         installed = false;
+        deps.onHeld?.(null);
       }
     },
     clear(ctx) {
       if (!installed) return;
       installed = false;
+      deps.onHeld?.(null);
       if (!removable(ctx)) return;
       ctx.ui.setWidget(SIDEKICK_WAKE_WIDGET_KEY, void 0);
     }
@@ -52198,7 +52223,11 @@ function fusionExtension(pi) {
   let bashStreak = 0;
   const wakeLine = createSidekickWakeLine({
     isBusy: () => runtime?.isBusy() === true,
-    progress: () => runtime?.progress()
+    progress: () => runtime?.progress(),
+    // While the wake line is up the pane must read `working` in herdr (the
+    // sidekick will re-invoke the lead), not `idle` — same claim the bg-tasks
+    // wake line makes.
+    onHeld: (label) => setHerdrWorking(pi, "fusion-sidekick", label)
   });
   function identity(ctx) {
     const reg = registryOf(ctx);

package/packages/updater/package.json

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