@mjasnikovs/pi-task 0.5.0 → 0.7.0

package/dist/remote/bridge.d.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent';
-import type { PromptMessage, ServerMessage } from './protocol.js';
+import type { ContextUsage, PromptMessage, 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>;
@@ -7,6 +7,8 @@ export interface BridgeState {
     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>;

package/dist/remote/bridge.js

@@ -1,4 +1,5 @@
 import { broadcast as wsBroadcast } from './broadcast.js';
+import { pushNotify } from './push.js';
 const g = globalThis;
 export function getBridge() {
     if (!g.__piBridge) {
@@ -6,6 +7,7 @@ export function getBridge() {
             pending: new Map(),
             activePrompt: null,
             activeWidgets: new Map(),
+            lastContextUsage: null,
             nextId: 0,
             commands: new Map(),
             currentCtx: null,
@@ -56,6 +58,8 @@ export class SessionUI {
         };
         b.activePrompt = prompt;
         b.broadcast(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 ?

package/dist/remote/events.js

@@ -1,4 +1,6 @@
 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 = [];
@@ -25,6 +27,7 @@ export function setupEvents(pi, history, broadcastFn) {
                 const message = errorMessage || 'Request failed';
                 history.addError(message);
                 broadcastFn({ type: 'agent_error', message });
+                void pushNotify('Agent error', message, 'pi-error').catch(() => { });
             }
         }
     });
@@ -67,8 +70,11 @@ export function setupEvents(pi, history, broadcastFn) {
     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 });
+        void pushNotify('Task finished', '', 'pi-end').catch(() => { });
         currentText = '';
         currentTools.length = 0;
     });

package/dist/remote/protocol.d.ts

@@ -24,10 +24,26 @@ export interface ViewerMessage {
     title: string;
     text: string;
 }
+export interface ContextUsage {
+    tokens?: number;
+    contextWindow?: number;
+    percent?: number;
+}
+/** Seeds the context-usage bar for a freshly-connected client (the live value is
+ *  otherwise only carried on agent_end). */
+export interface ContextMessage {
+    type: 'context';
+    contextUsage: ContextUsage;
+}
+/** 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';
+}
 /** 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;
+export type ServerMessage = PromptMessage | PromptResolvedMessage | WidgetMessage | NotifyMessage | ViewerMessage | ContextMessage | ResetMessage;
 /** 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

@@ -5,10 +5,11 @@ import { HistoryBuffer } from './history.js';
 import { html } from './ui.js';
 import { qrLines } from './qr.js';
 import { startServer, formatAddresses } from './server.js';
+import { ensureTailscaleServe, teardownTailscaleServe, planRemoteUrls } from './tailscale.js';
 import { isAgentIdle } from './state.js';
 const _g = globalThis;
 if (!_g.__piRemote)
-    _g.__piRemote = { server: null, send: null };
+    _g.__piRemote = { server: null, send: null, serveResult: null };
 const S = _g.__piRemote;
 export function registerRemote(pi) {
     const history = new HistoryBuffer(20);
@@ -38,10 +39,20 @@ export function registerRemote(pi) {
                 }
             });
         }, wsUrl => html(wsUrl), () => history.getEntries());
+        // 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' }));
         return S.server;
     }
     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.
+        const bridge = getBridge();
+        bridge.activeWidgets.clear();
+        bridge.activePrompt = null;
+        bridge.lastContextUsage = null;
+        broadcast({ type: 'reset' });
         setupEvents(pi, history, broadcast);
         // Seed a shimmed ctx so commands that don't need newSession (/task-list,
         // /task-cancel, /task-auto-cancel) work immediately from the remote without
@@ -49,17 +60,21 @@ export function registerRemote(pi) {
         // 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'));
     });
     pi.on('session_shutdown', (event, _ctx) => {
         if (event.reason === 'quit') {
             if (S.server) {
+                const port = S.server.port;
                 S.server.stop();
                 S.server = null;
+                S.serveResult = null;
+                void teardownTailscaleServe(port).catch(() => { });
             }
             S.send = null;
         }
@@ -69,8 +84,11 @@ export function registerRemote(pi) {
         handler: async (args, ctx) => {
             if (args.trim() === 'stop') {
                 if (S.server) {
+                    const port = S.server.port;
                     S.server.stop();
                     S.server = null;
+                    S.serveResult = null;
+                    void teardownTailscaleServe(port).catch(() => { });
                     ctx.ui.notify('Remote server stopped', 'info');
                 }
                 else {
@@ -82,11 +100,17 @@ export function registerRemote(pi) {
             getBridge().currentCtx = ctx;
             try {
                 const server = await ensureServer();
-                const primaryUrl = `http://${server.ip}:${server.port}`;
+                const httpPrimary = `http://${server.ip}:${server.port}`;
+                const result = S.serveResult ?? { state: 'unavailable' };
+                const plan = planRemoteUrls(httpPrimary, result);
+                const primaryUrl = plan.primaryUrl;
                 const qr = await qrLines(primaryUrl);
-                const addrs = formatAddresses(server.ips, server.port);
+                const addrs = [...plan.urlLines, ...formatAddresses(server.ips, server.port)];
                 const labelW = addrs.reduce((m, a) => Math.max(m, a.label.length), 0);
-                const addrLines = addrs.map(a => a.label ? `${a.label.padEnd(labelW)}  ${a.url}` : a.url);
+                const addrLines = [
+                    ...addrs.map(a => (a.label ? `${a.label.padEnd(labelW)}  ${a.url}` : a.url)),
+                    ...plan.hintLines
+                ];
                 const addrWidth = addrLines.reduce((m, l) => Math.max(m, l.length), 0);
                 if (ctx.mode === 'tui') {
                     // eslint-disable-next-line no-control-regex -- strip ANSI SGR escapes to measure visible width

package/dist/remote/server.js

@@ -4,6 +4,8 @@ import { WebSocketServer } from 'ws';
 import { addClient, removeClient, clientCount, broadcast, sendTo } from './broadcast.js';
 import { getBridge, answerPrompt } from './bridge.js';
 import { isClientMessage } from './protocol.js';
+import { swJs } from './sw.js';
+import { publicKey, addSubscription, getSubscriptions, logPush } from './push.js';
 export function getLocalIPs(nets = networkInterfaces()) {
     // Prefer Tailscale when available.
     let tailscale;
@@ -68,6 +70,34 @@ export async function startServer(onMessage, getHtml, getHistory) {
             res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
             res.end(body);
         }
+        else if (req.method === 'GET' && req.url === '/sw.js') {
+            res.writeHead(200, { 'Content-Type': 'text/javascript; charset=utf-8' });
+            res.end(swJs());
+        }
+        else if (req.method === 'GET' && req.url === '/push-key') {
+            res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+            res.end(publicKey());
+        }
+        else if (req.method === 'POST' && req.url === '/subscribe') {
+            const chunks = [];
+            req.on('data', c => chunks.push(c));
+            req.on('end', () => {
+                try {
+                    const sub = JSON.parse(Buffer.concat(chunks).toString());
+                    if (!sub || typeof sub.endpoint !== 'string')
+                        throw new Error('no endpoint');
+                    addSubscription(sub);
+                    logPush(`subscribe ${new URL(sub.endpoint).host} (total ${getSubscriptions().length})`);
+                    res.writeHead(201);
+                    res.end('ok');
+                }
+                catch {
+                    logPush('subscribe REJECTED (malformed body)');
+                    res.writeHead(400);
+                    res.end('bad subscription');
+                }
+            });
+        }
         else {
             res.writeHead(404);
             res.end('Not found');
@@ -95,6 +125,9 @@ export async function startServer(onMessage, getHtml, getHistory) {
         }
         if (bridge.activePrompt)
             sendTo(ws, bridge.activePrompt);
+        if (bridge.lastContextUsage) {
+            sendTo(ws, { type: 'context', contextUsage: bridge.lastContextUsage });
+        }
         broadcast({ type: 'client_count', count: clientCount() });
         ws.on('message', data => {
             let msg;

package/dist/remote/sw.d.ts

@@ -0,0 +1,8 @@
+/** Service worker source served at /sw.js. It must be a real same-origin URL
+ *  (a SW cannot be registered from a data: URL), and serving it at the root path
+ *  gives it root scope so it controls the whole app.
+ *
+ *  iOS home-screen PWAs deliver notifications ONLY through a service worker's
+ *  push event — the in-page `new Notification()` constructor is unavailable — so
+ *  this is the only path that reaches a backgrounded iPhone. */
+export declare function swJs(): string;

package/dist/remote/sw.js

@@ -0,0 +1,40 @@
+/** Service worker source served at /sw.js. It must be a real same-origin URL
+ *  (a SW cannot be registered from a data: URL), and serving it at the root path
+ *  gives it root scope so it controls the whole app.
+ *
+ *  iOS home-screen PWAs deliver notifications ONLY through a service worker's
+ *  push event — the in-page `new Notification()` constructor is unavailable — so
+ *  this is the only path that reaches a backgrounded iPhone. */
+export function swJs() {
+    return `self.addEventListener('install', function () { self.skipWaiting(); });
+self.addEventListener('activate', function (e) { e.waitUntil(self.clients.claim()); });
+
+self.addEventListener('push', function (event) {
+  var data = {};
+  try { data = event.data ? event.data.json() : {}; } catch (e) { data = {}; }
+  var title = data.title || 'pi-task remote';
+  var options = { body: data.body || '', tag: data.tag, renotify: !!data.tag };
+  event.waitUntil(
+    self.clients.matchAll({ type: 'window', includeUncontrolled: true }).then(function (cs) {
+      // Skip the banner if a window is already focused — the in-page UI shows it.
+      for (var i = 0; i < cs.length; i++) {
+        if (cs[i].visibilityState === 'visible' && cs[i].focused) return;
+      }
+      return self.registration.showNotification(title, options);
+    })
+  );
+});
+
+self.addEventListener('notificationclick', function (event) {
+  event.notification.close();
+  event.waitUntil(
+    self.clients.matchAll({ type: 'window', includeUncontrolled: true }).then(function (cs) {
+      for (var i = 0; i < cs.length; i++) {
+        if ('focus' in cs[i]) return cs[i].focus();
+      }
+      if (self.clients.openWindow) return self.clients.openWindow('/');
+    })
+  );
+});
+`;
+}

package/dist/remote/tailscale.d.ts

@@ -0,0 +1,45 @@
+/** Injectable command runner so serve orchestration is unit-testable without a real CLI. */
+export interface Run {
+    (cmd: string, args: string[]): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+}
+export type ServeResult = {
+    state: 'served';
+    url: string;
+} | {
+    state: 'foreign-conflict';
+    host: string;
+} | {
+    state: 'certs-disabled';
+    host: string;
+} | {
+    state: 'unavailable';
+};
+export interface RemoteUrlPlan {
+    /** URL to encode in the QR and announce; the https one when serve is live. */
+    primaryUrl: string;
+    /** Labeled URL lines to add to the address list (e.g. the HTTPS URL when served). */
+    urlLines: {
+        label: string;
+        url: string;
+    }[];
+    /** Extra lines to print under the URLs (empty when nothing to suggest). */
+    hintLines: string[];
+}
+/** The "/" proxy target of the first :443 Web handler in `tailscale serve status --json`,
+ *  or undefined when there is no such handler / the output isn't valid serve JSON
+ *  (e.g. the literal "No serve config"). */
+export declare function serve443Target(json: string): string | undefined;
+/** Ensure Tailscale serves https://<host> → http://127.0.0.1:<port>. Mutates only
+ *  when needed and never touches a serve config we didn't create. Best-effort:
+ *  returns a non-served state rather than throwing. */
+export declare function ensureTailscaleServe(port: number, run?: Run): Promise<ServeResult>;
+/** Tear down the :443 serve handler ONLY if it currently points at our port.
+ *  Best-effort; callers should additionally `.catch()` since it may run during
+ *  shutdown. */
+export declare function teardownTailscaleServe(port: number, run?: Run): Promise<void>;
+/** Pure: pick the primary URL and any hint lines from a serve result. */
+export declare function planRemoteUrls(httpPrimary: string, result: ServeResult): RemoteUrlPlan;

package/dist/remote/tailscale.js

@@ -0,0 +1,108 @@
+import { execFile } from 'node:child_process';
+const defaultRun = (cmd, args) => new Promise(resolve => {
+    execFile(cmd, args, { timeout: 5000 }, (err, stdout, stderr) => {
+        const exitCode = err && typeof err.code === 'number' ?
+            err.code
+            : err ? 1
+                : 0;
+        resolve({ stdout: stdout ?? '', stderr: stderr ?? '', exitCode });
+    });
+});
+/** The "/" proxy target of the first :443 Web handler in `tailscale serve status --json`,
+ *  or undefined when there is no such handler / the output isn't valid serve JSON
+ *  (e.g. the literal "No serve config"). */
+export function serve443Target(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return undefined;
+    }
+    const web = parsed
+        .Web;
+    if (!web)
+        return undefined;
+    for (const key of Object.keys(web)) {
+        if (key.endsWith(':443'))
+            return web[key]?.Handlers?.['/']?.Proxy;
+    }
+    return undefined;
+}
+/** Tailscale MagicDNS name (trailing dot stripped), or undefined if the daemon
+ *  isn't reachable / has no name. */
+async function tailscaleHost(run) {
+    const status = await run('tailscale', ['status', '--json']);
+    if (status.exitCode !== 0)
+        return undefined;
+    try {
+        const parsed = JSON.parse(status.stdout);
+        return (parsed.Self?.DNSName ?? '').replace(/\.$/, '') || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Ensure Tailscale serves https://<host> → http://127.0.0.1:<port>. Mutates only
+ *  when needed and never touches a serve config we didn't create. Best-effort:
+ *  returns a non-served state rather than throwing. */
+export async function ensureTailscaleServe(port, run = defaultRun) {
+    const host = await tailscaleHost(run);
+    if (!host)
+        return { state: 'unavailable' };
+    const ours = `http://127.0.0.1:${port}`;
+    const serve = await run('tailscale', ['serve', 'status', '--json']);
+    const target = serve443Target(serve.stdout);
+    if (target === ours)
+        return { state: 'served', url: `https://${host}` };
+    if (target !== undefined)
+        return { state: 'foreign-conflict', host };
+    // No :443 handler yet — check cert capability before trying to create one.
+    const cert = await run('tailscale', ['cert']);
+    if (/HTTPS cert support is not enabled/i.test(cert.stdout + cert.stderr)) {
+        return { state: 'certs-disabled', host };
+    }
+    const set = await run('tailscale', ['serve', '--bg', '--https=443', ours]);
+    if (set.exitCode === 0)
+        return { state: 'served', url: `https://${host}` };
+    return { state: 'certs-disabled', host };
+}
+/** Tear down the :443 serve handler ONLY if it currently points at our port.
+ *  Best-effort; callers should additionally `.catch()` since it may run during
+ *  shutdown. */
+export async function teardownTailscaleServe(port, run = defaultRun) {
+    const serve = await run('tailscale', ['serve', 'status', '--json']);
+    if (serve443Target(serve.stdout) === `http://127.0.0.1:${port}`) {
+        await run('tailscale', ['serve', '--https=443', 'off']);
+    }
+}
+/** Pure: pick the primary URL and any hint lines from a serve result. */
+export function planRemoteUrls(httpPrimary, result) {
+    switch (result.state) {
+        case 'served':
+            return {
+                primaryUrl: result.url,
+                urlLines: [{ label: 'HTTPS', url: result.url }],
+                hintLines: []
+            };
+        case 'foreign-conflict':
+            return {
+                primaryUrl: httpPrimary,
+                urlLines: [],
+                hintLines: [
+                    'HTTPS: port 443 is already used by another tailscale serve config; not touching it.',
+                    '  Free it (tailscale serve --https=443 off) to enable phone notifications.'
+                ]
+            };
+        case 'certs-disabled':
+            return {
+                primaryUrl: httpPrimary,
+                urlLines: [],
+                hintLines: [
+                    'HTTPS (for phone notifications): enable HTTPS in the Tailscale admin console, then restart the remote.'
+                ]
+            };
+        case 'unavailable':
+            return { primaryUrl: httpPrimary, urlLines: [], hintLines: [] };
+    }
+}

package/dist/remote/ui.js

@@ -38,7 +38,7 @@ export function html(wsUrl) {
       font-family: ui-monospace, monospace; height: 100dvh;
       display: flex; flex-direction: column; overflow: hidden;
       padding: env(safe-area-inset-top, 0px) env(safe-area-inset-right, 0px)
-               env(safe-area-inset-bottom, 0px) env(safe-area-inset-left, 0px);
+               0px env(safe-area-inset-left, 0px);
     }
     #context-bar { height: 4px; background: var(--surface0); flex-shrink: 0; }
     #context-bar-fill { height: 100%; background: var(--mauve); width: 0%; transition: width 0.4s ease; }
@@ -47,8 +47,27 @@ export function html(wsUrl) {
       display: flex; justify-content: space-between; align-items: center;
       font-size: 13px; flex-shrink: 0; border-bottom: 1px solid var(--surface0);
     }
-    #header .title { font-weight: bold; color: var(--mauve); letter-spacing: 0.05em; }
-    #header .status { color: var(--subtext0); font-size: 11px; }
+    #header .title { font-weight: bold; color: var(--mauve); letter-spacing: 0.05em;
+      position: relative; animation: glitch 5s steps(1) infinite; }
+    @keyframes glitch {
+      0%, 88%, 100% { text-shadow: none; transform: translate(0, 0); }
+      90% { text-shadow: -1px 0 var(--red), 1px 0 var(--teal); transform: translate(1px, -1px); }
+      92% { text-shadow: 1px 0 var(--red), -1px 0 var(--blue); transform: translate(-1px, 1px); }
+      94% { text-shadow: -1px 0 var(--blue), 1px 0 var(--red); transform: translate(1px, 0); }
+      96% { text-shadow: 1px 0 var(--teal), -1px 0 var(--red); transform: translate(-1px, 0); }
+    }
+    @media (prefers-reduced-motion: reduce) { #header .title { animation: none; } }
+    #header .status { color: var(--subtext0); font-size: 11px; display: inline-flex; align-items: center; gap: 5px; }
+    #header .cdot { color: var(--yellow); }
+    #header .cdot.up { color: var(--green); }
+    #header .cdot.down { color: var(--red); }
+    #header .hgroup { display: flex; align-items: center; gap: 10px; }
+    #bell {
+      background: none; border: none; color: var(--subtext1); cursor: pointer;
+      font-size: 15px; line-height: 1; padding: 2px; font-family: inherit;
+    }
+    #bell:hover { color: var(--text); }
+    #bell.on { color: var(--mauve); }
     #chat-log {
       flex: 1; min-width: 0; overflow-y: auto; overflow-x: hidden; padding: 16px;
       display: flex; flex-direction: column; gap: 8px;
@@ -67,17 +86,11 @@ export function html(wsUrl) {
       max-width: 100%; border: 1px solid var(--red); font-size: 12px;
     }
     .bubble.thinking {
-      display: flex; gap: 5px; align-items: center; padding: 12px 14px;
+      display: flex; gap: 5px; align-items: center; padding: 10px 14px;
     }
-    .bubble.thinking .dot {
-      width: 7px; height: 7px; border-radius: 50%; background: var(--subtext0);
-      animation: thinking-bounce 1.2s infinite ease-in-out both;
-    }
-    .bubble.thinking .dot:nth-child(1) { animation-delay: -0.24s; }
-    .bubble.thinking .dot:nth-child(2) { animation-delay: -0.12s; }
-    @keyframes thinking-bounce {
-      0%, 80%, 100% { transform: scale(0.6); opacity: 0.4; }
-      40% { transform: scale(1); opacity: 1; }
+    .bubble.thinking .spinner {
+      color: var(--mauve); font-size: 15px; line-height: 1;
+      font-family: ui-monospace, monospace;
     }
     .tool-call {
       background: var(--crust); border-radius: 6px; align-self: flex-start;
@@ -86,6 +99,7 @@ export function html(wsUrl) {
     .tool-call summary {
       padding: 6px 10px; color: var(--subtext1); cursor: pointer;
       user-select: none; list-style: none;
+      overflow-wrap: anywhere; word-break: break-word;
     }
     .tool-call summary::-webkit-details-marker { display: none; }
     .tool-call summary::before { content: "▶  "; }
@@ -116,7 +130,7 @@ export function html(wsUrl) {
     .hl-num { color: var(--blue); }
     .hl-fn  { color: var(--yellow); }
     #input-bar {
-      background: var(--mantle); padding: 10px 16px;
+      background: var(--mantle); padding: 10px 16px calc(10px + env(safe-area-inset-bottom, 0px));
       display: flex; gap: 8px; flex-shrink: 0;
       border-top: 1px solid var(--surface0);
       position: relative;
@@ -194,7 +208,9 @@ export function html(wsUrl) {
       font-size: 12px; font-weight: 500; padding: 8px 10px; }
     #prompt-card button.cancel:hover { color: var(--red); filter: none; }
     #prompt-card button.cancel.armed { background: var(--red); color: var(--crust); font-weight: 700; }
-    .toast { position: fixed; top: 12px; right: 12px; padding: 8px 12px; border-radius: 6px;
+    .toast { position: fixed; top: calc(env(safe-area-inset-top, 0px) + 12px);
+      right: calc(env(safe-area-inset-right, 0px) + 12px); max-width: calc(100vw - 24px);
+      padding: 8px 12px; border-radius: 6px; overflow-wrap: anywhere; word-break: break-word;
       background: var(--surface1); color: var(--text); z-index: 60; }
     .toast.warning { background: var(--peach); color: var(--crust); }
     .toast.error { background: var(--red); color: var(--crust); }
@@ -208,7 +224,10 @@ export function html(wsUrl) {
   <div id="context-bar"><div id="context-bar-fill"></div></div>
   <div id="header">
     <span class="title">pi-task remote</span>
-    <span class="status" id="client-status">connecting…</span>
+    <div class="hgroup">
+      <span class="status" id="client-status"><span class="cdot" id="conn-dot">&#x25CB;</span></span>
+      <button id="bell" aria-label="Toggle notifications" title="Notifications">&#x25EF;</button>
+    </div>
   </div>
   <div id="chat-log"></div>
   <div id="status-panel"></div>
@@ -242,11 +261,32 @@ export function html(wsUrl) {
     const inputEl = document.getElementById('input');
     const sendBtn = document.getElementById('send');
     const contextFill = document.getElementById('context-bar-fill');
-    const clientStatus = document.getElementById('client-status');
+    function setContextBar(usage) {
+      if (usage && usage.percent != null) contextFill.style.width = usage.percent + '%';
+    }
+    const connDot = document.getElementById('conn-dot');
+    // state: 'connecting' (○ yellow) | 'up' (● green) | 'down' (● red)
+    function setConn(state) {
+      connDot.textContent = state === 'connecting' ? '\\u25CB' : '\\u25CF';
+      connDot.className = 'cdot' + (state === 'up' ? ' up' : state === 'down' ? ' down' : '');
+    }
     const reconnectOverlay = document.getElementById('reconnect-overlay');
     const reconnectMsg = document.getElementById('reconnect-msg');
     const cmdSuggestions = document.getElementById('cmd-suggestions');
     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 = {};
+    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');
+        statusPanel.style.display = 'block';
+      } else {
+        statusPanel.style.display = 'none';
+      }
+    }
     const promptCard = document.getElementById('prompt-card');
     const promptQ = document.getElementById('prompt-q');
     const promptRec = document.getElementById('prompt-rec');
@@ -264,6 +304,7 @@ export function html(wsUrl) {
     let streamText = '';
     let autoScroll = true;
     let reconnectDelay = 1000;
+    let reconnectAnim = null;
     let ws = null;
 
     const BT = String.fromCharCode(96);
@@ -444,16 +485,28 @@ export function html(wsUrl) {
     }
 
     let thinkingEl = null;
+    let spinTimer = null;
+    let spinIdx = 0;
+    const SPIN = '\\u280B\\u2819\\u2839\\u2838\\u283C\\u2834\\u2826\\u2827\\u2807\\u280F';
     function showThinking() {
       if (!thinkingEl) {
         thinkingEl = document.createElement('div');
         thinkingEl.className = 'bubble assistant thinking';
-        thinkingEl.innerHTML = '<span class="dot"></span><span class="dot"></span><span class="dot"></span>';
+        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);
       }
       chatLog.appendChild(thinkingEl); // append (or move) to bottom
       scrollBottom();
     }
     function hideThinking() {
+      if (spinTimer) { clearInterval(spinTimer); spinTimer = null; }
       if (thinkingEl) thinkingEl.remove();
     }
 
@@ -483,6 +536,100 @@ export function html(wsUrl) {
       setTimeout(function () { t.remove(); }, 4000);
     }
 
+    const bell = document.getElementById('bell');
+    const NOTIFY_KEY = 'piRemoteNotify';
+
+    function notifyEnabled() {
+      return localStorage.getItem(NOTIFY_KEY) === '1'
+        && typeof Notification !== 'undefined'
+        && Notification.permission === 'granted';
+    }
+
+    function updateBell() {
+      // ◉ (mauve) when armed, ◯ (dim) when off/unavailable.
+      var on = notifyEnabled();
+      bell.textContent = on ? '\\u25C9' : '\\u25EF';
+      bell.classList.toggle('on', on);
+    }
+
+    // Why notifications can't be enabled here, or null if they can.
+    function notifyEnvIssue() {
+      if (typeof Notification === 'undefined') return "This browser doesn't support notifications.";
+      if (!window.isSecureContext) return 'Notifications need HTTPS. Open the Tailscale https:// URL, or open via localhost.';
+      const isIOS = /iP(hone|ad|od)/i.test(navigator.userAgent);
+      const standalone = navigator.standalone === true
+        || (window.matchMedia && window.matchMedia('(display-mode: standalone)').matches);
+      if (isIOS && !standalone) return 'On iOS: Share \\u2192 Add to Home Screen first, then enable notifications.';
+      return null;
+    }
+
+    bell.addEventListener('click', function () {
+      // Turning OFF always works regardless of environment.
+      if (localStorage.getItem(NOTIFY_KEY) === '1') {
+        localStorage.setItem(NOTIFY_KEY, '0'); updateBell(); return;
+      }
+      const issue = notifyEnvIssue();
+      if (issue) { showToast(issue, 'warning'); return; }
+      if (!('serviceWorker' in navigator) || !('PushManager' in window)) {
+        showToast('This browser doesn\\u2019t support push notifications.', 'warning'); return;
+      }
+      Notification.requestPermission().then(function (perm) {
+        if (perm !== 'granted') {
+          showToast('Notifications blocked in browser settings.', 'warning');
+          updateBell(); return;
+        }
+        subscribePush().then(function (ok) {
+          if (ok) { localStorage.setItem(NOTIFY_KEY, '1'); showToast('Notifications on.', 'info'); }
+          else { showToast('Could not register for notifications.', 'warning'); }
+          updateBell();
+        }).catch(function (e) {
+          showToast('Notification setup failed: ' + (e && e.message ? e.message : e), 'warning');
+          updateBell();
+        });
+      });
+    });
+
+    // VAPID public key (base64url) -> Uint8Array for applicationServerKey.
+    function urlB64ToUint8Array(base64) {
+      const pad = '='.repeat((4 - base64.length % 4) % 4);
+      const b64 = (base64 + pad).replace(/-/g, '+').replace(/_/g, '/');
+      const raw = atob(b64);
+      const arr = new Uint8Array(raw.length);
+      for (let i = 0; i < raw.length; i++) arr[i] = raw.charCodeAt(i);
+      return arr;
+    }
+
+    // Register the service worker, subscribe via the Push API, and hand the
+    // subscription to the server. The server (not the page) sends notifications,
+    // so they arrive even when this PWA is backgrounded/suspended on iOS.
+    function subscribePush() {
+      return navigator.serviceWorker.register('/sw.js')
+        .then(function () { return navigator.serviceWorker.ready; })
+        .then(function (reg) {
+          return fetch('/push-key').then(function (r) { return r.text(); }).then(function (key) {
+            return reg.pushManager.getSubscription().then(function (existing) {
+              return existing || reg.pushManager.subscribe({
+                userVisibleOnly: true,
+                applicationServerKey: urlB64ToUint8Array(key.trim())
+              });
+            });
+          });
+        })
+        .then(function (subscription) {
+          return fetch('/subscribe', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(subscription)
+          }).then(function (res) { return res.ok; });
+        });
+    }
+
+    updateBell();
+    // Self-heal: if notifications were enabled before, re-register the
+    // subscription on load (the server keeps subscriptions in memory and may
+    // have restarted, and browsers can rotate the subscription).
+    if (notifyEnabled()) { subscribePush().catch(function () {}); }
+
     function answer(value) {
       if (activePromptId === null) return;
       ws.send(JSON.stringify({ type: 'prompt_answer', id: activePromptId, value: value }));
@@ -670,12 +817,14 @@ export function html(wsUrl) {
           currentBubble = null;
           streamText = '';
           setEnabled(true);
-          if (msg.contextUsage && msg.contextUsage.percent != null) {
-            contextFill.style.width = msg.contextUsage.percent + '%';
-          }
+          setContextBar(msg.contextUsage);
+          break;
+        case 'context':
+          // Seeds the bar for a client that joined mid-session.
+          setContextBar(msg.contextUsage);
           break;
         case 'client_count':
-          clientStatus.textContent = msg.count + ' client' + (msg.count === 1 ? '' : 's') + ' connected';
+          setConn('up');
           break;
         case 'prompt':
           showPrompt(msg);
@@ -684,12 +833,9 @@ export function html(wsUrl) {
           if (activePromptId === msg.id) closePrompt();
           break;
         case 'widget':
-          if (msg.lines && msg.lines.length) {
-            statusPanel.textContent = msg.lines.join('\\n');
-            statusPanel.style.display = 'block';
-          } else {
-            statusPanel.style.display = 'none';
-          }
+          if (msg.lines && msg.lines.length) widgets[msg.key] = msg.lines;
+          else delete widgets[msg.key];
+          renderWidgets();
           break;
         case 'notify':
           showToast(msg.message, msg.level);
@@ -698,6 +844,16 @@ export function html(wsUrl) {
           viewerBody.textContent = msg.text;
           viewer.style.display = 'block';
           break;
+        case 'reset':
+          // A new session started — wipe the previous session's transcript.
+          chatLog.innerHTML = '';
+          hideThinking();
+          currentBubble = null; streamText = '';
+          closePrompt();
+          for (const k in widgets) delete widgets[k];
+          renderWidgets();
+          contextFill.style.width = '0%';
+          break;
       }
     }
 
@@ -737,9 +893,10 @@ export function html(wsUrl) {
     function connect() {
       ws = new WebSocket(WS_URL);
       ws.addEventListener('open', () => {
+        if (reconnectAnim) { clearInterval(reconnectAnim); reconnectAnim = null; }
         reconnectOverlay.classList.remove('visible');
         reconnectDelay = 1000;
-        clientStatus.textContent = 'connected';
+        setConn('up');
         setEnabled(true);
       });
       ws.addEventListener('message', (e) => {
@@ -747,8 +904,21 @@ export function html(wsUrl) {
       });
       ws.addEventListener('close', () => {
         setEnabled(false);
+        setConn('down');
         reconnectOverlay.classList.add('visible');
-        reconnectMsg.textContent = 'reconnecting in ' + (reconnectDelay / 1000) + 's…';
+        // Animate the same braille spinner used elsewhere, with a live countdown.
+        const until = Date.now() + reconnectDelay;
+        let frame = 0;
+        const paint = () => {
+          const left = Math.max(0, Math.ceil((until - Date.now()) / 1000));
+          const glyph = SPIN[frame++ % SPIN.length];
+          reconnectMsg.textContent = left > 0
+            ? glyph + '  connection lost — retrying in ' + left + 's'
+            : glyph + '  reconnecting…';
+        };
+        if (reconnectAnim) clearInterval(reconnectAnim);
+        paint();
+        reconnectAnim = setInterval(paint, 90);
         setTimeout(() => { reconnectDelay = Math.min(reconnectDelay * 2, 30000); connect(); }, reconnectDelay);
       });
     }

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

@@ -19,7 +19,7 @@ export async function runWorker(input) {
     const result = await runChildDefault(invocation, input.cwd, input.signal, {
         mode: 'json-events',
         onFirstByte: () => (tFirstByte = Date.now()),
-        onToolCall: (call) => loopDetector.record(call)
+        onToolCall: call => loopDetector.record(call)
     }, input.spawn);
     const tEnd = Date.now();
     const waitMs = tFirstByte === null ? tEnd - tStart : tFirstByte - tStart;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.5.0",
+    "version": "0.7.0",
     "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",
@@ -27,19 +27,21 @@
         "jsdom": "^29.1.1",
         "qrcode": "^1.5.4",
         "turndown": "^7.2.4",
+        "web-push": "^3.6.7",
         "ws": "^8.18.0"
     },
     "devDependencies": {
-        "@earendil-works/pi-coding-agent": "0.78.1",
         "@earendil-works/pi-agent-core": "0.78.1",
+        "@earendil-works/pi-coding-agent": "0.78.1",
         "@earendil-works/pi-tui": "0.78.1",
-        "@types/qrcode": "^1.5.5",
-        "@types/ws": "^8.5.14",
         "@eslint/js": "10.0.1",
         "@sinclair/typebox": "0.34.49",
         "@types/bun": "1.3.12",
         "@types/jsdom": "^28.0.3",
+        "@types/qrcode": "^1.5.5",
         "@types/turndown": "^5.0.6",
+        "@types/web-push": "^3.6.4",
+        "@types/ws": "^8.5.14",
         "eslint": "10.2.1",
         "globals": "17.5.0",
         "prettier": "3.8.3",