@mjasnikovs/pi-task 0.7.0 → 0.7.1

package/README.md

@@ -7,7 +7,7 @@
 [![npm](https://img.shields.io/npm/v/@mjasnikovs/pi-task?color=cb3837&logo=npm)](https://www.npmjs.com/package/@mjasnikovs/pi-task)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![pi extension](https://img.shields.io/badge/pi-extension-7c3aed)](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
-[![tests](https://img.shields.io/badge/tests-326%20passing-3fb950)](#development)
+[![tests](https://img.shields.io/badge/tests-533%20passing-3fb950)](#development)
 [![types](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](./tsconfig.json)
 
 </div>
@@ -114,6 +114,26 @@ The remote server is **always on** — it starts automatically with each session
 
 Prompts use a **first-answer-wins race**: the same question shows in the local TUI *and* every connected browser, and whoever answers first wins — the other surfaces dismiss. With nobody connected, `/task` behaves exactly as before; the remote path is purely additive.
 
+### Push notifications
+
+Tap the bell (◯ → ◉) in the remote header to get pushed a notification — even with the app backgrounded or the phone locked — when:
+
+- a **grill / clarify question** needs answering (*"pi needs your input"*),
+- a **task finishes** (*"Task finished"*), or
+- the agent hits an **error** (*"Agent error"*).
+
+Delivery is **server → push service → device** over the [Web Push](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) standard (service worker + VAPID), so it reaches a suspended device. It works on desktop browsers and on iOS home-screen PWAs.
+
+**iOS setup** (these are Apple's requirements, not ours):
+
+1. Open the **HTTPS** Tailscale URL (`/remote` lists it). iOS only allows push from a secure context — the plain `http://` LAN URL won't work.
+2. **Share → Add to Home Screen**, then open the app from that icon. iOS only permits notifications for installed PWAs.
+3. Launch the app, **tap the bell**, and **Allow** when prompted.
+
+The subscription is kept in memory, so after restarting `pi` just reload the app (it re-subscribes automatically) or tap the bell again. Notifications are suppressed while the app is focused in the foreground — the in-page UI already shows the prompt there.
+
+VAPID keys are generated once and persisted to `${XDG_DATA_HOME:-~/.local/share}/pi-task/vapid.json` (deleting them invalidates existing subscriptions). The JWT contact (`sub`) defaults to the project URL; override it with `PI_REMOTE_PUSH_SUBJECT` (e.g. your own `mailto:you@domain.com`). To debug delivery, set `PI_REMOTE_PUSH_DEBUG=1` and tail `/tmp/pi-task-push.log` — it records each push and the **push-service HTTP status** (`201` delivered, `403`/`400` token/key problem, `410` stale subscription).
+
 `/remote stop` shuts the server down for the rest of the session (it comes back on the next session start). There is **no authentication** — it's a personal LAN/Tailscale tool. Don't expose the port to untrusted networks.
 
 ## Bundled tools
@@ -148,6 +168,10 @@ Resolves an installed npm package, indexes its `.d.ts` files and README into a l
 | --- | --- | --- |
 | `BRAVE_SEARCH_API_KEY` / `BRAVE_API_KEY` | `pi-worker-search`, research enrichment | Required for web search. |
 | `XDG_CACHE_HOME` | `pi-worker-docs` | Overrides the docs cache location (defaults to `~/.cache`). |
+| `XDG_DATA_HOME` | remote push | Where the VAPID keypair is stored (defaults to `~/.local/share`). |
+| `PI_REMOTE_PUSH_SUBJECT` | remote push | VAPID JWT `sub` contact. Defaults to the project URL; set your own `mailto:you@domain.com` or `https://…`. |
+| `PI_REMOTE_PUSH_DEBUG` | remote push | When set (e.g. `1`), logs push delivery and push-service HTTP status. Off by default. |
+| `PI_REMOTE_PUSH_LOG` | remote push | Path for the debug log (defaults to `/tmp/pi-task-push.log`). |
 
 Tasks are persisted to `<cwd>/.pi-tasks/TASK_NNNN.md`. Add `.pi-tasks/` to your `.gitignore` if you don't want them checked in.
 
@@ -155,7 +179,7 @@ Tasks are persisted to `<cwd>/.pi-tasks/TASK_NNNN.md`. Add `.pi-tasks/` to your
 
 ```sh
 bun install
-bun test src/      # 326 tests across 28 files
+bun test src/      # 533 tests across 45 files
 bun run lint       # prettier + eslint + tsc --noEmit
 bun run build      # tsc → dist/
 ```

package/dist/remote/bridge.d.ts

@@ -1,14 +1,8 @@
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent';
-import type { ContextUsage, PromptMessage, ServerMessage } from './protocol.js';
+import type { ServerMessage } from './protocol.js';
 export interface BridgeState {
     /** promptId → resolver that settles the remote side of an ask() race. */
     pending: Map<string, (value: string | undefined) => void>;
-    /** The prompt currently awaiting an answer (replayed to late joiners), or null. */
-    activePrompt: PromptMessage | null;
-    /** Last lines pushed per widget key (replayed to late joiners). */
-    activeWidgets: Map<string, string[]>;
-    /** Most recent context-window usage (replayed to seed late joiners' bar), or null. */
-    lastContextUsage: ContextUsage | null;
     nextId: number;
     /** Command name → handler, populated as pi-task registers its commands. */
     commands: Map<string, (args: string, ctx: ExtensionCommandContext) => unknown>;
@@ -43,9 +37,6 @@ export declare class SessionUI {
     /** Race the local input against a remote answer; first to settle wins. */
     ask(spec: AskSpec): Promise<string | undefined>;
 }
-/** Mirror a status widget to browsers and remember it for late joiners.
- *  `lines === undefined` clears the widget (broadcast as `lines: null`). */
-export declare function publishWidget(key: string, lines: string[] | undefined): void;
 export declare function publishNotify(message: string, level: 'info' | 'warning' | 'error'): void;
 export declare function publishViewer(title: string, text: string): void;
 /**

package/dist/remote/bridge.js

@@ -1,13 +1,11 @@
 import { broadcast as wsBroadcast } from './broadcast.js';
 import { pushNotify } from './push.js';
+import { setPrompt, clearPrompt } from './session-state.js';
 const g = globalThis;
 export function getBridge() {
     if (!g.__piBridge) {
         g.__piBridge = {
             pending: new Map(),
-            activePrompt: null,
-            activeWidgets: new Map(),
-            lastContextUsage: null,
             nextId: 0,
             commands: new Map(),
             currentCtx: null,
@@ -56,8 +54,7 @@ export class SessionUI {
             recommended: spec.recommended,
             allowSkip: spec.allowSkip
         };
-        b.activePrompt = prompt;
-        b.broadcast(prompt);
+        setPrompt(prompt);
         // Reaches a backgrounded/suspended phone, which the in-page UI can't.
         void pushNotify('pi needs your input', spec.question, 'pi-prompt').catch(() => { });
         // Local: resolves to a value/undefined, or undefined on abort. Swallow
@@ -78,23 +75,10 @@ export class SessionUI {
         }
         finally {
             b.pending.delete(id);
-            b.activePrompt = null;
-            b.broadcast({ type: 'prompt_resolved', id });
+            clearPrompt(id);
         }
     }
 }
-/** Mirror a status widget to browsers and remember it for late joiners.
- *  `lines === undefined` clears the widget (broadcast as `lines: null`). */
-export function publishWidget(key, lines) {
-    const b = getBridge();
-    if (lines === undefined) {
-        b.activeWidgets.delete(key);
-        b.broadcast({ type: 'widget', key, lines: null });
-        return;
-    }
-    b.activeWidgets.set(key, lines);
-    b.broadcast({ type: 'widget', key, lines });
-}
 export function publishNotify(message, level) {
     getBridge().broadcast({ type: 'notify', message, level });
 }

package/dist/remote/events.d.ts

@@ -1,3 +1,4 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import type { HistoryBuffer } from './history.js';
-export declare function setupEvents(pi: ExtensionAPI, history: HistoryBuffer, broadcastFn: (msg: unknown) => void): void;
+/** Mirror pi agent events into the authoritative SessionState. Each handler
+ *  drives a mutator, which updates the snapshot AND broadcasts the live delta. */
+export declare function setupEvents(pi: ExtensionAPI): void;

package/dist/remote/events.js

@@ -1,22 +1,18 @@
 import { setAgentIdle } from './state.js';
-import { getBridge } from './bridge.js';
 import { pushNotify } from './push.js';
-export function setupEvents(pi, history, broadcastFn) {
-    let currentText = '';
-    const currentTools = [];
-    const pendingArgs = new Map();
+import { publishNotify } from './bridge.js';
+import { agentStart, appendText, textEnd, startTool, updateTool, endTool, agentEnd, addUserTurn, addError, addSystemNote } from './session-state.js';
+/** Mirror pi agent events into the authoritative SessionState. Each handler
+ *  drives a mutator, which updates the snapshot AND broadcasts the live delta. */
+export function setupEvents(pi) {
     pi.on('agent_start', (_event, _ctx) => {
-        currentText = '';
-        currentTools.length = 0;
-        pendingArgs.clear();
         setAgentIdle(false);
-        broadcastFn({ type: 'agent_start' });
+        agentStart();
     });
     pi.on('message_update', (event, _ctx) => {
         const ae = event.assistantMessageEvent;
         if (ae.type === 'text_delta' && 'delta' in ae && typeof ae.delta === 'string') {
-            currentText += ae.delta;
-            broadcastFn({ type: 'text_delta', delta: ae.delta });
+            appendText(ae.delta);
         }
         else if (ae.type === 'error') {
             const errorMessage = 'error' in ae && ae.error && typeof ae.error.errorMessage === 'string' ?
@@ -25,63 +21,42 @@ export function setupEvents(pi, history, broadcastFn) {
             // Skip silent user aborts (no message); only surface genuine failures.
             if (errorMessage || ae.reason === 'error') {
                 const message = errorMessage || 'Request failed';
-                history.addError(message);
-                broadcastFn({ type: 'agent_error', message });
+                addError(message);
                 void pushNotify('Agent error', message, 'pi-error').catch(() => { });
             }
         }
     });
     pi.on('message_end', (_event, _ctx) => {
-        broadcastFn({ type: 'text_end' });
+        textEnd();
     });
     pi.on('tool_execution_start', (event, _ctx) => {
-        pendingArgs.set(event.toolCallId, event.args);
-        broadcastFn({
-            type: 'tool_start',
-            toolCallId: event.toolCallId,
-            toolName: event.toolName,
-            args: event.args
-        });
+        startTool(event.toolCallId, event.toolName, event.args);
     });
     pi.on('tool_execution_update', (event, _ctx) => {
-        broadcastFn({
-            type: 'tool_update',
-            toolCallId: event.toolCallId,
-            partialResult: event.partialResult
-        });
+        updateTool(event.toolCallId, event.partialResult);
     });
     pi.on('tool_execution_end', (event, _ctx) => {
-        const args = pendingArgs.get(event.toolCallId);
-        pendingArgs.delete(event.toolCallId);
-        currentTools.push({
-            toolName: event.toolName,
-            args,
-            result: event.result,
-            isError: event.isError
-        });
-        broadcastFn({
-            type: 'tool_end',
-            toolCallId: event.toolCallId,
-            toolName: event.toolName,
-            result: event.result,
-            isError: event.isError
-        });
+        endTool(event.toolCallId, event.toolName, event.result, event.isError);
     });
     pi.on('agent_end', (_event, ctx) => {
-        const contextUsage = ctx.getContextUsage();
         setAgentIdle(true);
-        // Remember it so a browser that connects mid-session gets its bar seeded.
-        getBridge().lastContextUsage = contextUsage;
-        history.addAssistantTurn(currentText, [...currentTools]);
-        broadcastFn({ type: 'agent_end', contextUsage });
+        agentEnd(ctx.getContextUsage());
         void pushNotify('Task finished', '', 'pi-end').catch(() => { });
-        currentText = '';
-        currentTools.length = 0;
     });
     pi.on('input', (event, _ctx) => {
         if (event.source === 'interactive' && typeof event.text === 'string') {
-            history.addUserMessage(event.text);
-            broadcastFn({ type: 'user_message', text: event.text });
+            addUserTurn(event.text);
         }
     });
+    // Context-window compaction (incl. the auto-compaction triggered by a context
+    // overflow) is invisible to a remote viewer otherwise — mirror it as a toast so
+    // they see the same "compacting…" status the terminal shows.
+    pi.on('session_before_compact', (_event, _ctx) => {
+        publishNotify('Context full — compacting…', 'warning');
+    });
+    pi.on('session_compact', (_event, _ctx) => {
+        // Persistent inline note so it's still visible after a reconnect, not just a
+        // transient toast.
+        addSystemNote('Context compacted');
+    });
 }

package/dist/remote/history.d.ts

@@ -1,13 +1,24 @@
-export interface ToolSummary {
+export interface TextPart {
+    kind: 'text';
+    text: string;
+}
+export interface ToolPart {
+    kind: 'tool';
+    toolCallId: string;
     toolName: string;
     args: unknown;
     result: unknown;
     isError: boolean;
+    /** false while the tool is still running (result not in yet). */
+    done: boolean;
 }
+export type Part = TextPart | ToolPart;
 export interface Turn {
-    role: 'user' | 'assistant';
-    text: string;
-    tools: ToolSummary[];
+    role: 'user' | 'assistant' | 'system';
+    /** User text, error text, or a system note. Assistant content lives in `parts`. */
+    text?: string;
+    /** Ordered assistant content (text + tools). */
+    parts?: Part[];
     error?: boolean;
 }
 export declare class HistoryBuffer {
@@ -15,8 +26,10 @@ export declare class HistoryBuffer {
     private readonly limit;
     constructor(limit?: number);
     addUserMessage(text: string): void;
-    addAssistantTurn(text: string, tools: ToolSummary[]): void;
+    addAssistantTurn(parts: Part[]): void;
     addError(text: string): void;
+    /** A persistent, inline system note (e.g. "Context compacted"). */
+    addSystemNote(text: string): void;
     getEntries(): Turn[];
     private _push;
 }

package/dist/remote/history.js

@@ -1,3 +1,6 @@
+// An assistant turn is an ORDERED list of parts — text segments and tool calls
+// interleaved exactly as they happened — so the remote transcript reproduces the
+// terminal's layout instead of collapsing a whole run into one text blob.
 export class HistoryBuffer {
     entries = [];
     limit;
@@ -5,13 +8,17 @@ export class HistoryBuffer {
         this.limit = limit;
     }
     addUserMessage(text) {
-        this._push({ role: 'user', text, tools: [] });
+        this._push({ role: 'user', text });
     }
-    addAssistantTurn(text, tools) {
-        this._push({ role: 'assistant', text, tools });
+    addAssistantTurn(parts) {
+        this._push({ role: 'assistant', parts });
     }
     addError(text) {
-        this._push({ role: 'assistant', text, tools: [], error: true });
+        this._push({ role: 'assistant', text, error: true });
+    }
+    /** A persistent, inline system note (e.g. "Context compacted"). */
+    addSystemNote(text) {
+        this._push({ role: 'system', text });
     }
     getEntries() {
         return [...this.entries];

package/dist/remote/protocol.d.ts

@@ -9,9 +9,9 @@ export interface PromptResolvedMessage {
     type: 'prompt_resolved';
     id: string;
 }
+/** The single task-widget slot. `lines: null` clears it. */
 export interface WidgetMessage {
     type: 'widget';
-    key: string;
     lines: string[] | null;
 }
 export interface NotifyMessage {
@@ -40,10 +40,13 @@ export interface ContextMessage {
 export interface ResetMessage {
     type: 'reset';
 }
-/** Server → browser messages added by the integration. The existing
- *  history / text_delta / tool_* / agent_* / client_count / user_message messages are
- *  emitted ad hoc by events.ts / server.ts and are not enumerated here. */
-export type ServerMessage = PromptMessage | PromptResolvedMessage | WidgetMessage | NotifyMessage | ViewerMessage | ContextMessage | ResetMessage;
+/** The full authoritative state sent to a (re)connecting client. Defined in
+ *  session-state.ts (its serializer); re-exported here as part of the wire type. */
+export type { SnapshotMessage } from './session-state.js';
+/** Server → browser messages. The live text_delta / tool_* / agent_* /
+ *  client_count / user_message deltas are emitted by the SessionState mutators
+ *  and not all enumerated here; the snapshot below carries the full state. */
+export type ServerMessage = PromptMessage | PromptResolvedMessage | WidgetMessage | NotifyMessage | ViewerMessage | ContextMessage | ResetMessage | import('./session-state.js').SnapshotMessage;
 /** Browser → server messages. */
 export interface ClientChatMessage {
     type: 'message';

package/dist/remote/register.js

@@ -1,7 +1,6 @@
-import { broadcast } from './broadcast.js';
 import { getBridge, dispatchRemoteLine, dispatchRemoteNewSession, makeShimmedCtx } from './bridge.js';
 import { setupEvents } from './events.js';
-import { HistoryBuffer } from './history.js';
+import { reset, addUserTurn } from './session-state.js';
 import { html } from './ui.js';
 import { qrLines } from './qr.js';
 import { startServer, formatAddresses } from './server.js';
@@ -12,7 +11,6 @@ if (!_g.__piRemote)
     _g.__piRemote = { server: null, send: null, serveResult: null };
 const S = _g.__piRemote;
 export function registerRemote(pi) {
-    const history = new HistoryBuffer(20);
     async function ensureServer() {
         if (S.server)
             return S.server;
@@ -29,7 +27,7 @@ export function registerRemote(pi) {
             }
             dispatchRemoteLine(text, {
                 onPlain: plain => {
-                    history.addUserMessage(plain);
+                    addUserTurn(plain);
                     if (isAgentIdle()) {
                         S.send?.(plain);
                     }
@@ -38,7 +36,7 @@ export function registerRemote(pi) {
                     }
                 }
             });
-        }, wsUrl => html(wsUrl), () => history.getEntries());
+        }, wsUrl => html(wsUrl));
         // Hands-off HTTPS: point Tailscale serve at our port so phones get a
         // secure context. Best-effort — any failure degrades to the http URL.
         S.serveResult = await ensureTailscaleServe(S.server.port).catch(() => ({ state: 'unavailable' }));
@@ -47,13 +45,11 @@ export function registerRemote(pi) {
     pi.on('session_start', (_event, ctx) => {
         S.send = (text, opts) => (opts ? pi.sendUserMessage(text, opts) : pi.sendUserMessage(text));
         // A new session (incl. /new and the /task handoff's newSession) means the
-        // browser is showing a stale transcript/widgets — wipe both ends.
+        // browser is showing a stale transcript/widgets — wipe the authoritative
+        // state and tell connected clients to clear.
         const bridge = getBridge();
-        bridge.activeWidgets.clear();
-        bridge.activePrompt = null;
-        bridge.lastContextUsage = null;
-        broadcast({ type: 'reset' });
-        setupEvents(pi, history, broadcast);
+        reset();
+        setupEvents(pi);
         // Seed a shimmed ctx so commands that don't need newSession (/task-list,
         // /task-cancel, /task-auto-cancel) work immediately from the remote without
         // any terminal interaction. Only overwrite if null or already shimmed —

package/dist/remote/server.d.ts

@@ -1,4 +1,3 @@
-import type { Turn } from './history.js';
 export interface LocalIPs {
     /** Tailscale (tailscale0) IPv4 address, if the interface is up. */
     tailscale?: string;
@@ -27,5 +26,5 @@ export declare function getLocalIPs(nets?: NodeJS.Dict<import("node:os").Network
 /** Build the labeled URL lines shown under the QR code. Both Tailscale and LAN
  *  when present; a single unlabeled primary URL when neither resolves. */
 export declare function formatAddresses(ips: LocalIPs, port: number): AddressLine[];
-export declare function startServer(onMessage: MessageCallback, getHtml: (wsUrl: string) => string, getHistory: () => Turn[]): Promise<ServerHandle>;
+export declare function startServer(onMessage: MessageCallback, getHtml: (wsUrl: string) => string): Promise<ServerHandle>;
 export {};

package/dist/remote/server.js

@@ -2,7 +2,8 @@ import { createServer } from 'node:http';
 import { networkInterfaces } from 'node:os';
 import { WebSocketServer } from 'ws';
 import { addClient, removeClient, clientCount, broadcast, sendTo } from './broadcast.js';
-import { getBridge, answerPrompt } from './bridge.js';
+import { answerPrompt } from './bridge.js';
+import { getState, snapshot } from './session-state.js';
 import { isClientMessage } from './protocol.js';
 import { swJs } from './sw.js';
 import { publicKey, addSubscription, getSubscriptions, logPush } from './push.js';
@@ -59,7 +60,7 @@ async function findPort(start, max) {
     }
     throw new Error(`No free port found in range ${start}–${start + max - 1}`);
 }
-export async function startServer(onMessage, getHtml, getHistory) {
+export async function startServer(onMessage, getHtml) {
     const port = await findPort(8800, 100);
     const ips = getLocalIPs();
     const ip = ips.primary;
@@ -118,16 +119,8 @@ export async function startServer(onMessage, getHtml, getHistory) {
         addClient(ws);
         handle.onFirstConnect?.();
         handle.onFirstConnect = null;
-        sendTo(ws, { type: 'history', turns: getHistory() });
-        const bridge = getBridge();
-        for (const [key, lines] of bridge.activeWidgets) {
-            sendTo(ws, { type: 'widget', key, lines });
-        }
-        if (bridge.activePrompt)
-            sendTo(ws, bridge.activePrompt);
-        if (bridge.lastContextUsage) {
-            sendTo(ws, { type: 'context', contextUsage: bridge.lastContextUsage });
-        }
+        // One authoritative snapshot — the client replaces its whole view with it.
+        sendTo(ws, snapshot());
         broadcast({ type: 'client_count', count: clientCount() });
         ws.on('message', data => {
             let msg;
@@ -145,7 +138,7 @@ export async function startServer(onMessage, getHtml, getHistory) {
             }
             // type === 'message': ignore while a prompt is pending (composer is
             // disabled in the browser; this is the server-side guard).
-            if (getBridge().activePrompt)
+            if (getState().prompt)
                 return;
             onMessage(msg.text);
         });

package/dist/remote/session-state.d.ts

@@ -0,0 +1,54 @@
+import { HistoryBuffer } from './history.js';
+import type { Turn, Part } from './history.js';
+import type { ContextUsage, PromptMessage } from './protocol.js';
+export interface LiveTurn {
+    /** Ordered assistant content (text segments + tool calls) for this run. */
+    parts: Part[];
+    /** Is the trailing text part still accumulating deltas? Closed by text_end /
+     *  a tool start, so the next text begins a fresh segment (separate bubble). */
+    textOpen: boolean;
+}
+export interface SnapshotMessage {
+    type: 'snapshot';
+    turns: Turn[];
+    live: LiveTurn | null;
+    agentRunning: boolean;
+    taskWidget: string[] | null;
+    prompt: PromptMessage | null;
+    context: ContextUsage | null;
+}
+interface SessionState {
+    history: HistoryBuffer;
+    live: LiveTurn | null;
+    agentRunning: boolean;
+    taskWidget: string[] | null;
+    prompt: PromptMessage | null;
+    context: ContextUsage | null;
+    /** Broadcast sink — swapped in tests via _setSink. */
+    sink: (msg: unknown) => void;
+}
+export declare function getState(): SessionState;
+/** @internal Test-only: swap the broadcast sink to capture emitted deltas. */
+export declare function _setSink(fn: (msg: unknown) => void): void;
+export declare function agentStart(): void;
+export declare function appendText(delta: string): void;
+export declare function textEnd(): void;
+export declare function startTool(toolCallId: string, toolName: string, args: unknown): void;
+export declare function updateTool(toolCallId: string, partialResult: unknown): void;
+export declare function endTool(toolCallId: string, toolName: string, result: unknown, isError: boolean): void;
+export declare function agentEnd(context: ContextUsage): void;
+export declare function addUserTurn(text: string): void;
+export declare function addError(message: string): void;
+/** A persistent inline note (committed to the transcript so it survives reconnect)
+ *  plus a live delta so connected clients render it immediately. */
+export declare function addSystemNote(text: string): void;
+/** The single task-widget slot. Empty/undefined lines clear it. */
+export declare function setTaskWidget(lines: string[] | null | undefined): void;
+export declare function setPrompt(prompt: PromptMessage): void;
+export declare function clearPrompt(id: string): void;
+export declare function setContext(context: ContextUsage): void;
+/** Wipe everything (new session) and tell connected clients to clear. */
+export declare function reset(): void;
+/** Serialize the whole state for a (re)connecting client. */
+export declare function snapshot(): SnapshotMessage;
+export {};

package/dist/remote/session-state.js

@@ -0,0 +1,179 @@
+// The single authoritative mirror of what a connected browser should be showing.
+//
+// Every change funnels through a mutator that (1) updates this object and (2)
+// broadcasts the matching live delta. On (re)connect the server serializes the
+// whole object with snapshot() and the client replaces its entire view. Because
+// the snapshot and the live deltas read/write the same object, they can never
+// disagree — which is what kills the duplicate-transcript / orphaned-widget /
+// two-task-widget drift the ad-hoc broadcasting used to cause.
+//
+// State lives on globalThis so it survives jiti module re-evaluation on session
+// switches, the same pattern broadcast.ts and bridge.ts use.
+import { broadcast as wsBroadcast } from './broadcast.js';
+import { HistoryBuffer } from './history.js';
+const g = globalThis;
+function fresh() {
+    return {
+        history: new HistoryBuffer(20),
+        live: null,
+        agentRunning: false,
+        taskWidget: null,
+        prompt: null,
+        context: null,
+        sink: wsBroadcast
+    };
+}
+export function getState() {
+    if (!g.__piSessionState)
+        g.__piSessionState = fresh();
+    return g.__piSessionState;
+}
+/** @internal Test-only: swap the broadcast sink to capture emitted deltas. */
+export function _setSink(fn) {
+    getState().sink = fn;
+}
+function ensureLive(s) {
+    if (!s.live)
+        s.live = { parts: [], textOpen: false };
+    return s.live;
+}
+// ─── Mutators ────────────────────────────────────────────────────────────────
+export function agentStart() {
+    const s = getState();
+    s.live = { parts: [], textOpen: false };
+    s.agentRunning = true;
+    s.sink({ type: 'agent_start' });
+}
+export function appendText(delta) {
+    const s = getState();
+    const live = ensureLive(s);
+    const last = live.parts[live.parts.length - 1];
+    if (live.textOpen && last && last.kind === 'text') {
+        last.text += delta;
+    }
+    else {
+        live.parts.push({ kind: 'text', text: delta });
+        live.textOpen = true;
+    }
+    s.sink({ type: 'text_delta', delta });
+}
+export function textEnd() {
+    const s = getState();
+    if (s.live)
+        s.live.textOpen = false; // next text starts a new segment
+    s.sink({ type: 'text_end' });
+}
+export function startTool(toolCallId, toolName, args) {
+    const s = getState();
+    const live = ensureLive(s);
+    live.textOpen = false;
+    live.parts.push({
+        kind: 'tool',
+        toolCallId,
+        toolName,
+        args,
+        result: undefined,
+        isError: false,
+        done: false
+    });
+    s.sink({ type: 'tool_start', toolCallId, toolName, args });
+}
+export function updateTool(toolCallId, partialResult) {
+    getState().sink({ type: 'tool_update', toolCallId, partialResult });
+}
+export function endTool(toolCallId, toolName, result, isError) {
+    const s = getState();
+    const live = ensureLive(s);
+    const part = live.parts.find((p) => p.kind === 'tool' && p.toolCallId === toolCallId);
+    if (part) {
+        part.result = result;
+        part.isError = isError;
+        part.done = true;
+    }
+    else {
+        // tool_end without a matching start (shouldn't happen) — append a done tool.
+        live.parts.push({
+            kind: 'tool',
+            toolCallId,
+            toolName,
+            args: undefined,
+            result,
+            isError,
+            done: true
+        });
+    }
+    s.sink({ type: 'tool_end', toolCallId, toolName, result, isError });
+}
+export function agentEnd(context) {
+    const s = getState();
+    if (s.live)
+        s.history.addAssistantTurn(s.live.parts);
+    s.live = null;
+    s.agentRunning = false;
+    s.context = context;
+    s.sink({ type: 'agent_end', contextUsage: context });
+}
+export function addUserTurn(text) {
+    const s = getState();
+    s.history.addUserMessage(text);
+    s.sink({ type: 'user_message', text });
+}
+export function addError(message) {
+    const s = getState();
+    s.history.addError(message);
+    s.live = null;
+    s.agentRunning = false;
+    s.sink({ type: 'agent_error', message });
+}
+/** A persistent inline note (committed to the transcript so it survives reconnect)
+ *  plus a live delta so connected clients render it immediately. */
+export function addSystemNote(text) {
+    const s = getState();
+    s.history.addSystemNote(text);
+    s.sink({ type: 'system_note', text });
+}
+/** The single task-widget slot. Empty/undefined lines clear it. */
+export function setTaskWidget(lines) {
+    const s = getState();
+    s.taskWidget = lines && lines.length ? lines : null;
+    s.sink({ type: 'widget', lines: s.taskWidget });
+}
+export function setPrompt(prompt) {
+    const s = getState();
+    s.prompt = prompt;
+    s.sink(prompt);
+}
+export function clearPrompt(id) {
+    const s = getState();
+    s.prompt = null;
+    s.sink({ type: 'prompt_resolved', id });
+}
+export function setContext(context) {
+    const s = getState();
+    s.context = context;
+    s.sink({ type: 'context', contextUsage: context });
+}
+/** Wipe everything (new session) and tell connected clients to clear. */
+export function reset() {
+    const s = getState();
+    s.history = new HistoryBuffer(20);
+    s.live = null;
+    s.agentRunning = false;
+    s.taskWidget = null;
+    s.prompt = null;
+    s.context = null;
+    s.sink({ type: 'reset' });
+}
+/** Serialize the whole state for a (re)connecting client. */
+export function snapshot() {
+    const s = getState();
+    return {
+        type: 'snapshot',
+        turns: s.history.getEntries(),
+        live: s.live ? { parts: [...s.live.parts], textOpen: s.live.textOpen } : null,
+        agentRunning: s.agentRunning,
+        taskWidget: s.taskWidget,
+        prompt: s.prompt,
+        context: s.context
+    };
+}

package/dist/remote/ui.js

@@ -85,6 +85,13 @@ export function html(wsUrl) {
       background: var(--crust); color: var(--red); align-self: stretch;
       max-width: 100%; border: 1px solid var(--red); font-size: 12px;
     }
+    /* Persistent inline system note (e.g. context compaction) — a muted centered
+       divider, distinct from chat bubbles. */
+    .sysnote {
+      align-self: center; color: var(--subtext0); font-size: 11px;
+      font-family: ui-monospace, monospace; letter-spacing: 0.5px;
+      padding: 2px 10px; opacity: 0.85;
+    }
     .bubble.thinking {
       display: flex; gap: 5px; align-items: center; padding: 10px 14px;
     }
@@ -172,11 +179,12 @@ export function html(wsUrl) {
       font-size: 13px; z-index: 100; letter-spacing: 0.03em;
     }
     #reconnect-overlay.visible { display: flex; }
+    /* Trailing stream indicator: the same braille spinner as the thinking bubble,
+       inline at the end of the streaming text (not a green blinking block). */
     .cursor {
-      display: inline-block; width: 7px; height: 1em; vertical-align: text-bottom;
-      background: var(--green); animation: blink 1s step-end infinite; margin-left: 1px;
+      color: var(--mauve); margin-left: 2px;
+      font-family: ui-monospace, monospace;
     }
-    @keyframes blink { 50% { opacity: 0; } }
     #status-panel { padding: 6px 12px; border-bottom: 1px solid var(--surface1);
       color: var(--subtext1); white-space: pre-wrap; font-size: 13px; display: none; }
     #prompt-card { position: fixed; left: 0; right: 0; bottom: 0; background: var(--mantle);
@@ -276,12 +284,13 @@ export function html(wsUrl) {
     const statusPanel = document.getElementById('status-panel');
     // Widgets are keyed (e.g. 'pi-tasks', 'pi-task-auto'); track them per key so a
     // clear for one key can't be masked by a stale message from another.
-    const widgets = {};
+    // Single authoritative task-widget slot. The snapshot and the live 'widget'
+    // delta both set this; null hides the panel. (No more per-key map that could
+    // strand an orphaned widget on screen.)
+    let taskWidgetLines = null;
     function renderWidgets() {
-      let all = [];
-      for (const k in widgets) if (widgets[k] && widgets[k].length) all = all.concat(widgets[k]);
-      if (all.length) {
-        statusPanel.textContent = all.join('\\n');
+      if (taskWidgetLines && taskWidgetLines.length) {
+        statusPanel.textContent = taskWidgetLines.join('\\n');
         statusPanel.style.display = 'block';
       } else {
         statusPanel.style.display = 'none';
@@ -488,30 +497,46 @@ export function html(wsUrl) {
     let spinTimer = null;
     let spinIdx = 0;
     const SPIN = '\\u280B\\u2819\\u2839\\u2838\\u283C\\u2834\\u2826\\u2827\\u2807\\u280F';
+    // One braille ticker drives every '.spin' element — the thinking bubble AND the
+    // trailing stream cursor — so they share the same frame and look identical.
+    function spinPaint() {
+      const g = SPIN[spinIdx % SPIN.length];
+      const els = document.getElementsByClassName('spin');
+      for (let i = 0; i < els.length; i++) els[i].textContent = g;
+    }
+    function startSpin() {
+      spinPaint();
+      if (spinTimer) return;
+      spinTimer = setInterval(function () {
+        spinIdx = (spinIdx + 1) % SPIN.length;
+        spinPaint();
+      }, 90);
+    }
+    // Stop the ticker once nothing on screen needs spinning.
+    function stopSpinIfIdle() {
+      if (spinTimer && !document.querySelector('.spin')) {
+        clearInterval(spinTimer); spinTimer = null;
+      }
+    }
     function showThinking() {
       if (!thinkingEl) {
         thinkingEl = document.createElement('div');
         thinkingEl.className = 'bubble assistant thinking';
-        thinkingEl.innerHTML = '<span class="spinner"></span>';
-      }
-      if (!spinTimer) {
-        var sp = thinkingEl.firstChild;
-        sp.textContent = SPIN[spinIdx % SPIN.length];
-        spinTimer = setInterval(function () {
-          spinIdx = (spinIdx + 1) % SPIN.length;
-          sp.textContent = SPIN[spinIdx];
-        }, 90);
+        thinkingEl.innerHTML = '<span class="spinner spin"></span>';
       }
       chatLog.appendChild(thinkingEl); // append (or move) to bottom
+      startSpin();
       scrollBottom();
     }
     function hideThinking() {
-      if (spinTimer) { clearInterval(spinTimer); spinTimer = null; }
       if (thinkingEl) thinkingEl.remove();
+      stopSpinIfIdle();
     }
 
     function addToolCall(toolName, argsStr, isError) {
-      const label = (toolName + ': ' + argsStr).slice(0, 64);
+      // argsStr can be undefined (no args / JSON.stringify(undefined)); don't let
+      // that render as the literal "name: undefined" in the collapsed summary.
+      const label = (toolName + (argsStr ? ': ' + argsStr : '')).slice(0, 64);
       const d = document.createElement('details');
       d.className = 'tool-call' + (isError ? ' error' : '');
       const s = document.createElement('summary');
@@ -528,6 +553,82 @@ export function html(wsUrl) {
       sendBtn.disabled = !allow;
     }
 
+    // Stringify a tool result safely. A null/undefined result (e.g. a tool that
+    // hasn't produced output) must NOT become the JS value undefined, whose
+    // .slice() throws — a throw here aborts the whole snapshot rebuild after the
+    // log was already cleared, blanking the transcript on reconnect.
+    function toolResultText(result) {
+      if (result == null) return '';
+      const r = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+      return (r == null ? '' : r).slice(0, 8000);
+    }
+
+    // Render one tool part from the ordered parts list (running or finished).
+    function renderToolPart(p) {
+      const argsStr = typeof p.args === 'string' ? p.args : JSON.stringify(p.args);
+      const d = addToolCall(p.toolName, argsStr, p.isError);
+      if (p.done) {
+        const pre = document.createElement('pre');
+        pre.textContent = toolResultText(p.result);
+        d.appendChild(pre);
+      } else {
+        toolCallMap[p.toolCallId] = d; // a later tool_end delta fills the result
+      }
+      return d;
+    }
+
+    // A muted, centered system note (e.g. "Context compacted").
+    function addSystemLine(text) {
+      const el = document.createElement('div');
+      el.className = 'sysnote';
+      el.textContent = text;
+      chatLog.appendChild(el);
+      scrollBottom();
+      return el;
+    }
+
+    // Render one committed transcript turn. Assistant turns are an ordered list of
+    // parts (text segments + tool calls), so the layout matches the terminal's
+    // interleaving instead of one merged blob with tools dumped at the end.
+    function renderTurn(t) {
+      if (t.error) { addBubble('error', t.text); return; }
+      if (t.role === 'system') { addSystemLine(t.text); return; }
+      if (t.role === 'user') { addBubble('user', t.text); return; }
+      for (const p of (t.parts || [])) {
+        if (p.kind === 'text') { if (p.text) addBubble('assistant', p.text); }
+        else renderToolPart(p);
+      }
+    }
+
+    // Render the in-progress assistant turn from a snapshot, preserving order. The
+    // trailing OPEN text segment becomes the live streaming bubble (cursor + spin)
+    // so subsequent text_delta frames keep flowing into it.
+    function renderLiveTurn(live) {
+      const parts = live.parts || [];
+      for (let i = 0; i < parts.length; i++) {
+        const p = parts[i];
+        const last = i === parts.length - 1;
+        if (p.kind === 'text') {
+          if (last && live.textOpen) {
+            currentBubble = document.createElement('div');
+            currentBubble.className = 'bubble assistant';
+            const cursor = document.createElement('span');
+            cursor.className = 'cursor spin';
+            currentBubble.appendChild(cursor);
+            if (p.text) currentBubble.insertBefore(document.createTextNode(p.text), cursor);
+            chatLog.appendChild(currentBubble);
+            streamText = p.text || '';
+            startSpin();
+            scrollBottom();
+          } else if (p.text) {
+            addBubble('assistant', p.text);
+          }
+        } else {
+          renderToolPart(p);
+        }
+      }
+    }
+
     function showToast(message, level) {
       const t = document.createElement('div');
       t.className = 'toast ' + (level || 'info');
@@ -731,19 +832,27 @@ export function html(wsUrl) {
 
     function handleMsg(msg) {
       switch (msg.type) {
-        case 'history':
-          for (const t of (msg.turns || [])) {
-            if (t.error) { addBubble('error', t.text); continue; }
-            addBubble(t.role, t.text);
-            for (const tool of (t.tools || [])) {
-              const d = addToolCall(tool.toolName, JSON.stringify(tool.args), tool.isError);
-              const pre = document.createElement('pre');
-              const r = typeof tool.result === 'string' ? tool.result : JSON.stringify(tool.result, null, 2);
-              pre.textContent = r.slice(0, 8000);
-              d.appendChild(pre);
-            }
-          }
+        case 'snapshot': {
+          // Authoritative full state on every (re)connect: replace the WHOLE view.
+          // This is what kills duplicated transcript / stale-orphaned widgets —
+          // whatever was on screen is discarded and rebuilt from server truth.
+          chatLog.innerHTML = '';
+          closePrompt();
+          hideThinking();
+          currentBubble = null; streamText = '';
+          for (const k in toolCallMap) delete toolCallMap[k];
+          // Per-turn try/catch: one malformed turn must never abort the rebuild
+          // and leave the (already-cleared) transcript blank.
+          for (const t of (msg.turns || [])) { try { renderTurn(t); } catch (e) {} }
+          if (msg.live) { try { renderLiveTurn(msg.live); } catch (e) {} }
+          taskWidgetLines = (msg.taskWidget && msg.taskWidget.length) ? msg.taskWidget : null;
+          renderWidgets();
+          if (msg.context) setContextBar(msg.context); else contextFill.style.width = '0%';
+          if (msg.prompt) showPrompt(msg.prompt);
+          setEnabled(!msg.agentRunning && !msg.prompt);
+          if (msg.agentRunning && !msg.live) showThinking();
           break;
+        }
         case 'agent_start':
           autoScroll = true;
           streamText = '';
@@ -757,9 +866,10 @@ export function html(wsUrl) {
             currentBubble = document.createElement('div');
             currentBubble.className = 'bubble assistant';
             const cursor = document.createElement('span');
-            cursor.className = 'cursor';
+            cursor.className = 'cursor spin';
             currentBubble.appendChild(cursor);
             chatLog.appendChild(currentBubble);
+            startSpin();
           }
           streamText += msg.delta;
           {
@@ -773,6 +883,11 @@ export function html(wsUrl) {
             const c = currentBubble.querySelector('.cursor');
             if (c) c.remove();
             if (streamText) setContent(currentBubble, streamText);
+            // Close this message's bubble so the next text segment (after a tool or
+            // the next message) starts a fresh bubble — matching the terminal.
+            currentBubble = null;
+            streamText = '';
+            stopSpinIfIdle();
           }
           break;
         case 'tool_start': {
@@ -786,8 +901,7 @@ export function html(wsUrl) {
           if (d) {
             if (msg.isError) d.classList.add('error');
             const pre = document.createElement('pre');
-            const r = typeof msg.result === 'string' ? msg.result : JSON.stringify(msg.result, null, 2);
-            pre.textContent = r.slice(0, 8000);
+            pre.textContent = toolResultText(msg.result);
             d.appendChild(pre);
             delete toolCallMap[msg.toolCallId];
           }
@@ -800,6 +914,9 @@ export function html(wsUrl) {
         case 'user_message':
           addBubble('user', msg.text);
           break;
+        case 'system_note':
+          addSystemLine(msg.text);
+          break;
         case 'agent_error':
           hideThinking();
           if (currentBubble) {
@@ -808,6 +925,7 @@ export function html(wsUrl) {
             if (streamText) setContent(currentBubble, streamText);
             currentBubble = null;
             streamText = '';
+            stopSpinIfIdle();
           }
           addBubble('error', msg.message || 'Error');
           setEnabled(true);
@@ -833,8 +951,7 @@ export function html(wsUrl) {
           if (activePromptId === msg.id) closePrompt();
           break;
         case 'widget':
-          if (msg.lines && msg.lines.length) widgets[msg.key] = msg.lines;
-          else delete widgets[msg.key];
+          taskWidgetLines = (msg.lines && msg.lines.length) ? msg.lines : null;
           renderWidgets();
           break;
         case 'notify':
@@ -850,7 +967,7 @@ export function html(wsUrl) {
           hideThinking();
           currentBubble = null; streamText = '';
           closePrompt();
-          for (const k in widgets) delete widgets[k];
+          taskWidgetLines = null;
           renderWidgets();
           contextFill.style.width = '0%';
           break;

package/dist/task/widget.js

@@ -5,7 +5,7 @@
  * context usage, and the latest child-process line.
  */
 import { PHASE_INDEX, PHASE_ORDER } from './task-file.js';
-import { publishWidget } from '../remote/bridge.js';
+import { setTaskWidget } from '../remote/session-state.js';
 // ─── Constants ───────────────────────────────────────────────────────────────
 export const WIDGET_KEY = 'pi-tasks';
 export const AUTO_WIDGET_KEY = 'pi-task-auto';
@@ -101,7 +101,7 @@ export function startWidget(ctx, getState) {
         catch {
             /* stale ctx */
         }
-        publishWidget(WIDGET_KEY, plain);
+        setTaskWidget(plain);
     };
     render();
     const timer = setInterval(render, WIDGET_REFRESH_MS);
@@ -114,7 +114,7 @@ export function startWidget(ctx, getState) {
         catch {
             /* stale ctx */
         }
-        publishWidget(WIDGET_KEY, undefined);
+        setTaskWidget(undefined);
     };
 }
 export function buildAutoLoaderLines(s, theme) {
@@ -150,7 +150,7 @@ export function startAutoLoader(ctx, getState) {
         catch {
             /* stale ctx */
         }
-        publishWidget(AUTO_WIDGET_KEY, plain);
+        setTaskWidget(plain);
     };
     render();
     const timer = setInterval(render, WIDGET_REFRESH_MS);
@@ -163,7 +163,7 @@ export function startAutoLoader(ctx, getState) {
         catch {
             /* stale ctx */
         }
-        publishWidget(AUTO_WIDGET_KEY, undefined);
+        setTaskWidget(undefined);
     };
 }
 export function flashTerminalWidget(ctx, state, taskId, reason) {
@@ -185,7 +185,7 @@ export function flashTerminalWidget(ctx, state, taskId, reason) {
         : `✘ ${taskId} failed${reason ? ': ' + reason : ''}`;
     try {
         ctx.ui.setWidget(WIDGET_KEY, [line]);
-        publishWidget(WIDGET_KEY, [plainLine]);
+        setTaskWidget([plainLine]);
     }
     catch {
         /* stale ctx */
@@ -193,7 +193,7 @@ export function flashTerminalWidget(ctx, state, taskId, reason) {
     setTimeout(() => {
         try {
             ctx.ui.setWidget(WIDGET_KEY, undefined);
-            publishWidget(WIDGET_KEY, undefined);
+            setTaskWidget(undefined);
         }
         catch {
             /* stale ctx */

package/dist/workers/pi-worker-docs.js

@@ -20,17 +20,20 @@ export function registerPiWorkerDocs(pi, internals = {}) {
     pi.registerTool({
         name: 'pi-worker-docs',
         label: 'Pi Worker Docs',
-        description: 'Look up an npm package locally and return a focused, version-pinned '
-            + 'answer extracted from its .d.ts types and README. No network after install (except a small '
-            + 'live npm registry call described below). The cache lives at ~/.cache/pi-worker/docs.sqlite '
-            + 'and is keyed by exact installed version.\n'
-            + 'If the package is not yet installed, it is installed automatically via bun add or npm install.\n'
-            + '\n'
-            + 'Live registry data: in addition to the docs answer, the tool fetches the latest published '
-            + 'version, recent versions, and publish date from the npm registry and prepends them to the '
-            + 'output (and exposes them in details). This is the source of truth for "what is the latest '
-            + 'version of X" questions — training-data versions are typically months stale. The lookup is '
-            + 'best-effort and silently absent when offline.\n'
+        description: 'Look up an INSTALLED npm package and return a focused, version-pinned '
+            + 'answer from its .d.ts types and README, PLUS the latest published version '
+            + 'from a live npm registry call. USE THIS BEFORE ANSWERING any question '
+            + 'about how to use a library, what it exports, its types/overloads/config, '
+            + 'or the latest published version of an npm package. Do NOT answer package '
+            + 'APIs from memory, do NOT run `npm view`/bash to get a package version, and '
+            + 'do NOT web-search for an installed package — this tool is the source of '
+            + 'truth and is version-pinned to what is actually installed (training-data '
+            + 'versions and APIs are typically months stale).\n'
+            + 'For a non-package framework/runtime version (e.g. Node.js, Ubuntu), use '
+            + '`pi-worker-search` instead. If the package is not installed it is '
+            + 'auto-installed via bun add or npm install. The cache lives at '
+            + '~/.cache/pi-worker/docs.sqlite, keyed by exact installed version; the '
+            + 'registry lookup is best-effort and silently absent when offline.\n'
             + '\n'
             + 'Good fits:\n'
             + '- "What does library X export?" / "How does function Y work?"\n'

package/dist/workers/pi-worker-search.js

@@ -14,9 +14,14 @@ export function registerPiWorkerSearch(pi, internals = {}) {
     pi.registerTool({
         name: 'pi-worker-search',
         label: 'Pi Worker Search',
-        description: 'Search the web via Brave Search. Returns a compact markdown list of '
-            + 'up to 10 results (title, URL, snippet). Use this to find candidate '
-            + 'URLs, then call `pi-worker-fetch` on the URL you want to read. '
+        description: 'Search the live web via Brave Search. CALL THIS BEFORE ANSWERING any '
+            + 'question about current or version-specific external facts: '
+            + 'library/framework versions and their APIs, latest releases, recently '
+            + 'shipped features, current events, prices, or who currently holds a '
+            + 'role. Your built-in knowledge is out of date — do NOT answer such '
+            + 'questions from memory and do NOT shell out with bash to guess. Returns '
+            + 'a compact markdown list of up to 10 results (title, URL, snippet); then '
+            + 'call `pi-worker-fetch` on the URL you want to read. '
             + 'Requires BRAVE_SEARCH_API_KEY env var.',
         parameters: Params,
         executionMode: 'parallel',

package/dist/workers/pi-worker.js

@@ -18,16 +18,19 @@ export function registerPiWorker(pi) {
     pi.registerTool({
         name: 'pi-worker',
         label: 'Pi Worker',
-        description: 'Dispatch an isolated child Pi to investigate a question and return its '
-            + 'conclusion — not the raw evidence. Use when answering requires reading '
-            + 'multiple files, running several greps, or scanning large command output '
-            + 'you do not need verbatim.\n'
+        description: 'Dispatch an isolated child Pi to investigate and return its CONCLUSION — '
+            + 'not the raw evidence. USE THIS FIRST, instead of running your own '
+            + 'ls/grep/find/read, whenever a question spans MULTIPLE files or means '
+            + 'searching/scanning code you have not already located. Doing it yourself '
+            + 'floods your context with raw file output; the worker reads in isolation '
+            + 'and returns only the answer. You can dispatch several in one turn for '
+            + 'independent questions.\n'
             + '\n'
             + 'Good fits:\n'
             + '- "Where/how is X handled in this repo?" across unfamiliar code\n'
             + '- Audits and pattern scans across many files ("every place we log PII")\n'
-            + '- Summarising long test output, logs, or shell output\n'
-            + '- Parallel fan-out: dispatch several workers in one turn for independent questions\n'
+            + '- Tracing a flow across layers (router → service → database)\n'
+            + '- Summarising long test output, logs, or shell output you do not need verbatim\n'
             + '\n'
             + 'Skip when:\n'
             + '- You already know the exact file — call `read` directly\n'

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.7.0",
+    "version": "0.7.1",
     "description": "Deterministic spec-orchestration for local models, with a bundled real-time remote web view and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",