pi-note 0.33.4 → 0.35.0

package/README.md

@@ -92,12 +92,55 @@ missing/stale revisions fail closed. Resume, reload and `/new` never replay the
 handoff or replace another selection. Pi keeps its normal endpoint/token settings.
 With pi-note 0.33.4+, completing the launched task from the menu, footer or
 **Complete task and exit** exits Pi directly, so Kitty closes its dedicated tab
-(or the standalone window's last tab). Completion never runs Git commands;
-Git configuration and network availability do not affect closing the session.
+(or the standalone window's last tab). Pinote itself never runs Git commands;
+optional local completion hooks can briefly delay closing (see below).
 This ownership survives `/reload`, but not `/new`, resume, fork, tree navigation
 or process restart. Completing a different task or an externally completed task
 does not close Pi; failed/uncertain completion stays open.
 
+### Local completion event (pi-note 0.35.0+)
+
+Trusted sibling extensions can listen on `pi.events` for `pinote:task-completed`:
+
+```ts
+pi.events.on('pinote:task-completed', (event) => {
+  const { taskId, signal, waitUntil } = event as {
+    taskId: number;
+    signal: AbortSignal;
+    waitUntil(work: Promise<unknown>): void;
+  };
+  waitUntil(Promise.resolve().then(() => doLocalWork(taskId, signal))); // Register before any await.
+});
+```
+
+This local event fires exactly once only after this client's acknowledged **Done**
+action clears a valid selected task, across menu, footer and exit/new-session paths.
+`taskId` is the original positive safe-integer task ID, not the cleared selection.
+External completions, notifications, clear-selection actions and failed/stale Done
+attempts do not emit it. Pinote does not submit a model prompt for this event.
+
+Pi's event bus is synchronous fire-and-forget: returning an async handler's promise
+is insufficient. Call `waitUntil` during dispatch; late registrations are ignored.
+Put potentially throwing work inside the registered promise, as above. Exceptions
+thrown by the listener itself before registration are handled by Pi's own logger,
+which may print their raw text; Pinote cannot intercept those bus errors.
+All registered work is awaited outside Pinote's serial queue (so listeners may use
+`pinote:query-current`) before Done returns or a launched session auto-exits.
+Without registered work, completion proceeds immediately. Ordinary Done still
+keeps the conversation open.
+
+There is one fixed **25-second total deadline**, shared by all listeners. The signal
+aborts on session lifetime cancellation, deadline, or hook settlement; listeners
+must honor it and avoid blocking synchronous work. Timers cannot preempt JavaScript
+that blocks the event loop. On runtime teardown, `signal.reason` carries Pi's
+shutdown reason (`quit`, `reload`, `new`, `resume`, or `fork`). A listener with its
+own awaited shutdown handler may finish bounded work on `quit`; other cancellation
+still stops its work. Hook rejection, timeout or cancellation never undo an
+acknowledged completion, invalidate its state, or retry remote writes. Registered
+promise rejections and timeouts produce only a generic warning when UI is available;
+Pinote does not display their error or response text. This is a trusted local extension API, not remote task
+instructions or authorization to run models or external actions.
+
 ### Agent tools and context
 
 The extension registers `pinote_search`, `pinote_get_task`, `pinote_get_current`,

package/dist-mcp/mcp/events.js

@@ -0,0 +1,150 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+const LIMIT = 256;
+const safe = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+/** One bounded CLI scan per tick, shared by all subscribers; no in-memory replay queue. */
+export function completionEvents(log) {
+    const subscribers = new Set();
+    let timer;
+    let running;
+    let controller;
+    let stopped = false;
+    const reject = (res, status, message) => {
+        res.writeHead(status, { 'Content-Type': 'text/plain' });
+        res.end(`${message}\n`);
+    };
+    const drop = (sub) => {
+        subscribers.delete(sub);
+        if (!subscribers.size) {
+            clearTimeout(timer);
+            timer = undefined;
+            controller?.abort();
+        }
+    };
+    const write = (sub, frame) => {
+        // Disconnect rather than queue unbounded data. Resume from the last persisted ID.
+        if (!sub.res.write(frame)) {
+            drop(sub);
+            sub.res.destroy();
+        }
+    };
+    const checkpoint = (sub, id) => {
+        write(sub, `id: ${id}\nevent: checkpoint\ndata: {}\n\n`);
+        sub.cursor = id;
+    };
+    const read = async (after) => {
+        const { stdout } = await exec(process.env.PINOTE_NOTE_COMMAND || 'note', ['--no-notify', 'events', '--limit', String(LIMIT), ...(after === undefined ? [] : ['--after', String(after)])], { signal: controller.signal, timeout: 10_000, maxBuffer: 256 * 1024 });
+        const page = JSON.parse(stdout);
+        if (!safe(page.cursor) || after !== undefined && page.cursor < after || !Array.isArray(page.events) || page.events.length > LIMIT)
+            throw new Error('Invalid event page');
+        let previous = after ?? 0;
+        for (const event of page.events) {
+            if (!safe(event.id) || event.id <= previous || event.id > page.cursor || !safe(event.task_id) || !event.task_id || typeof event.timestamp !== 'string' || event.timestamp.length > 128 || /[\r\n]/.test(event.timestamp))
+                throw new Error('Invalid completion');
+            previous = event.id;
+        }
+        return page;
+    };
+    const tick = async () => {
+        controller = new AbortController();
+        try {
+            const pending = [...subscribers].filter((sub) => !sub.ready);
+            if (pending.length) {
+                const tail = (await read()).cursor;
+                // New arrivals must not be validated against a tail captured before they joined.
+                for (const sub of pending) {
+                    if (!subscribers.has(sub))
+                        continue;
+                    if (sub.cursor !== undefined && sub.cursor > tail) {
+                        drop(sub);
+                        reject(sub.res, 400, 'Last-Event-ID is ahead of current event history');
+                        continue;
+                    }
+                    sub.res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'X-Accel-Buffering': 'no' });
+                    sub.ready = true;
+                    checkpoint(sub, sub.cursor ?? tail);
+                }
+            }
+            if (!subscribers.size || stopped)
+                return;
+            const ready = [...subscribers].filter((sub) => sub.ready);
+            if (!ready.length)
+                return;
+            const after = Math.min(...ready.map((sub) => sub.cursor));
+            const page = await read(after);
+            for (const sub of ready) {
+                if (!subscribers.has(sub))
+                    continue;
+                for (const event of page.events) {
+                    if (event.id <= sub.cursor)
+                        continue;
+                    write(sub, `id: ${event.id}\nevent: task.completed\ndata: ${JSON.stringify({ task_id: event.task_id, timestamp: event.timestamp })}\n\n`);
+                    sub.cursor = event.id;
+                    if (!subscribers.has(sub))
+                        break;
+                }
+                if (!subscribers.has(sub))
+                    continue;
+                if (page.cursor > sub.cursor)
+                    checkpoint(sub, page.cursor);
+                if (!subscribers.has(sub))
+                    continue;
+                if (Date.now() - sub.heartbeat >= 15_000) {
+                    write(sub, ': heartbeat\n\n');
+                    sub.heartbeat = Date.now();
+                }
+            }
+        }
+        catch {
+            if (subscribers.size && !stopped)
+                log();
+            for (const sub of subscribers) {
+                if (!sub.res.headersSent)
+                    reject(sub.res, 503, 'Event history unavailable');
+                else
+                    sub.res.end();
+            }
+            subscribers.clear();
+        }
+        finally {
+            controller = undefined;
+        }
+    };
+    const schedule = () => {
+        if (stopped || running || !subscribers.size)
+            return;
+        running = tick().finally(() => {
+            running = undefined;
+            if (!stopped && subscribers.size)
+                timer = setTimeout(() => { timer = undefined; schedule(); }, 1000);
+        });
+    };
+    return {
+        handle(req, res) {
+            if (req.method !== 'GET') {
+                res.setHeader('Allow', 'GET');
+                return reject(res, 405, 'GET required');
+            }
+            const raw = req.headers['last-event-id'];
+            if (raw !== undefined && (typeof raw !== 'string' || !/^[0-9]{1,16}$/.test(raw) || !safe(Number(raw))))
+                return reject(res, 400, 'Last-Event-ID must be a nonnegative safe integer');
+            if (stopped || subscribers.size >= 64)
+                return reject(res, 503, 'Event stream limit reached');
+            const sub = { res, cursor: raw === undefined ? undefined : Number(raw), ready: false, heartbeat: Date.now() };
+            subscribers.add(sub);
+            res.once('close', () => drop(sub));
+            if (!timer)
+                schedule();
+        },
+        async close() {
+            stopped = true;
+            clearTimeout(timer);
+            controller?.abort();
+            for (const sub of subscribers)
+                sub.res.end();
+            subscribers.clear();
+            await running;
+        },
+    };
+}

package/dist-mcp/mcp/http.js

@@ -7,6 +7,7 @@ import { isIP } from 'node:net';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { createPinoteServer } from "./core.js";
+import { completionEvents } from "./events.js";
 import { pinoteToken } from "../token.js";
 function diagnostic(path, event) {
     const line = `${new Date().toISOString()} Pinote HTTP ${event}\n`;
@@ -37,6 +38,7 @@ export async function startPinoteHttpServer(options = {}) {
     // Fail startup if the configured log is not writable.
     appendFileSync(logPath, '', { mode: 0o600 });
     const log = (event) => diagnostic(logPath, event);
+    const events = completionEvents(() => log('event polling failed'));
     const digest = (value) => createHash('sha256').update(value).digest();
     const expected = digest(`Bearer ${token}`);
     const sessions = new Map();
@@ -66,10 +68,12 @@ export async function startPinoteHttpServer(options = {}) {
                 return reject(res, 403);
             if (req.headers.origin !== undefined && !options.allowedOrigins?.includes(req.headers.origin))
                 return reject(res, 403);
-            if (req.url !== '/mcp')
-                return reject(res, 404);
             if (stopping)
                 return reject(res, 503);
+            if (req.url === '/events')
+                return events.handle(req, res);
+            if (req.url !== '/mcp')
+                return reject(res, 404);
             if (!['GET', 'POST', 'DELETE'].includes(req.method ?? '')) {
                 res.setHeader('Allow', 'GET, POST, DELETE');
                 return reject(res, 405);
@@ -188,6 +192,7 @@ export async function startPinoteHttpServer(options = {}) {
         const closed = new Promise((ok) => listener.close(() => ok()));
         const force = setTimeout(() => listener.closeAllConnections(), 3000);
         try {
+            await events.close();
             await Promise.allSettled([...all].map((session) => session.server.close()));
             await closed;
         }

package/mcp/README.md

@@ -18,6 +18,11 @@ export PINOTE_NOTE_COMMAND="$PWD/.venv/bin/note"
 npm --prefix pi run serve
 ```
 
+After building, production installs may prune development/peer-only packages:
+`npm --prefix pi prune --omit=dev --omit=peer --ignore-scripts`.
+Run `npm --prefix pi run check:runtime` before restarting the service; its required
+terminal-width helpers are runtime dependencies, not development-only packages.
+
 The bearer token is mandatory, including on loopback: use at least 32 random
 non-whitespace characters. Store it in an owner-only regular file (mode `0600`),
 never commit or paste it into a conversation. For a new setup, after creating the
@@ -52,7 +57,7 @@ share. Point every client at the service instead.
 
 The Node listener is plaintext HTTP. **Never expose it directly to the public
 Internet.** Use a private VPN or a trusted HTTPS reverse proxy. The proxy must
-forward `/mcp`, bearer authorization, MCP headers and streaming responses without
+forward `/mcp` and `/events`, bearer authorization, MCP headers and streaming responses without
 buffering, preserve the external Host, and allow long-lived SSE connections.
 
 For example, a local reverse proxy serving `https://notes.example.net/mcp` forwards
@@ -113,8 +118,8 @@ serialize within this daemon and mutations use database/config revisions.
 
 The service bounds request bodies and session counts, and expires idle disconnected
 sessions. Active streams and operations are not expired. Shutdown closes sessions;
-a server restart preserves notes but requires clients to reconnect. No durable SSE
-replay, offline writes or automatic mutation retries are provided. After an
+a server restart preserves notes but requires clients to reconnect. MCP notifications have no durable
+replay; offline writes and automatic mutation retries are not provided. After an
 interrupted write, read fresh state before retrying: it may already have committed.
 
 The native terminal UI protocol and `pinote://agent-context` resource are internal
@@ -135,3 +140,52 @@ npm --prefix pi test
 Tests use temporary data and real HTTP/stdio connections, including authentication,
 shared notes, independent selections, conflicts and reconnects. Visual checks use
 Xvfb and private D-Bus; never point them at personal data.
+
+## Task-completion events
+
+`GET /events` on the same listener requires the same bearer token, Host allowlist
+and Origin policy as `/mcp`; it does not require an MCP session. Only GET is
+accepted (405 otherwise). Use `Accept: text/event-stream` and disable proxy buffering.
+The service requires `note` 0.21.0+ via `PINOTE_NOTE_COMMAND` (or `note` on PATH).
+
+With no `Last-Event-ID`, subscription starts at the current durable history tail,
+not with historical replay. Persist the numeric ID from **both** event types:
+
+```text
+id: 0
+event: checkpoint
+data: {}
+
+id: 3
+event: task.completed
+data: {"task_id":1,"timestamp":"2030-01-02T03:04:05.000000+00:00"}
+
+```
+
+An initial checkpoint is always sent, even at cursor 0. Completion IDs are event
+row IDs, not task IDs. Only committed `done` transitions emit completions, whether
+made by CLI, GUI or Pi. Re-marking done, starting/removing tasks and importing
+archived notes do not. Checkpoints advance past unrelated history; idle streams
+receive heartbeat comments every approximately 15 seconds.
+
+Reconnect with `Last-Event-ID: <persisted ID>` to scan subsequent durable history.
+Delivery is **at-least-once**, not exactly once; consumers should deduplicate by
+event ID. IDs must be nonnegative decimal integers no greater than
+9007199254740991. Malformed or future cursors return 400 with a plain-text error
+before streaming begins; unavailable history returns 503. Database replacement or
+restoring an older backup can invalidate a saved cursor and requires an explicit
+consumer decision to establish a fresh baseline.
+
+At most 64 streams (including pending subscriptions) are allowed; excess streams
+return 503. One shared poller scans at most 256 history rows per roughly one-second
+tick using the CLI, with one additional tail read when accepting new subscribers.
+Catchup therefore has bounded throughput. Slow writers are disconnected rather
+than buffered indefinitely and must reconnect. Poll failures close streams; the
+last disconnect stops polling, and service shutdown aborts the CLI and ends streams.
+
+For local integrations, `note events [--after CURSOR] [--limit N]` returns
+`{"cursor":number,"events":[{"id":number,"task_id":number,"timestamp":string}]}`.
+Without `--after` it returns the current tail and an empty array. With `--after`
+(including 0), it scans up to N rows in ascending order (default 256, range 1–1000),
+includes only completions, and advances the cursor across all scanned rows.
+It is a read-only operation with the same safe cursor range and future-cursor rejection.

package/mcp/events.ts

@@ -0,0 +1,116 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+const exec = promisify(execFile);
+const LIMIT = 256;
+type Page = { cursor: number; events: { id: number; task_id: number; timestamp: string }[] };
+type Subscriber = { res: ServerResponse; cursor: number | undefined; ready: boolean; heartbeat: number };
+const safe = (value: unknown): value is number => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+
+/** One bounded CLI scan per tick, shared by all subscribers; no in-memory replay queue. */
+export function completionEvents(log: () => void) {
+  const subscribers = new Set<Subscriber>();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let running: Promise<void> | undefined;
+  let controller: AbortController | undefined;
+  let stopped = false;
+  const reject = (res: ServerResponse, status: number, message: string) => {
+    res.writeHead(status, { 'Content-Type': 'text/plain' }); res.end(`${message}\n`);
+  };
+  const drop = (sub: Subscriber) => {
+    subscribers.delete(sub);
+    if (!subscribers.size) { clearTimeout(timer); timer = undefined; controller?.abort(); }
+  };
+  const write = (sub: Subscriber, frame: string) => {
+    // Disconnect rather than queue unbounded data. Resume from the last persisted ID.
+    if (!sub.res.write(frame)) { drop(sub); sub.res.destroy(); }
+  };
+  const checkpoint = (sub: Subscriber, id: number) => {
+    write(sub, `id: ${id}\nevent: checkpoint\ndata: {}\n\n`);
+    sub.cursor = id;
+  };
+  const read = async (after?: number): Promise<Page> => {
+    const { stdout } = await exec(process.env.PINOTE_NOTE_COMMAND || 'note',
+      ['--no-notify', 'events', '--limit', String(LIMIT), ...(after === undefined ? [] : ['--after', String(after)])],
+      { signal: controller!.signal, timeout: 10_000, maxBuffer: 256 * 1024 });
+    const page: Page = JSON.parse(stdout);
+    if (!safe(page.cursor) || after !== undefined && page.cursor < after || !Array.isArray(page.events) || page.events.length > LIMIT) throw new Error('Invalid event page');
+    let previous = after ?? 0;
+    for (const event of page.events) {
+      if (!safe(event.id) || event.id <= previous || event.id > page.cursor || !safe(event.task_id) || !event.task_id || typeof event.timestamp !== 'string' || event.timestamp.length > 128 || /[\r\n]/.test(event.timestamp)) throw new Error('Invalid completion');
+      previous = event.id;
+    }
+    return page;
+  };
+  const tick = async () => {
+    controller = new AbortController();
+    try {
+      const pending = [...subscribers].filter((sub) => !sub.ready);
+      if (pending.length) {
+        const tail = (await read()).cursor;
+        // New arrivals must not be validated against a tail captured before they joined.
+        for (const sub of pending) {
+          if (!subscribers.has(sub)) continue;
+          if (sub.cursor !== undefined && sub.cursor > tail) {
+            drop(sub); reject(sub.res, 400, 'Last-Event-ID is ahead of current event history'); continue;
+          }
+          sub.res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'X-Accel-Buffering': 'no' });
+          sub.ready = true;
+          checkpoint(sub, sub.cursor ?? tail);
+        }
+      }
+      if (!subscribers.size || stopped) return;
+      const ready = [...subscribers].filter((sub) => sub.ready);
+      if (!ready.length) return;
+      const after = Math.min(...ready.map((sub) => sub.cursor!));
+      const page = await read(after);
+      for (const sub of ready) {
+        if (!subscribers.has(sub)) continue;
+        for (const event of page.events) {
+          if (event.id <= sub.cursor!) continue;
+          write(sub, `id: ${event.id}\nevent: task.completed\ndata: ${JSON.stringify({ task_id: event.task_id, timestamp: event.timestamp })}\n\n`);
+          sub.cursor = event.id;
+          if (!subscribers.has(sub)) break;
+        }
+        if (!subscribers.has(sub)) continue;
+        if (page.cursor > sub.cursor!) checkpoint(sub, page.cursor);
+        if (!subscribers.has(sub)) continue;
+        if (Date.now() - sub.heartbeat >= 15_000) { write(sub, ': heartbeat\n\n'); sub.heartbeat = Date.now(); }
+      }
+    } catch {
+      if (subscribers.size && !stopped) log();
+      for (const sub of subscribers) {
+        if (!sub.res.headersSent) reject(sub.res, 503, 'Event history unavailable'); else sub.res.end();
+      }
+      subscribers.clear();
+    } finally { controller = undefined; }
+  };
+  const schedule = () => {
+    if (stopped || running || !subscribers.size) return;
+    running = tick().finally(() => {
+      running = undefined;
+      if (!stopped && subscribers.size) timer = setTimeout(() => { timer = undefined; schedule(); }, 1000);
+    });
+  };
+  return {
+    handle(req: IncomingMessage, res: ServerResponse) {
+      if (req.method !== 'GET') { res.setHeader('Allow', 'GET'); return reject(res, 405, 'GET required'); }
+      const raw = req.headers['last-event-id'];
+      if (raw !== undefined && (typeof raw !== 'string' || !/^[0-9]{1,16}$/.test(raw) || !safe(Number(raw)))) return reject(res, 400, 'Last-Event-ID must be a nonnegative safe integer');
+      if (stopped || subscribers.size >= 64) return reject(res, 503, 'Event stream limit reached');
+      const sub: Subscriber = { res, cursor: raw === undefined ? undefined : Number(raw), ready: false, heartbeat: Date.now() };
+      subscribers.add(sub);
+      res.once('close', () => drop(sub));
+      if (!timer) schedule();
+    },
+    async close() {
+      stopped = true;
+      clearTimeout(timer);
+      controller?.abort();
+      for (const sub of subscribers) sub.res.end();
+      subscribers.clear();
+      await running;
+    },
+  };
+}

package/mcp/http.ts

@@ -7,6 +7,7 @@ import { isIP } from 'node:net';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { createPinoteServer } from './core.ts';
+import { completionEvents } from './events.ts';
 import { pinoteToken } from '../token.ts';
 
 export interface PinoteHttpOptions {
@@ -48,6 +49,7 @@ export async function startPinoteHttpServer(options: PinoteHttpOptions = {}) {
   // Fail startup if the configured log is not writable.
   appendFileSync(logPath, '', { mode: 0o600 });
   const log = (event: string) => diagnostic(logPath, event);
+  const events = completionEvents(() => log('event polling failed'));
   const digest = (value: string) => createHash('sha256').update(value).digest();
   const expected = digest(`Bearer ${token}`);
   type Session = { transport: StreamableHTTPServerTransport; server: ReturnType<typeof createPinoteServer>; busy: number; streams: number; touched: number };
@@ -74,8 +76,9 @@ export async function startPinoteHttpServer(options: PinoteHttpOptions = {}) {
       }
       if (!allowedHosts.has(req.headers.host ?? '')) return reject(res, 403);
       if (req.headers.origin !== undefined && !options.allowedOrigins?.includes(req.headers.origin)) return reject(res, 403);
-      if (req.url !== '/mcp') return reject(res, 404);
       if (stopping) return reject(res, 503);
+      if (req.url === '/events') return events.handle(req, res);
+      if (req.url !== '/mcp') return reject(res, 404);
       if (!['GET', 'POST', 'DELETE'].includes(req.method ?? '')) { res.setHeader('Allow', 'GET, POST, DELETE'); return reject(res, 405); }
       const id = req.headers['mcp-session-id'];
       if (id !== undefined && (typeof id !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id))) return reject(res, 400);
@@ -162,6 +165,7 @@ export async function startPinoteHttpServer(options: PinoteHttpOptions = {}) {
     const closed = new Promise<void>((ok) => listener.close(() => ok()));
     const force = setTimeout(() => listener.closeAllConnections(), 3000);
     try {
+      await events.close();
       await Promise.allSettled([...all].map((session) => session.server.close()));
       await closed;
     } finally { clearTimeout(force); log('stopped'); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-note",
-  "version": "0.33.4",
+  "version": "0.35.0",
   "description": "Persistent pinote tasks, Markdown handoffs, and task status for Pi",
   "license": "MIT",
   "type": "module",
@@ -59,6 +59,7 @@
     "prepack": "npm run build:mcp",
     "mcp": "node dist-mcp/mcp/server.js",
     "serve": "node dist-mcp/mcp/http.js",
+    "check:runtime": "node --input-type=module -e \"await import('./dist-mcp/mcp/http.js')\"",
     "check": "tsc --noEmit",
     "test:unit": "node --test --experimental-strip-types tests/*.test.ts",
     "test:load": "node --test --experimental-strip-types test-load.ts test-remote-load.ts",
@@ -71,12 +72,12 @@
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "1.4.0",
-    "@earendil-works/pi-tui": "1.4.0",
     "@types/node": "22.20.3",
     "typebox": "1.3.7",
     "typescript": "5.9.3"
   },
   "dependencies": {
+    "@earendil-works/pi-tui": "1.4.0",
     "@modelcontextprotocol/sdk": "^1.32.1",
     "zod": "^4.6.7"
   }

package/remote/completion.ts

@@ -0,0 +1,50 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+export interface TaskCompletedEvent {
+  taskId: number;
+  signal: AbortSignal;
+  /** Register during synchronous event dispatch, before the listener's first await. */
+  waitUntil(work: Promise<unknown>): void;
+}
+
+/** Local, best-effort work only; never turn an acknowledged Done into a failed write. */
+export async function taskCompleted(
+  events: Pick<ExtensionAPI['events'], 'emit'>,
+  taskId: number,
+  lifetime: AbortSignal,
+  warn: () => void,
+): Promise<void> {
+  if (lifetime.aborted) return;
+  const controller = new AbortController();
+  const work: Promise<unknown>[] = [];
+  let accepting = true, warned = false;
+  const warning = () => {
+    if (warned) return;
+    warned = true;
+    try { warn(); } catch { /* Diagnostics must not affect completion. */ }
+  };
+  let finish!: () => void;
+  const cancelled = new Promise<void>((resolve) => { finish = resolve; });
+  const cancel = () => { controller.abort(lifetime.reason); finish(); };
+  lifetime.addEventListener('abort', cancel, { once: true });
+  // One deadline covers dispatch and all listeners, not 25 seconds per listener.
+  const timer = setTimeout(() => { warning(); cancel(); }, 25_000);
+  try {
+    try {
+      events.emit('pinote:task-completed', {
+        taskId, signal: controller.signal,
+        waitUntil(promise: Promise<unknown>) {
+          const registered = accepting;
+          const observed = Promise.resolve(promise).catch(() => { if (registered && !controller.signal.aborted) warning(); });
+          if (registered) work.push(observed);
+        },
+      } satisfies TaskCompletedEvent);
+    } catch { warning(); } // Dispatch failures only; Pi itself catches listener exceptions.
+    finally { accepting = false; }
+    if (work.length) await Promise.race([Promise.all(work), cancelled]);
+  } finally {
+    clearTimeout(timer);
+    lifetime.removeEventListener('abort', cancel);
+    controller.abort();
+  }
+}

package/remote/session.ts

@@ -32,6 +32,7 @@ export class RemoteSession {
   view?: NativeView;
   fullscreen = false;
   onChange = () => {};
+  onCompleted?: (taskId: number, signal: AbortSignal) => Promise<void>;
   private config: RemoteConfig;
   private persist: (saved: SavedState) => void;
   private factory: PeerFactory;
@@ -49,8 +50,8 @@ export class RemoteSession {
     this.persist(this.saved);
     await this.refresh(true);
   }
-  async stop(): Promise<void> {
-    this.active = false; this.epoch++; this.lifetime.abort(); this.connection?.abort();
+  async stop(reason?: string): Promise<void> {
+    this.active = false; this.epoch++; this.lifetime.abort(reason); this.connection?.abort();
     clearTimeout(this.refreshTimer); this.refreshTimer = undefined; this.dirty = false; this.refreshing = false;
     const peer = this.peer; this.peer = undefined; this.view = undefined;
     this.queue = Promise.resolve(); this.onChange();
@@ -171,8 +172,10 @@ export class RemoteSession {
       } catch (error) { if (current()) this.failed(error, mutation && attempted); throw new RemoteFailure(mutation && attempted); }
     }, signal);
   }
-  action(view: NativeView, control: NativeControl, value?: NativeControl['value'], allow = () => true): Promise<{ draft?: string; preview?: string }> {
-    return this.serial(async () => {
+  async action(view: NativeView, control: NativeControl, value?: NativeControl['value'], allow = () => true): Promise<{ draft?: string; preview?: string }> {
+    const signal = this.signal;
+    let completedId: number | undefined;
+    const result = await this.serial(async () => {
       const current = this.current(); let attempted = false;
       if (!allow()) throw new RemoteFailure(false, true);
       const latest = this.view?.controls.find((c) => c.id === control.id && c.kind === control.kind);
@@ -180,10 +183,14 @@ export class RemoteSession {
       try {
         const peer = await this.connected(true);
         if (!allow()) throw new RemoteFailure(false, true);
+        const taskId = this.view?.state.selectedId;
         attempted = true;
         const result = await peer.action({ uri: 'pinote://ui', action: control.id, revision: control.revision ?? view.revision, ...(value === undefined ? {} : { value }), _meta: this.meta() }, this.signal);
         if (!current()) throw new RemoteFailure(true);
         this.apply(result.view);
+        if (control.id === 'done' && control.kind === 'action' &&
+            typeof taskId === 'number' && Number.isSafeInteger(taskId) && taskId > 0 &&
+            result.view.state.selectedId == null) completedId = taskId;
         return result;
       } catch (error) {
         if (!attempted && error instanceof RemoteFailure && error.stale) throw error;
@@ -191,5 +198,11 @@ export class RemoteSession {
         throw new RemoteFailure(attempted);
       }
     });
+    // Outside the serial queue: trusted listeners may query this session themselves.
+    // Hook failures cannot invalidate or replay the acknowledged remote mutation.
+    if (completedId !== undefined && !signal.aborted) {
+      try { await this.onCompleted?.(completedId, signal); } catch { /* Best effort only. */ }
+    }
+    return result;
   }
 }

package/remote.ts

@@ -6,6 +6,7 @@ import { registerTools } from './remote/tools.ts';
 import { registerPreview, RemoteUI } from './remote/ui.ts';
 import { registerRemoteExit } from './remote/exit.ts';
 import { editorText } from './remote/protocol.ts';
+import { taskCompleted } from './remote/completion.ts';
 
 // Only an accepted /new (previousSessionFile) may carry this process-local selection.
 // Reload/resume/fork restore branch entries, never this map or a folder-global store.
@@ -46,6 +47,9 @@ export default function pinoteRemote(pi: ExtensionAPI): void {
     try {
       const config = remoteConfig();
       session = new RemoteSession(config, (saved) => pi.appendEntry(ENTRY_TYPE, saved));
+      session.onCompleted = (taskId, signal) => taskCompleted(pi.events, taskId, signal, () => {
+        if (ctx.hasUI) ctx.ui.notify('Pinote: completion hook did not finish successfully. The task completion remains confirmed.', 'warning');
+      });
       launchKey = `${config.scope}:${ctx.sessionManager.getSessionId()}`;
       ui = new RemoteUI(pi, session, ownsLaunch);
       ui.attach(ctx);
@@ -99,7 +103,7 @@ export default function pinoteRemote(pi: ExtensionAPI): void {
       if (transfers.size >= 32) transfers.delete(transfers.keys().next().value!);
       transfers.set(file, saved);
     }
-    ui?.detach(); await session?.stop();
+    ui?.detach(); await session?.stop(event.reason);
   });
   pi.on('before_agent_start', async (event, ctx) => {
     let text: string;