@mjasnikovs/pi-task 0.38.29 → 0.38.30

package/dist/config/register.d.ts

@@ -44,15 +44,8 @@ declare class BorderedBox implements Component {
  * One /task-config setting, and BOTH directions of its value.
  *
  * `format` renders the stored value for the panel; `apply` parses the chosen
- * label back into it. They are per-row because the two used to be hand-written
- * ladders — a `displayValue` arm to format, a matching `onChange` arm to parse,
- * and three different idioms for the same parse across the four enum settings.
- * Adding one enum setting meant four coordinated edits (row, format arm, parse
- * arm, sanitizer) and NONE of them failed to compile if you forgot it: a missed
- * format arm rendered `String(cfg[id])`, and a missed parse arm let the generic
- * `else` write the boolean `newValue === 'on'` into an enum field. The comment
- * that used to sit in that `else` — explaining why `debugLogs` must not fall
- * into it — was the interface saying it was too shallow.
+ * label back into it. Both live on the row so adding an enum setting is ONE
+ * edit, and a row that renders but cannot parse is impossible to write.
  *
  * With both directions on the row, `format(apply(cfg, v)) === v` is a property
  * over the whole table, and the panel and the non-TUI listing cannot disagree
@@ -64,18 +57,16 @@ export interface ConfigItem {
      * string (`reason:`, `tool:`, `ext:`) for a DISCOVERED one.
      *
      * It is `string`, not `keyof PiTaskConfig`, and that is what lets the three
-     * dynamic families BE rows instead of bypassing them. While the id was
-     * narrow, each family re-invented both directions by hand — a builder, an
-     * apply function, and an arm in a four-way prefix ladder 300 lines away —
-     * and the round-trip property `config-items.test.ts` runs over `ITEMS`
-     * covered none of them.
+     * dynamic families BE rows instead of bypassing them — so the round-trip
+     * property in `config-items.test.ts` covers them through the same row type
+     * as the fixed settings.
      */
     id: string;
     /**
-     * Which titled block of the menu this row sits under. Rows are grouped by
-     * section in {@link panelItems}, in the order the sections first appear in
-     * {@link ITEMS} — so moving a row between sections is a one-word edit and
-     * the header follows it.
+     * Which titled block of the menu this row sits under. {@link renderRows}
+     * walks {@link SECTIONS} and collects the rows claiming each key, so the
+     * block order is SECTIONS' order and moving a row between blocks is a
+     * one-word edit here.
      */
     section: Section;
     label: string;
@@ -95,12 +86,11 @@ export interface ConfigItem {
 /**
  * The titled blocks the settings menu is divided into.
  *
- * A flat list of ~30 rows — twelve settings, seven reasoning groups, one row per
- * live tool and one per installed extension — reads as a wall, and the rows that
- * belong together (a mode and the seven groups it controls; a timeout and the
- * per-tool exemptions from it) end up separated by rows that have nothing to do
- * with them. The headers are inert rows: no `values`, so Enter does nothing on
- * them.
+ * One flat list — the fixed settings, one row per reasoning group, one per live
+ * tool and one per installed extension — reads as a wall, and the rows that
+ * belong together (a mode and the groups it controls; a timeout and the per-tool
+ * exemptions from it) end up separated by rows that have nothing to do with
+ * them. The headers are inert rows: no `values`, so Enter does nothing on them.
  */
 export type Section = 'session' | 'checks' | 'research' | 'reasoning' | 'timeouts' | 'unattended' | 'logging' | 'extensions';
 /** Section order, and the label each header renders. */
@@ -113,9 +103,8 @@ export declare const SECTION_ID_PREFIX = "section:";
 /**
  * Every setting rendered by /task-config, in display order.
  *
- * Exported so the round-trip property below can be asserted over the WHOLE table
- * rather than per setting — the check that would have caught a forgotten arm in
- * either of the two ladders this replaced.
+ * Exported so the round-trip property in `config-items.test.ts` can be asserted
+ * over the WHOLE table rather than per setting.
  */
 export declare const ITEMS: ConfigItem[];
 export declare function extensionItems(extensions: InstalledExtension[]): ConfigItem[];
@@ -134,10 +123,10 @@ export declare function applyToolToggle(exempt: readonly string[], toolName: str
  * parent is also a row.
  *
  * So a child is drawn as a tree branch under its parent and loses the repeated
- * `think: research:` prefix, which is 15 columns of the same text on four
- * consecutive lines. `└─` on the last child, `├─` on the rest, decided from the
- * group's position in {@link REASONING_GROUPS} rather than a hand-kept list —
- * adding a fifth worker moves the corner on its own.
+ * `think: research:` prefix, the same text at the head of four consecutive
+ * lines. `└─` on the last child, `├─` on the rest, decided from the group's
+ * position in {@link REASONING_GROUPS} rather than a hand-kept list — adding a
+ * fifth worker moves the corner on its own.
  *
  * Leading spaces survive: SettingsList pads the label right, never trims it.
  */
@@ -150,8 +139,8 @@ export declare function reasoningItems(): ConfigItem[];
  * a per-group choice. The seeding step is what stops that from being a trap: on
  * the way out of `default`/`on`/`off` every OTHER group is first pinned to the
  * level it was already running at, so changing one row changes one row. Without
- * it, nudging `research` while in `off` would silently return the other six to
- * whatever the stored table happened to hold.
+ * it, nudging `research` while in `off` would silently return every other group
+ * to whatever the stored table happened to hold.
  */
 export declare function applyReasoningLevel(cfg: PiTaskConfig, group: ReasoningGroup, chosen: string): void;
 /**
@@ -192,10 +181,10 @@ export declare function createSettingsPanel(items: PanelItem[], theme: Theme,
  * Called with the row's id, its new value, and the LIST ITSELF.
  *
  * The list is handed back because some rows change what OTHER rows display:
- * flipping `reasoning` to off means all seven `think:` rows now run at off,
- * and a row's `currentValue` is a snapshot taken when the panel was built.
- * Without a way to write the others back, the menu shows `reasoning off`
- * beside seven rows still claiming `inherit` — which is what it did.
+ * flipping `reasoning` to off means every `think:` row now runs at off, and
+ * a row's `currentValue` is a snapshot taken when the panel was built.
+ * Without a way to write the others back, the menu would show
+ * `reasoning off` beside rows still claiming `inherit`.
  */
 onChange: (id: string, newValue: string, list: SettingsList) => void, onCancel: () => void): BorderedBox;
 /**
@@ -204,10 +193,10 @@ onChange: (id: string, newValue: string, list: SettingsList) => void, onCancel:
  * One list of `ConfigItem`s — so a row's display, its write-back and its section
  * are one object, the dispatch is a lookup by id, and the round-trip properties
  * in `config-items.test.ts` cover the reasoning, tool and extension families
- * that used to bypass the row type entirely.
+ * through the same row type as everything else.
  *
- * Fixed rows come before discovered ones within a section, which is the order
- * the hand-written `extra` map produced.
+ * Fixed rows come before discovered ones within a section, so a freshly
+ * installed extension appends rather than reshuffling the menu.
  */
 export declare function configRows(installed: InstalledExtension[], tools?: readonly GuardableTool[]): ConfigItem[];
 /** Render `rows` for the current config, grouped under their section headers. */
@@ -219,15 +208,12 @@ export declare function panelItems(cfg: PiTaskConfig, installed: InstalledExtens
  *
  * A row's `currentValue` in the live list is a snapshot taken when the panel was
  * built, and rows describe each other: cycling `reasoning` to `off` changes what
- * all seven `think:` rows run at, and cycling one group row flips the mode,
- * which changes the other six.
+ * every `think:` row runs at, and cycling one group row flips the mode, which
+ * changes all the others.
  *
- * This runs after ANY change, over EVERY row. Its predecessor,
- * `refreshReasoningRows`, ran after any change too — but hard-coded the seven
- * reasoning ids plus `reasoningMode` and touched none of the other ~30 rows, so
- * the next cross-row dependency would have needed a fifth function. Re-reading a
- * `format` costs nothing, which is why there is still no list of "changes that
- * need a refresh" to keep correct.
+ * This runs after ANY change, over EVERY row. Re-reading a `format` costs
+ * nothing, which is why there is no list of "changes that need a refresh" to
+ * keep correct.
  */
 export declare function syncRows(cfg: PiTaskConfig, rows: readonly ConfigItem[], list: SettingsList): void;
 export declare function registerConfig(pi: ExtensionAPI): void;

package/dist/config/register.js

@@ -78,8 +78,7 @@ export const SECTIONS = [
     { key: 'logging', title: 'logging' },
     { key: 'extensions', title: 'child extensions' },
     // Last on purpose. It is the longest block (a fixed timeout plus one row
-    // per live tool, so it grows with the host) and the least often changed —
-    // in front of `unattended` it pushed every short section off the screen.
+    // per live tool, so it grows with the host) and the least often changed.
     { key: 'timeouts', title: 'timeouts' }
 ];
 /** Marks a header row, so onChange can ignore one and tests can find them. */
@@ -88,9 +87,8 @@ export const SECTION_ID_PREFIX = 'section:';
  * An inert titled row. No `values` ⇒ SettingsList's Enter handler no-ops on it,
  * and {@link SkipInertRows} steps the cursor straight over it.
  *
- * Upper case, and styled muted by {@link makeTheme}, because the dashed
- * lower-case form it replaces was the same case, colour and weight as the
- * setting labels underneath it — eight headings that read as nine more rows.
+ * Upper case, and styled muted by {@link makeTheme}, so a heading does not read
+ * as one more setting row.
  */
 function sectionHeader(title) {
     return {
@@ -132,9 +130,8 @@ function booleanItem(section, id, label, description) {
 /**
  * Every setting rendered by /task-config, in display order.
  *
- * Exported so the round-trip property below can be asserted over the WHOLE table
- * rather than per setting — the check that would have caught a forgotten arm in
- * either of the two ladders this replaced.
+ * Exported so the round-trip property in `config-items.test.ts` can be asserted
+ * over the WHOLE table rather than per setting.
  */
 export const ITEMS = [
     booleanItem('session', 'remote', 'remote control', 'Serve the task UI on your local network so you can follow and steer a run from '
@@ -317,13 +314,13 @@ export function applyToolToggle(exempt, toolName, watched) {
  *
  * SHOWN IN EVERY MODE, not only `custom`. Two reasons, and the second is the
  * real one:
- *  - `SettingsList` fixes the overlay's body height from the descriptions it was
- *    constructed with (see createSettingsPanel), so rows that appear and vanish
- *    would leave the box sized for the wrong list.
+ *  - {@link createSettingsPanel} pads the box to a height computed from the
+ *    descriptions it was handed, so rows that appear and vanish would leave the
+ *    box sized for the wrong list.
  *  - The value displayed is what the group ACTUALLY runs at — resolveReasoning,
- *    not the stored custom table. That makes the measured `default` table
- *    readable from the menu instead of hidden in a source file, which is the
- *    whole point of having measured it.
+ *    not the stored custom table. In mode `off` every row reads `off` even
+ *    though the custom table underneath is untouched, which is the honest
+ *    answer to "what will my next child do".
  */
 const REASON_ID_PREFIX = 'reason:';
 /**
@@ -336,10 +333,10 @@ const REASON_ID_PREFIX = 'reason:';
  * parent is also a row.
  *
  * So a child is drawn as a tree branch under its parent and loses the repeated
- * `think: research:` prefix, which is 15 columns of the same text on four
- * consecutive lines. `└─` on the last child, `├─` on the rest, decided from the
- * group's position in {@link REASONING_GROUPS} rather than a hand-kept list —
- * adding a fifth worker moves the corner on its own.
+ * `think: research:` prefix, the same text at the head of four consecutive
+ * lines. `└─` on the last child, `├─` on the rest, decided from the group's
+ * position in {@link REASONING_GROUPS} rather than a hand-kept list — adding a
+ * fifth worker moves the corner on its own.
  *
  * Leading spaces survive: SettingsList pads the label right, never trims it.
  */
@@ -374,15 +371,15 @@ export function reasoningItems() {
  * a per-group choice. The seeding step is what stops that from being a trap: on
  * the way out of `default`/`on`/`off` every OTHER group is first pinned to the
  * level it was already running at, so changing one row changes one row. Without
- * it, nudging `research` while in `off` would silently return the other six to
- * whatever the stored table happened to hold.
+ * it, nudging `research` while in `off` would silently return every other group
+ * to whatever the stored table happened to hold.
  */
 export function applyReasoningLevel(cfg, group, chosen) {
     if (!REASONING_SETTINGS.includes(chosen))
         return;
     if (cfg.reasoningMode !== 'custom') {
         // Freeze the table exactly as it runs today, then switch to custom, so
-        // opening one row cannot silently move the other six.
+        // opening one row cannot silently move the rest.
         cfg.reasoningLevels = effectiveReasoning(cfg);
         cfg.reasoningMode = 'custom';
     }
@@ -438,10 +435,9 @@ const DOWN_KEY = '\x1b[B';
  * Moves the cursor over the section headers and the blank rows between them.
  *
  * Those rows are decoration: they carry no `values`, so Enter already does
- * nothing on them. Without this they were still stops on the way down — with a
- * heading AND a blank line per section that is sixteen dead keypresses in a
- * thirty-row menu, and the panel opens with the cursor parked on a heading that
- * has no description to show.
+ * nothing on them. Without this they were still stops on the way down — a
+ * heading AND a blank line for every section — and the panel opens with the
+ * cursor parked on a heading that has no description to show.
  *
  * It drives the list through its own public `handleInput` — pressing the very
  * key the user pressed, N times — rather than reaching for the private
@@ -506,10 +502,10 @@ export function createSettingsPanel(items, theme,
  * Called with the row's id, its new value, and the LIST ITSELF.
  *
  * The list is handed back because some rows change what OTHER rows display:
- * flipping `reasoning` to off means all seven `think:` rows now run at off,
- * and a row's `currentValue` is a snapshot taken when the panel was built.
- * Without a way to write the others back, the menu shows `reasoning off`
- * beside seven rows still claiming `inherit` — which is what it did.
+ * flipping `reasoning` to off means every `think:` row now runs at off, and
+ * a row's `currentValue` is a snapshot taken when the panel was built.
+ * Without a way to write the others back, the menu would show
+ * `reasoning off` beside rows still claiming `inherit`.
  */
 onChange, onCancel) {
     // A row with no `values` is a header or the blank line above one.
@@ -523,10 +519,10 @@ onChange, onCancel) {
  * One list of `ConfigItem`s — so a row's display, its write-back and its section
  * are one object, the dispatch is a lookup by id, and the round-trip properties
  * in `config-items.test.ts` cover the reasoning, tool and extension families
- * that used to bypass the row type entirely.
+ * through the same row type as everything else.
  *
- * Fixed rows come before discovered ones within a section, which is the order
- * the hand-written `extra` map produced.
+ * Fixed rows come before discovered ones within a section, so a freshly
+ * installed extension appends rather than reshuffling the menu.
  */
 export function configRows(installed, tools = []) {
     // The discovered rows carry a section like every other row — the per-tool
@@ -567,15 +563,12 @@ export function panelItems(cfg, installed, tools = []) {
  *
  * A row's `currentValue` in the live list is a snapshot taken when the panel was
  * built, and rows describe each other: cycling `reasoning` to `off` changes what
- * all seven `think:` rows run at, and cycling one group row flips the mode,
- * which changes the other six.
+ * every `think:` row runs at, and cycling one group row flips the mode, which
+ * changes all the others.
  *
- * This runs after ANY change, over EVERY row. Its predecessor,
- * `refreshReasoningRows`, ran after any change too — but hard-coded the seven
- * reasoning ids plus `reasoningMode` and touched none of the other ~30 rows, so
- * the next cross-row dependency would have needed a fifth function. Re-reading a
- * `format` costs nothing, which is why there is still no list of "changes that
- * need a refresh" to keep correct.
+ * This runs after ANY change, over EVERY row. Re-reading a `format` costs
+ * nothing, which is why there is no list of "changes that need a refresh" to
+ * keep correct.
  */
 export function syncRows(cfg, rows, list) {
     for (const row of rows)
@@ -600,11 +593,10 @@ async function handleTaskConfig(_args, ctx, getTools = () => []) {
     // it can only be read here, when the menu opens, never at registration.
     const tools = getTools();
     if (ctx.mode !== 'tui') {
-        // Reads the SAME `format` the panel does, so the two renderings cannot
-        // disagree about what a setting currently says.
-        // Built from panelItems, not a second hand-written walk of the same
-        // tables: the two renderings used to be able to disagree about what a
-        // setting said, and a headless run is the one place nobody would notice.
+        // Built from panelItems and reading the SAME `format` the panel does,
+        // so the two renderings cannot disagree about what a setting says. A
+        // second walk of the same tables is the one place nobody would notice
+        // them drifting, because a headless run has no panel to compare against.
         const lines = panelItems(cfg, installed, tools)
             // The blank rows between sections are there to give the TUI air.
             // One line of `|`-joined text has none to give, and an empty label
@@ -621,12 +613,10 @@ async function handleTaskConfig(_args, ctx, getTools = () => []) {
     const rows = configRows(installed, tools);
     await ctx.ui.custom((_tui, theme, _kb, done) => createSettingsPanel(renderRows(cfg, rows), theme, (id, newValue, list) => {
         // Every row parses its own value. There is no generic
-        // fallback and no prefix ladder: the ladder this replaces
-        // ended in one that wrote `newValue === 'on'` into whatever
-        // field it was handed, so a new enum setting silently became
-        // a boolean until someone noticed. A header row carries no
-        // `values`, so SettingsList never cycles it and it matches
-        // no row here anyway.
+        // fallback and no prefix ladder, so a row that forgets to
+        // parse cannot fall through to something that guesses. A
+        // header row carries no `values`, so SettingsList never
+        // cycles it and it matches no row here anyway.
         rows.find(row => row.id === id)?.apply(cfg, newValue);
         syncRows(cfg, rows, list);
         saveConfig(cfg).catch(() => { });

package/dist/config/tool-list.d.ts

@@ -4,28 +4,28 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
  * the live session rather than named by hand.
  *
  * WHY DISCOVERY AND NOT A HAND-EDITED NAME LIST: the watchdog arms on ANY tool
- * (see task/command-watchdog.ts), which is correct for `bash` — pi's bash takes
- * an OPTIONAL `timeout` with no default, so an unbounded command runs forever —
- * but wrong for an extension tool that already owns a longer, bounded contract
- * of its own. Those tools get aborted mid-transaction at the generic ceiling.
- * The operator has to be able to say "not this one", and the only identity that
- * survives a rename or an uninstall is the one pi itself reports.
+ * (see task/command-watchdog.ts), which is correct for `bash` — its `timeout`
+ * is optional and has no default (`resolveTimeoutMs` returns undefined when it
+ * is omitted), so an unbounded command runs forever — but wrong for an
+ * extension tool that already owns a longer, bounded contract of its own. Those
+ * tools get aborted mid-transaction at the generic ceiling. The operator has to
+ * be able to say "not this one", and the only identity that survives a rename
+ * or an uninstall is the one pi itself reports.
  *
- * MEASURED against pi 0.83.0 (`pi.getAllTools()`), not assumed:
- *   - built-ins report `source: "builtin"`, `path: "<builtin:bash>"`
- *   - extension tools report the extension's real entry-point path — the SAME
+ * What `pi.getAllTools()` reports:
+ *   - built-ins carry `source: "builtin"` and a synthetic `<builtin:name>` path
+ *   - extension tools carry the extension's real entry-point path — the SAME
  *     identity `extensionWhitelist` keys on (see extension-list.ts)
- *   - `getAllTools()` THROWS during extension loading ("Extension runtime not
- *     initialized"); it is only callable from `session_start` onward, which is
- *     why this is read when the menu opens and never at registration.
- *   - `getActiveTools()` is a strict SUBSET (4 of 7 built-ins in a plain
- *     session), so it is the wrong source: a tool the model isn't currently
- *     offered is still a tool the watchdog would arm on if it ran.
+ *   - it THROWS during extension loading ("Extension runtime not initialized"),
+ *     so this is read when the menu opens and never at registration
+ *   - `getActiveTools()` returns only what the model is currently offered, which
+ *     is the wrong source: a tool that is not offered right now is still a tool
+ *     the watchdog would arm on if it ran.
  */
 export interface GuardableTool {
     /** Exact tool name — the watchdog's key, and what the config stores. */
     name: string;
-    /** Provenance shown in the menu, e.g. "built in" or "npm:pi-fable". */
+    /** Provenance shown in the menu, e.g. "built in" or "npm:pi-fable (/path)". */
     origin: string;
 }
 /**

package/dist/config/tool-list.js

@@ -1,4 +1,4 @@
-/** `source` values pi reports for its own tools rather than an extension's. */
+/** The `source` pi reports for its own tools rather than an extension's. */
 const BUILTIN_SOURCE = 'builtin';
 /**
  * Human provenance for a tool's source metadata. `source` is pi's own word for

package/dist/remote/bridge.d.ts

@@ -25,14 +25,20 @@ export interface AskSpec {
     displayQuestion?: string;
     /** Plain question text for the browser card. */
     question: string;
-    /** Primary recommended option, prefilled in the local TUI. */
+    /**
+     * Primary recommended option. It is the remote card's "✓ Accept" answer.
+     * Locally it is handed to `ctx.ui.input` as the placeholder argument, which
+     * pi's interactive input component takes and never reads — so with no
+     * `options` the local box opens empty.
+     */
     recommended?: string;
     /**
-     * Placeholder for the local TUI text input when there is NO recommended
-     * option. Local-only: the remote card must not see it, or it would render as
-     * an acceptable recommendation ("✓ Accept" answering with placeholder text).
-     * Used by the steer prompt, whose hint ("type guidance, or leave empty…") is
-     * instructional copy, not an answer.
+     * Instructional copy for the local TUI text input when there is NO
+     * recommended option. Local-only, and deliberately absent from the
+     * PromptMessage below: on the remote it would render as an acceptable
+     * recommendation ("✓ Accept" answering with instructional text). Its one
+     * producer is the steer prompt. Like `recommended` it reaches pi as the
+     * `input` placeholder, which pi's input component ignores.
      */
     localPlaceholder?: string;
     /** Secondary recommended option shown as a second button on the remote. */
@@ -44,8 +50,10 @@ export interface AskSpec {
      * a bare text input — one option per line, arrow-key navigable. Each entry's
      * `label` is what the picker displays; its `value` is what ask() resolves to
      * when chosen. A built-in "type a different answer" entry is appended that
-     * falls back to a text input, preserving the free-text override. Used for the
-     * binary A/B grill/clarify fork. Remote browsers ignore this and keep
+     * falls back to a text input, preserving the free-text override. Produced by
+     * the two-option grill/clarify fork, whose cards are labelled `A:` and `B:`
+     * (buildOptionCards), and by /task-plan's picker. The PromptMessage built in
+     * ask() carries no `options` field, so remote browsers never see it and keep
      * rendering recommended/recommended2 as buttons.
      */
     options?: {
@@ -69,8 +77,9 @@ export interface AskSpec {
      * which the remote already covers with the recommended/recommended2 buttons —
      * these are ACTIONS that mean something other than "here is my answer", so
      * the remote cannot express them by any existing field. /task-plan's "ask the
-     * model" and "proceed to execution" are the only producers; every other call
-     * site omits this and the card is byte-for-byte what it was.
+     * model" and "proceed to execution" are the only producers; for every other
+     * prompt the list is empty, and the browser's makeActionBtns then appends
+     * nothing to the card.
      */
     actions?: {
         label: string;

package/dist/remote/bridge.js

@@ -62,8 +62,9 @@ export class SessionUI {
         // service worker drops the banner if a window is visible+focused (sw.ts),
         // so we always push and let delivery-time visibility decide.
         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.
+        // Local: resolves to a value, or to undefined on cancel or abort. The
+        // catch is belt-and-braces — a rejection here would surface as an
+        // unhandled one rather than as a lost race.
         const local = this.ctx.hasUI ?
             this.askLocal(spec, ac.signal).catch(() => undefined)
             : new Promise(() => { });

package/dist/remote/broadcast.js

@@ -1,4 +1,6 @@
-// globalThis persists across jiti module re-evaluations on session switches
+// pi loads an extension through `createJiti(..., {moduleCache: false})`, so a
+// reload re-evaluates this module and resets its module-level state. globalThis
+// survives that, which is why the client set lives there.
 const g = globalThis;
 if (!g.__piRemoteClients)
     g.__piRemoteClients = new Set();

package/dist/remote/events.js

@@ -25,11 +25,11 @@ export function setupEvents(pi) {
             if (errorMessage || ae.reason === 'error') {
                 const message = errorMessage || 'Request failed';
                 addError(message);
-                // No push here: pi-task only notifies for the two cases the user
-                // cares about — needing their input (the grill/clarify dialog, see
-                // bridge.ask) and a top-level /task or /task-auto run finishing
-                // (orchestrator/auto-orchestrator). A push on every host agent
-                // error — most of them outside any task — is just noise.
+                // No push here: every pushNotify call site in src/ is one of
+                // two things — needing the user's input (bridge.ask) or a
+                // top-level run finishing (runSingleTask under `notifyFinish`,
+                // and run-bracket's announceTerminal). A push on every host
+                // agent error — most of them outside any task — is just noise.
             }
         }
     });
@@ -47,12 +47,13 @@ export function setupEvents(pi) {
     });
     pi.on('agent_end', (_event, ctx) => {
         agentEnd(ctx.getContextUsage(), ctx.model?.name);
-        // Deliberately no push: agent_end fires on EVERY host turn — every chat
-        // reply, every internal phase turn inside /task, and every internal /task
-        // run inside /task-auto — so a "Task finished" push here floods the device.
-        // The real "a run finished" push is fired from the top-level command
-        // handlers instead (orchestrator handleTask/handleTaskResume, and
-        // auto-orchestrator's runAutoLoop), which never fire for internal runs.
+        // Deliberately no push: agent_end fires on EVERY host-session turn —
+        // every chat reply, and the implementation turn of every task, including
+        // each task inside a /task-auto run — so a "Task finished" push here
+        // floods the device. (Phase children are spawned pi processes running
+        // --no-extensions, so they never reach this handler at all.) The real
+        // "a run finished" push is gated on `notifyFinish`, which only the
+        // top-level command handlers pass.
     });
     pi.on('input', (event, _ctx) => {
         if (event.source === 'interactive' && typeof event.text === 'string') {

package/dist/remote/history.d.ts

@@ -25,7 +25,7 @@ export interface Turn {
     role: 'user' | 'assistant' | 'system';
     /** User text, error text, or a system note. Assistant content lives in `parts`. */
     text?: string;
-    /** Ordered assistant content (text + tools). */
+    /** Ordered assistant content — text, thinking and tool parts, interleaved. */
     parts?: Part[];
     error?: boolean;
     /** Epoch ms when the turn was committed — the client renders a dim HH:MM. */

package/dist/remote/protocol.d.ts

@@ -7,7 +7,8 @@ export interface PromptMessage {
     /**
      * Buttons that answer with their own `value` instead of with an answer to the
      * question — /task-plan's "ask the model" and "proceed to execution". Absent
-     * on every other prompt, so an older card renders exactly as before.
+     * on every other prompt, and the browser's makeActionBtns then appends
+     * nothing to the card.
      */
     actions?: {
         label: string;
@@ -67,8 +68,10 @@ export interface ContextUsage {
     contextWindow?: number;
     percent?: number;
 }
-/** Seeds the context-usage bar for a freshly-connected client (the live value is
- *  otherwise only carried on agent_end). */
+/** A standalone context-usage update. The browser handles it, but nothing in
+ *  `src/` sends one: a connecting client is seeded from the snapshot's `context`
+ *  field, and the live value rides on `agent_end`. The only caller of
+ *  `setContext`, which emits this, is the test suite. */
 export interface ContextMessage {
     type: 'context';
     contextUsage: ContextUsage;

package/dist/remote/protocol.js

@@ -1,5 +1,6 @@
 // Wire format shared by the WS server and the inline browser app.
-// Keep these shapes in sync with the hand-written switch in ui.ts.
+// Keep these shapes in sync with the hand-written `switch (msg.type)` in
+// ui-script.ts, which is where the browser decodes them.
 export function isClientMessage(x) {
     if (typeof x !== 'object' || x === null)
         return false;

package/dist/remote/push.d.ts

@@ -11,27 +11,27 @@ export interface VapidKeys {
     publicKey: string;
     privateKey: string;
 }
-/** 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 declare function vapidStorePath(): string;
 /** 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 declare function subscriptionsStorePath(): 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`). */
+/** 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 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. */
+ *  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 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. */
@@ -54,8 +54,8 @@ export declare function deliver(targets: PushSubscriptionJSON[], payload: 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. */
+/** 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 declare function pushNotify(title: string, body: string, tag?: string): Promise<void>;
 export {};