@mjasnikovs/pi-task 0.6.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,12 +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,
@@ -55,8 +54,9 @@ 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
         // the rejection some implementations throw on abort so it never leaks.
         const local = this.ctx.hasUI ?
@@ -75,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,21 +1,18 @@
 import { setAgentIdle } from './state.js';
-import { getBridge } from './bridge.js';
-export function setupEvents(pi, history, broadcastFn) {
-    let currentText = '';
-    const currentTools = [];
-    const pendingArgs = new Map();
+import { pushNotify } from './push.js';
+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' ?
@@ -24,61 +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 });
-        currentText = '';
-        currentTools.length = 0;
+        agentEnd(ctx.getContextUsage());
+        void pushNotify('Task finished', '', 'pi-end').catch(() => { });
     });
     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 {
@@ -35,10 +35,18 @@ export interface ContextMessage {
     type: 'context';
     contextUsage: ContextUsage;
 }
-/** 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;
+/** Tells the browser to wipe the transcript/widgets/prompt when a new session
+ *  starts, so it reflects the fresh session instead of the previous one. */
+export interface ResetMessage {
+    type: 'reset';
+}
+/** 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/push.d.ts

@@ -0,0 +1,52 @@
+/** Minimal shape of a browser PushSubscription serialized to JSON. */
+export interface PushSubscriptionJSON {
+    endpoint?: string;
+    expirationTime?: number | null;
+    keys?: {
+        p256dh: string;
+        auth: string;
+    };
+}
+export interface VapidKeys {
+    publicKey: string;
+    privateKey: string;
+}
+/** Where the VAPID keypair is persisted. Follows the repo's XDG convention
+ *  (see workers/docs-core.ts), but under data-home so it survives cache clears —
+ *  losing these keys invalidates every existing browser subscription. */
+export declare function vapidStorePath(): string;
+/** Diagnostic log file. Defaults to /tmp for easy tailing; override with
+ *  PI_REMOTE_PUSH_LOG. (The VAPID key stays in its durable XDG location.) */
+export declare function pushLogPath(): string;
+/** VAPID JWT `sub` claim. Apple (unlike Chrome/FCM) validates this and rejects
+ *  tokens with an unroutable subject like `mailto:...@localhost` as BadJwtToken,
+ *  so the default is a real https URL. Override with PI_REMOTE_PUSH_SUBJECT
+ *  (e.g. your own `mailto:you@domain.com`). */
+export declare function pushSubject(): string;
+/** Append a timestamped diagnostic line — but only when PI_REMOTE_PUSH_DEBUG is
+ *  set, so it stays silent (and test-safe) by default. Push failures are
+ *  otherwise swallowed, so this is the way to see Apple's HTTP status codes. */
+export declare function logPush(line: string): void;
+/** Load the persisted VAPID keypair, generating and saving one on first use or
+ *  if the stored file is missing/corrupt. Stable across restarts. */
+export declare function loadOrCreateVapidKeys(file?: string): VapidKeys;
+export declare function addSubscription(sub: PushSubscriptionJSON): void;
+export declare function removeSubscription(endpoint: string): void;
+export declare function getSubscriptions(): PushSubscriptionJSON[];
+export declare function clearSubscriptions(): void;
+type SendFn = (sub: PushSubscriptionJSON, payload: string) => Promise<{
+    statusCode: number;
+}>;
+/** Fan a payload out to every subscription via `send`, pruning any the push
+ *  service reports as permanently gone. Network-free and fully testable; the
+ *  real web-push call is injected by pushNotify. */
+export declare function deliver(targets: PushSubscriptionJSON[], payload: string, send: SendFn): Promise<{
+    removed: string[];
+}>;
+/** The VAPID public key the browser needs as its applicationServerKey. */
+export declare function publicKey(): string;
+/** Send a notification to all subscribed devices. Best-effort: delivery is
+ *  server→push-service→device, so it reaches a suspended iOS PWA that the
+ *  in-page Notification API never could. */
+export declare function pushNotify(title: string, body: string, tag?: string): Promise<void>;
+export {};

package/dist/remote/push.js

@@ -0,0 +1,156 @@
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import webpush from 'web-push';
+/** Where the VAPID keypair is persisted. Follows the repo's XDG convention
+ *  (see workers/docs-core.ts), but under data-home so it survives cache clears —
+ *  losing these keys invalidates every existing browser subscription. */
+export function vapidStorePath() {
+    const base = process.env.XDG_DATA_HOME?.trim() || path.join(os.homedir(), '.local', 'share');
+    return path.join(base, 'pi-task', 'vapid.json');
+}
+/** Diagnostic log file. Defaults to /tmp for easy tailing; override with
+ *  PI_REMOTE_PUSH_LOG. (The VAPID key stays in its durable XDG location.) */
+export function pushLogPath() {
+    return process.env.PI_REMOTE_PUSH_LOG?.trim() || '/tmp/pi-task-push.log';
+}
+/** VAPID JWT `sub` claim. Apple (unlike Chrome/FCM) validates this and rejects
+ *  tokens with an unroutable subject like `mailto:...@localhost` as BadJwtToken,
+ *  so the default is a real https URL. Override with PI_REMOTE_PUSH_SUBJECT
+ *  (e.g. your own `mailto:you@domain.com`). */
+export function pushSubject() {
+    return process.env.PI_REMOTE_PUSH_SUBJECT?.trim() || 'https://github.com/mjasnikovs/pi-task';
+}
+/** Append a timestamped diagnostic line — but only when PI_REMOTE_PUSH_DEBUG is
+ *  set, so it stays silent (and test-safe) by default. Push failures are
+ *  otherwise swallowed, so this is the way to see Apple's HTTP status codes. */
+export function logPush(line) {
+    if (!process.env.PI_REMOTE_PUSH_DEBUG)
+        return;
+    try {
+        const file = pushLogPath();
+        mkdirSync(path.dirname(file), { recursive: true });
+        appendFileSync(file, `${new Date().toISOString()} ${line}\n`);
+    }
+    catch {
+        // diagnostics are best-effort; never let logging break a push
+    }
+}
+/** Short host label for an endpoint, for readable logs (full endpoints are long
+ *  and contain device tokens). */
+function endpointHost(sub) {
+    try {
+        return new URL(sub.endpoint ?? '').host;
+    }
+    catch {
+        return '?';
+    }
+}
+function isVapidKeys(x) {
+    if (typeof x !== 'object' || x === null)
+        return false;
+    const k = x;
+    return typeof k.publicKey === 'string' && typeof k.privateKey === 'string';
+}
+/** Load the persisted VAPID keypair, generating and saving one on first use or
+ *  if the stored file is missing/corrupt. Stable across restarts. */
+export function loadOrCreateVapidKeys(file = vapidStorePath()) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        if (isVapidKeys(parsed))
+            return { publicKey: parsed.publicKey, privateKey: parsed.privateKey };
+    }
+    catch {
+        // missing or corrupt — fall through and regenerate
+    }
+    const keys = webpush.generateVAPIDKeys();
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(keys), 'utf8');
+    return keys;
+}
+// In-memory subscription store, keyed by endpoint. Persisted on globalThis so it
+// survives jiti re-evaluation on session switches (same pattern as broadcast.ts).
+// Subscriptions themselves are not written to disk: the browser re-subscribes on
+// every page load, so an in-memory set is sufficient and self-healing.
+const g = globalThis;
+if (!g.__piRemoteSubs)
+    g.__piRemoteSubs = new Map();
+const subs = g.__piRemoteSubs;
+export function addSubscription(sub) {
+    if (!sub.endpoint)
+        return;
+    subs.set(sub.endpoint, sub);
+}
+export function removeSubscription(endpoint) {
+    subs.delete(endpoint);
+}
+export function getSubscriptions() {
+    return [...subs.values()];
+}
+export function clearSubscriptions() {
+    subs.clear();
+}
+/** True when the push service says the subscription is permanently gone and
+ *  should be dropped (404 Not Found, 410 Gone). */
+function isGone(err) {
+    const code = err?.statusCode;
+    return code === 404 || code === 410;
+}
+/** Fan a payload out to every subscription via `send`, pruning any the push
+ *  service reports as permanently gone. Network-free and fully testable; the
+ *  real web-push call is injected by pushNotify. */
+export async function deliver(targets, payload, send) {
+    const removed = [];
+    await Promise.all(targets.map(async (sub) => {
+        try {
+            await send(sub, payload);
+        }
+        catch (err) {
+            if (sub.endpoint && isGone(err)) {
+                removeSubscription(sub.endpoint);
+                removed.push(sub.endpoint);
+            }
+            // transient errors: keep the subscription, drop this push
+        }
+    }));
+    return { removed };
+}
+let configured = false;
+function ensureConfigured() {
+    const keys = loadOrCreateVapidKeys();
+    if (!configured) {
+        webpush.setVapidDetails(pushSubject(), keys.publicKey, keys.privateKey);
+        configured = true;
+    }
+    return keys;
+}
+/** The VAPID public key the browser needs as its applicationServerKey. */
+export function publicKey() {
+    return ensureConfigured().publicKey;
+}
+/** Send a notification to all subscribed devices. Best-effort: delivery is
+ *  server→push-service→device, so it reaches a suspended iOS PWA that the
+ *  in-page Notification API never could. */
+export async function pushNotify(title, body, tag) {
+    const targets = getSubscriptions();
+    logPush(`event "${title}" -> ${targets.length} subscription(s)`);
+    if (targets.length === 0)
+        return; // nobody subscribed — skip all VAPID/disk work
+    ensureConfigured();
+    const payload = JSON.stringify({ title, body, tag });
+    const { removed } = await deliver(targets, payload, async (sub, p) => {
+        try {
+            const res = await webpush.sendNotification(sub, p);
+            logPush(`send ${endpointHost(sub)} -> ${res.statusCode}`);
+            return res;
+        }
+        catch (err) {
+            const e = err;
+            logPush(`send ${endpointHost(sub)} -> ERROR ${e.statusCode ?? '?'} `
+                + `${(e.body || e.message || '').toString().trim().slice(0, 200)}`);
+            throw err; // rethrow so deliver can prune permanently-gone subscriptions
+        }
+    });
+    if (removed.length > 0)
+        logPush(`pruned ${removed.length} gone subscription(s)`);
+}

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' }));
@@ -46,17 +44,22 @@ export function registerRemote(pi) {
     }
     pi.on('session_start', (_event, ctx) => {
         S.send = (text, opts) => (opts ? pi.sendUserMessage(text, opts) : pi.sendUserMessage(text));
-        setupEvents(pi, history, broadcast);
+        // A new session (incl. /new and the /task handoff's newSession) means the
+        // browser is showing a stale transcript/widgets — wipe the authoritative
+        // state and tell connected clients to clear.
+        const bridge = getBridge();
+        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 —
         // a real command ctx captured from a prior terminal command must survive
         // session_start (it's updated via withSession or registerBridgeCommand,
         // not replaced here).
-        const b = getBridge();
-        if (!b.currentCtx
-            || b.currentCtx['__piRemoteShimmed'] === true) {
-            b.currentCtx = makeShimmedCtx(ctx);
+        if (!bridge.currentCtx
+            || bridge.currentCtx['__piRemoteShimmed']
+                === true) {
+            bridge.currentCtx = makeShimmedCtx(ctx);
         }
         void ensureServer().catch(err => ctx.ui.notify(`Failed to start remote: ${err.message}`, 'error'));
     });

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 {};