@mjasnikovs/pi-task 0.38.29 → 0.38.30

package/dist/remote/push.js

@@ -2,23 +2,22 @@ import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import os from 'node:os';
 import path from 'node:path';
 import webpush from 'web-push';
-/** Resolve the XDG data-home base. Under data-home (not cache) so the files it
- *  roots survive cache clears. Follows the repo's XDG convention; see
- *  workers/docs-core.ts. */
+/** Resolve the XDG data-home base. Same env-or-homedir shape the docs cache uses
+ *  (workers/docs-core.ts), but rooted at data-home rather than cache-home: what
+ *  lives under here is not reconstructible by re-fetching. */
 function dataHome() {
     return process.env.XDG_DATA_HOME?.trim() || path.join(os.homedir(), '.local', 'share');
 }
-/** Where the VAPID keypair is persisted — losing these keys invalidates every
- *  existing browser subscription. */
+/** Where the VAPID keypair is persisted. The browser subscribes with this
+ *  public key as its applicationServerKey (see ui-script.ts), so the pair has to
+ *  outlive the process that created it. */
 export function vapidStorePath() {
     return path.join(dataHome(), 'pi-task', 'vapid.json');
 }
 /** Where browser push subscriptions are mirrored to disk (next to vapid.json).
- *  Without this, a server restart — e.g. after a rebuild — silently drops every
- *  device: the in-memory store is empty, and a backgrounded/suspended PWA won't
- *  re-register until the user next foregrounds it, which is exactly when the push
- *  is no longer useful. The in-memory store stays authoritative within a process;
- *  this is its durable mirror. */
+ *  Without this a server restart starts with an empty store and reaches nobody
+ *  until every device happens to re-register. The in-memory store stays
+ *  authoritative within a process; this is its durable mirror. */
 export function subscriptionsStorePath() {
     return path.join(dataHome(), 'pi-task', 'subscriptions.json');
 }
@@ -27,16 +26,17 @@ export function subscriptionsStorePath() {
 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`). */
+/** VAPID JWT `sub` claim. web-push's validateSubject requires a parseable URL
+ *  whose protocol is `https:` or `mailto:` and throws otherwise, 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. */
+ *  set, so it stays silent (and test-safe) by default. deliver() swallows every
+ *  send failure, so this is the only way to see the push service's status
+ *  codes. */
 export function logPush(line) {
     if (!process.env.PI_REMOTE_PUSH_DEBUG)
         return;
@@ -49,8 +49,8 @@ export function logPush(line) {
         // 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). */
+/** Short host label for an endpoint, for readable logs — a push endpoint's path
+ *  carries the device's own subscription id and does not belong in a log. */
 function endpointHost(sub) {
     try {
         return new URL(sub.endpoint ?? '').host;
@@ -82,10 +82,9 @@ export function loadOrCreateVapidKeys(file = vapidStorePath()) {
     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),
-// and mirrored to disk (subscriptionsStorePath) so it also survives a full
-// process restart. A re-subscribe on page load can't be relied on for that: the
-// devices that need server push are backgrounded/suspended and won't reload.
+// survives the module being re-evaluated (same pattern as broadcast.ts), and
+// mirrored to disk (subscriptionsStorePath) so it also survives a full process
+// restart — a re-subscribe on page load only helps devices whose page is open.
 const g = globalThis;
 const freshStore = !g.__piRemoteSubs;
 if (!g.__piRemoteSubs)
@@ -144,8 +143,9 @@ export function clearSubscriptions() {
     subs.clear();
     saveSubscriptions();
 }
-/** True when the push service says the subscription is permanently gone and
- *  should be dropped (404 Not Found, 410 Gone). */
+/** True when the push service's status says the subscription is permanently
+ *  gone (404, 410) rather than transiently failing. web-push rejects with the
+ *  `statusCode` on any non-2xx, which is what this reads. */
 function isGone(err) {
     const code = err?.statusCode;
     return code === 404 || code === 410;
@@ -182,9 +182,9 @@ function ensureConfigured() {
 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. */
+/** Send a notification to all subscribed devices. Best-effort, and the route is
+ *  server→push-service→device, so it does not need the page to be open the way
+ *  the in-page Notification API does. */
 export async function pushNotify(title, body, tag) {
     if (process.env.NODE_ENV === 'test')
         return;

package/dist/remote/register.d.ts

@@ -1,8 +1,8 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 /**
- * Where a plain (non-slash) browser line goes. Exported so the decision is
- * tested as SHIPPED rather than as a copy — the three branches are the whole of
- * issue #8, and the middle one is the regression.
+ * Where a plain (non-slash) browser line goes. Exported so
+ * test/remote/mid-run-routing.test.ts drives the shipped decision rather than a
+ * copy of it — these three branches are the whole of issue #8.
  */
 export declare function routePlainLine(plain: string, send: (text: string, opts?: {
     deliverAs: 'steer' | 'followUp';

package/dist/remote/register.js

@@ -12,22 +12,17 @@ if (!_g.__piRemote)
     _g.__piRemote = { server: null, send: null, serveResult: null };
 const S = _g.__piRemote;
 /**
- * Where a plain (non-slash) browser line goes. Exported so the decision is
- * tested as SHIPPED rather than as a copy — the three branches are the whole of
- * issue #8, and the middle one is the regression.
+ * Where a plain (non-slash) browser line goes. Exported so
+ * test/remote/mid-run-routing.test.ts drives the shipped decision rather than a
+ * copy of it — these three branches are the whole of issue #8.
  */
 export function routePlainLine(plain, send) {
     addUserTurn(plain);
     // Read the run flag from SessionState, which is the only thing that owns it.
-    // There used to be a mirror of it here (remote/state.ts: a module-level `let`
-    // plus a getter/setter, set alongside agentStart/agentEnd in events.ts). Two
-    // sources of truth for one boolean, and they disagreed twice over: SessionState
-    // also clears agentRunning in addError and reset, neither of which touched the
-    // mirror — so an errored turn or a /new left this branch steering into a turn
-    // SessionState already considered finished. And the mirror was a plain module
-    // `let` while every other piece of remote state deliberately lives on
-    // globalThis to survive jiti re-evaluation, so it silently reset on session
-    // switch. Deleting it removed complexity rather than moving it.
+    // Three functions clear it — agentEnd, addError and reset — so anything
+    // mirroring the flag here would have to track an errored turn and a /new as
+    // well as a finished one, and would steer into a turn SessionState already
+    // considers over whenever it missed one.
     if (getState().agentRunning) {
         // A live turn: steer it (inject into the current generation) so the
         // nudge lands immediately.
@@ -35,9 +30,9 @@ export function routePlainLine(plain, send) {
     }
     else if (isRunActive()) {
         // Idle, but a task run owns the session — which is most of a run, since
-        // the spec phases and every gate are child processes. Sending here opens
-        // a SECOND turn beside the run; that is what killed a live run on pi
-        // 0.82.1. Hold it for the next task turn instead.
+        // the spec phases and every gate are child processes. pi documents
+        // sendUserMessage as "Always triggers a turn", so sending here opens a
+        // SECOND turn beside the run. Hold it for the next task turn instead.
         holdInput(plain);
     }
     else {
@@ -65,7 +60,9 @@ export function registerRemote(pi) {
         }, wsUrl => html(wsUrl), interruptAgent, clearHeldInput);
         // 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' }));
+        S.serveResult = await ensureTailscaleServe(S.server.port).catch(() => ({
+            state: 'unavailable'
+        }));
         return S.server;
     }
     pi.on('session_start', (_event, ctx) => {
@@ -119,9 +116,10 @@ export function registerRemote(pi) {
         });
         publishNotify('Compacting context…', 'info');
     });
-    // Bridge-registered (not pi.registerCommand) so `/remote stop` also works when
-    // typed in the browser — the web UI advertises it, and while a /task-auto run
-    // holds the host command loop the browser is the only live input surface.
+    // registerBridgeCommand, not registerRemoteOnlyCommand: this one needs to
+    // exist in the terminal AND on the bridge, so `/remote stop` also works typed
+    // in the browser — the web UI advertises it, and while a /task-auto run holds
+    // the host command loop the browser is the only live input surface.
     registerBridgeCommand(pi, 'remote', {
         description: 'Show the remote QR code & URLs.',
         handler: async (args, ctx) => {

package/dist/remote/server.d.ts

@@ -25,8 +25,9 @@ type MessageCallback = (text: string) => void;
 export declare function getLocalIPs(nets?: NodeJS.Dict<import("node:os").NetworkInterfaceInfo[]>): LocalIPs;
 /** Build the labeled URL lines shown under the QR code. Both Tailscale and LAN
  *  when present; a single unlabeled primary URL when neither resolves. The
- *  Tailscale line uses the MagicDNS host when known (resolves to the same node,
- *  but is what SSH and webpush certs need), falling back to the raw IP. */
+ *  Tailscale line uses the MagicDNS host when known — it resolves to the same
+ *  node as the raw IP, but it is the name `tailscale cert` and the https URL in
+ *  tailscale.ts are issued for — falling back to the raw IP. */
 export declare function formatAddresses(ips: LocalIPs, port: number, tsHost?: string): AddressLine[];
 /** Bind the REAL `server` to the first free port at or above `start`, trying up
  *  to `max` consecutive ports. On EADDRINUSE we bump the port and re-listen; any
@@ -35,12 +36,12 @@ export declare function formatAddresses(ips: LocalIPs, port: number, tsHost?: st
  *
  *  Binding the real server directly (rather than probing a throwaway socket with
  *  createServer()/listen()/close() first, then binding the real one) removes a
- *  TOCTOU race: between "probe says port free" and "real listen", the port can be
- *  taken by someone else, and on Windows/Bun the PROBE socket's own port isn't
- *  fully released before the real listen runs — so the real bind hits EADDRINUSE
- *  on the very port that just tested free, and (with no 'error' listener on the
- *  real server) escapes as an uncaughtException that crashes pi (issue #7).
- *  Retrying the real bind has no probe and no window. */
+ *  TOCTOU race: between "probe says port free" and "real listen" the port can be
+ *  taken — including by the probe's own socket, if the runtime has not released
+ *  it yet — so the real bind hits EADDRINUSE on the very port that just tested
+ *  free. With no 'error' listener on the real server that escapes as an
+ *  uncaughtException and takes pi down; that is issue #7. Retrying the real bind
+ *  has no probe and no window. */
 export declare function listenWithRetry(server: import('node:http').Server, start: number, max: number): Promise<number>;
 export declare function startServer(onMessage: MessageCallback, getHtml: (wsUrl: string) => string, onInterrupt?: () => void, onClearHeld?: () => void): Promise<ServerHandle>;
 export {};

package/dist/remote/server.js

@@ -34,8 +34,9 @@ export function getLocalIPs(nets = networkInterfaces()) {
 }
 /** Build the labeled URL lines shown under the QR code. Both Tailscale and LAN
  *  when present; a single unlabeled primary URL when neither resolves. The
- *  Tailscale line uses the MagicDNS host when known (resolves to the same node,
- *  but is what SSH and webpush certs need), falling back to the raw IP. */
+ *  Tailscale line uses the MagicDNS host when known — it resolves to the same
+ *  node as the raw IP, but it is the name `tailscale cert` and the https URL in
+ *  tailscale.ts are issued for — falling back to the raw IP. */
 export function formatAddresses(ips, port, tsHost) {
     const out = [];
     if (tsHost)
@@ -55,12 +56,12 @@ export function formatAddresses(ips, port, tsHost) {
  *
  *  Binding the real server directly (rather than probing a throwaway socket with
  *  createServer()/listen()/close() first, then binding the real one) removes a
- *  TOCTOU race: between "probe says port free" and "real listen", the port can be
- *  taken by someone else, and on Windows/Bun the PROBE socket's own port isn't
- *  fully released before the real listen runs — so the real bind hits EADDRINUSE
- *  on the very port that just tested free, and (with no 'error' listener on the
- *  real server) escapes as an uncaughtException that crashes pi (issue #7).
- *  Retrying the real bind has no probe and no window. */
+ *  TOCTOU race: between "probe says port free" and "real listen" the port can be
+ *  taken — including by the probe's own socket, if the runtime has not released
+ *  it yet — so the real bind hits EADDRINUSE on the very port that just tested
+ *  free. With no 'error' listener on the real server that escapes as an
+ *  uncaughtException and takes pi down; that is issue #7. Retrying the real bind
+ *  has no probe and no window. */
 export function listenWithRetry(server, start, max) {
     return new Promise((resolve, reject) => {
         let port = start;
@@ -145,12 +146,12 @@ export async function startServer(onMessage, getHtml, onInterrupt, onClearHeld)
     // keep-alive / WebSocket connections. Without this, httpServer.close() only
     // stops accepting new connections and waits for existing ones to drain — an
     // open browser tab never drains, so the listening server and its sockets
-    // stay as active event-loop handles forever. In headless print mode the host
-    // exits by natural event-loop drain (it sets process.exitCode and returns,
-    // with no process.exit()), so these lingering handles keep the pi process
-    // alive indefinitely — which blocks `docker stop` / OS shutdown until the
-    // SIGKILL grace timeout fires. A/B-proven: terminating clients + destroying
-    // sockets here makes the loop drain in ~2ms instead of never.
+    // stay as active event-loop handles forever. In print mode pi exits by
+    // natural event-loop drain: main.js sets `process.exitCode` and returns with
+    // no process.exit(), unlike the package-command path right above it which
+    // calls process.exit precisely so a bad extension cannot keep a one-shot
+    // command alive. Terminating clients and destroying sockets here is what
+    // lets the loop drain at all.
     const sockets = new Set();
     httpServer.on('connection', s => {
         sockets.add(s);

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

@@ -2,10 +2,11 @@ import { HistoryBuffer } from './history.js';
 import type { Turn, Part } from './history.js';
 import type { ContextUsage, PromptMessage, WidgetData } from './protocol.js';
 export interface LiveTurn {
-    /** Ordered assistant content (text segments + tool calls) for this run. */
+    /** Ordered assistant content — text, thinking and tool parts — 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). */
+    /** Is the trailing text part still accumulating deltas? Closed by text_end, a
+     *  thinking delta and a tool start, so the next text begins a fresh segment
+     *  (separate bubble). */
     textOpen: boolean;
 }
 export interface SnapshotMessage {
@@ -29,7 +30,7 @@ interface SessionState {
     taskWidgetData: WidgetData | null;
     prompt: PromptMessage | null;
     context: ContextUsage | null;
-    /** Human-readable active model name (e.g. "Qwen3.6 27B"), for the header chip. */
+    /** Human-readable active model name, as pi reports it, for the header chip. */
     model: string | null;
     /** Lines typed while a task run owned the session, waiting for the next task
      *  turn to steer. Mirrors src/task/mid-run-input.ts so the browser can show

package/dist/remote/session-state.js

@@ -3,12 +3,15 @@
 // 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.
+// the snapshot and the live deltas read/write the same object, they cannot
+// disagree.
 //
-// State lives on globalThis so it survives jiti module re-evaluation on session
-// switches, the same pattern broadcast.ts and bridge.ts use.
+// updateTool is the one mutator that only broadcasts: a partial tool result is
+// transient, endTool carries the real one, and no browser module listens for
+// `tool_update` at all.
+//
+// State lives on globalThis so it survives the module being re-evaluated, the
+// same pattern broadcast.ts and bridge.ts use.
 import { broadcast as wsBroadcast } from './broadcast.js';
 import { HistoryBuffer } from './history.js';
 const g = globalThis;

package/dist/remote/sw.d.ts

@@ -1,8 +1,9 @@
-/** 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.
+/** Service worker source served at /sw.js (see server.ts's request handler). It
+ *  must be a real same-origin URL — registering from a `data:` URL is refused
+ *  with "The URL protocol of the script is not supported" — and serving it at
+ *  the root path is what gives it root scope: a worker served at `/sw.js`
+ *  registers with scope `/`, one at `/deep/sw.js` with scope `/deep/`.
  *
- *  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. */
+ *  Notifications go through this worker's push event rather than an in-page
+ *  `new Notification()` so they reach a device whose page is not open. */
 export declare function swJs(): string;

package/dist/remote/sw.js

@@ -1,10 +1,11 @@
-/** 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.
+/** Service worker source served at /sw.js (see server.ts's request handler). It
+ *  must be a real same-origin URL — registering from a `data:` URL is refused
+ *  with "The URL protocol of the script is not supported" — and serving it at
+ *  the root path is what gives it root scope: a worker served at `/sw.js`
+ *  registers with scope `/`, one at `/deep/sw.js` with scope `/deep/`.
  *
- *  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. */
+ *  Notifications go through this worker's push event rather than an in-page
+ *  `new Notification()` so they reach a device whose page is not open. */
 export function swJs() {
     return `self.addEventListener('install', function () { self.skipWaiting(); });
 self.addEventListener('activate', function (e) { e.waitUntil(self.clients.claim()); });

package/dist/remote/tailscale.d.ts

@@ -19,7 +19,8 @@ export type ServeResult = {
 } | {
     state: 'unavailable';
 };
-/** The MagicDNS host of a serve result, or undefined when the daemon had no name. */
+/** The MagicDNS host of a serve result, or undefined for `unavailable` — the one
+ *  state that carries no host, because the daemon was unreachable or nameless. */
 export declare function hostFromResult(result: ServeResult): string | undefined;
 export interface RemoteUrlPlan {
     /** URL to encode in the QR and announce; the https one when serve is live. */
@@ -47,5 +48,6 @@ export declare function teardownTailscaleServe(port: number, run?: Run): Promise
 /** Pure: pick the primary URL (what the QR encodes) and any hint lines from a
  *  serve result. Prefers the MagicDNS host over the raw IP whenever it's known —
  *  the https URL when serve is live, else http://<host>:<port> — so the QR and
- *  the announced URL carry the tailnet name (needed for SSH and webpush certs). */
+ *  the announced URL carry the tailnet name, which is what `tailscale cert` and
+ *  the `--https=443` handler above are issued for. */
 export declare function planRemoteUrls(httpPrimary: string, result: ServeResult, port: number): RemoteUrlPlan;

package/dist/remote/tailscale.js

@@ -1,5 +1,6 @@
 import { execFile } from 'node:child_process';
-/** The MagicDNS host of a serve result, or undefined when the daemon had no name. */
+/** The MagicDNS host of a serve result, or undefined for `unavailable` — the one
+ *  state that carries no host, because the daemon was unreachable or nameless. */
 export function hostFromResult(result) {
     return result.state === 'unavailable' ? undefined : result.host;
 }
@@ -83,7 +84,8 @@ export async function teardownTailscaleServe(port, run = defaultRun) {
 /** Pure: pick the primary URL (what the QR encodes) and any hint lines from a
  *  serve result. Prefers the MagicDNS host over the raw IP whenever it's known —
  *  the https URL when serve is live, else http://<host>:<port> — so the QR and
- *  the announced URL carry the tailnet name (needed for SSH and webpush certs). */
+ *  the announced URL carry the tailnet name, which is what `tailscale cert` and
+ *  the `--https=443` handler above are issued for. */
 export function planRemoteUrls(httpPrimary, result, port) {
     switch (result.state) {
         case 'served':

package/dist/remote/ui-highlight.js

@@ -1,10 +1,11 @@
 // Generalized single-pass syntax highlighter, shipped as a JS string and
-// concatenated into the page by ui.ts. It grew out of the client's original
-// JS-only tokenizer: the string/comment/number/identifier logic is now shared and
-// parameterized by a per-language config (keyword set + comment markers + string
-// flavors). Unknown languages fall back to escaped plain text (unchanged).
+// concatenated into the page by ui.ts. One string/comment/number/identifier
+// tokenizer, parameterized by a per-language config in HL_LANGS (keyword set +
+// comment markers + string flavors). A language with no entry there falls back
+// to escaped plain text with no spans at all.
 //
-// Depends on escHtml (ui-render.ts) — both land in the same <script>.
+// Depends on escHtml (ui-render.ts) — ui.ts emits renderModule() immediately
+// before highlightModule(), inside one <script>.
 /** Emitted client JS (top-level function declarations + language tables). */
 export function highlightModule() {
     return `    var HL_JS_KW = new Set(('break case catch class const continue debugger default delete do else export '

package/dist/remote/ui-render.js

@@ -19,10 +19,10 @@ export function renderModule() {
     }
 
     // Split text into ordered {type:'text'|'code', ...} blocks by scanning lines
-    // for a fenced code marker at line start. This replaces a RegExp that was built
-    // from a string where '[\\\\s\\\\S]' collapsed to '[sS]', so it matched nothing
-    // and every code block rendered as raw text. A line scanner also tolerates an
-    // unclosed trailing fence, which the regex never could.
+    // for a fenced code marker at line START — an indented fence is ordinary
+    // text. Scanning lines rather than matching one regex over the whole string
+    // is also what tolerates an unclosed trailing fence: everything after it
+    // becomes the code block.
     function parseBlocks(text) {
       var FENCE = String.fromCharCode(96, 96, 96);
       var lines = String(text == null ? '' : text).split('\\n');

package/dist/remote/ui-script.js

@@ -21,7 +21,8 @@ export function clientScript(wsUrl) {
       if (usage && usage.percent != null) contextFill.style.width = usage.percent + '%';
       setStatusChip(usage);
     }
-    // Compact token count for the header chip (mirrors formatContextTokens).
+    // Compact token count for the header chip. Matches the terminal's
+    // formatContextTokens up to 10M; above that this one keeps a decimal.
     function fmtTokens(n) {
       if (n == null) return '';
       if (n < 1000) return String(n);
@@ -58,11 +59,8 @@ export function clientScript(wsUrl) {
     // Last ~20 toasts, newest first, for the bell dropdown history.
     let notifHistory = [];
     let modelName = '';
-    // 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.
-    // 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.)
+    // Single authoritative task-widget slot — two variables, no keying. The
+    // snapshot and the live 'widget' delta both set them; null hides the panel.
     let taskWidgetLines = null;
     let taskWidgetData = null;
     function renderWidgets() {
@@ -156,10 +154,10 @@ export function clientScript(wsUrl) {
       { name: '/compact',          desc: 'Compact context to save tokens' },
       { name: '/remote stop',      desc: 'Stop the remote server' },
     ];
-    // Every entry above must be dispatchable from the browser — /clear, /help and
-    // /fast used to sit here and were not (they are not pi commands at all), so
-    // picking one only ever produced "Unknown command". register.test.ts asserts
-    // this list stays a subset of what the bridge can actually run.
+    // Every entry above must be dispatchable from the browser, or picking it
+    // only ever toasts "Unknown command: /x". register.test.ts parses this array
+    // out of clientScript() and asserts each name is in the bridge's command map
+    // (/new excepted, which register.ts dispatches itself).
     let cmdActive = [];
     let cmdIndex = -1;
 
@@ -492,11 +490,13 @@ export function clientScript(wsUrl) {
       thinkingText = '';
     }
 
-    // Pull the human-readable text out of a tool result. Many tools (Read, Bash,
-    // MCP tools) return Anthropic content-block shapes — { content: [{type:'text',
-    // text:'...'}] } or a bare array of such blocks — which JSON.stringify would
-    // render as escaped, unreadable JSON. Extract the text blocks and join them;
-    // return null when there's nothing text-shaped so the caller falls back to JSON.
+    // Pull the human-readable text out of a tool result. pi types AgentToolResult
+    // with content: (TextContent | ImageContent)[], and TextContent is
+    // {type:'text', text}, so a result usually arrives as { content: [...] } — or,
+    // since the event field is typed \`any\`, as a bare array of those blocks.
+    // JSON.stringify would render either as escaped, unreadable JSON. Extract the
+    // text blocks and join them; return null when there is nothing text-shaped so
+    // the caller falls back to JSON.
     function contentBlocksText(result) {
       const blocks = Array.isArray(result) ? result
         : (result && Array.isArray(result.content)) ? result.content
@@ -567,8 +567,8 @@ export function clientScript(wsUrl) {
       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
+    // Render one committed transcript turn. Assistant turns are an ordered list
+    // of parts — text, thinking and tool — 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); addTurnTime(t.ts, 'assistant'); return; }
@@ -745,8 +745,8 @@ export function clientScript(wsUrl) {
     }
 
     // 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.
+    // subscription to the server. The server, not the page, sends the
+    // notification, so delivery does not need this page to be open.
     function subscribePush() {
       return navigator.serviceWorker.register('/sw.js')
         .then(function () { return navigator.serviceWorker.ready; })
@@ -1214,11 +1214,11 @@ export function clientScript(wsUrl) {
     window.addEventListener('online', connectNow);
     window.addEventListener('focus', connectNow);
 
-    // Pin the column to window.innerHeight (a stable px value) instead of letting
-    // it ride 100dvh, which iOS Safari interpolates DURING the rotation animation
-    // and makes the whole layout resize repeatedly ("spazzing out"). A rotation
-    // also fires several resize events and changes scrollHeight, so coalesce the
-    // updates in one rAF and re-pin to the bottom when the user was already there.
+    // Pin the column to a stable pixel height instead of leaving it on the
+    // 100dvh fallback in ui-styles.ts (height: var(--app-h, 100dvh)). A rotation
+    // fires several resize events and changes scrollHeight, so coalesce the
+    // updates in one rAF and re-pin to the bottom when the user was already
+    // there.
     let appHeightRaf = null;
     let appHeightPin = false;
     function setAppHeight() {