pi-note 0.18.0 → 0.19.0

package/README.md

@@ -5,6 +5,10 @@ in Pi: selected-task footer status, `/pi-note`, and agent current-task read/upda
 add, and tag-listing tools.
 The extension and Python app share a repository but install separately.
 
+For server-provided UI instead of this Pinote-specific extension, see the opt-in
+[native MCP UI alternative](mcp/README.md). It uses a generic gateway host and has
+explicit initial-version limits; it is not activated by installing this extension.
+
 ## Install
 
 Requires Pi 0.99.1+, Node.js 22.19+ and **pinote 0.3.0+** (`note` on PATH). Add and tag listing need **pinote 0.4.0+**.
@@ -84,7 +88,7 @@ The agent can still read the task separately with `pinote_get_current`.
 Click previews work while the agent is running, provided no other Pinote operation
 is open. Each click saves a fresh snapshot in the transcript, above any currently
 streaming response. Later output scrolls it upward; it does not expire. Preview
-reads never lock out the agent's task updates. Settings still requires Pi to be idle.
+reads never lock out the agent's task updates. Settings also works during a running turn.
 
 ![Preview above a running response](../docs/images/pi-note-active-preview.png)
 
@@ -358,7 +362,11 @@ Pinote no longer polls GitHub, runs `gh`, watches completed tasks, or prompts on
 PR merges. No GitHub authentication is required. `PINOTE_PR_POLL_SECONDS` is no
 longer used. Other separately installed Pi PR/Git extensions are unaffected.
 
-Tools work without a TUI, but `/pi-note` needs an idle TUI.
+Tools work without a TUI. `/pi-note` works in a TUI while the agent is running:
+you can select/switch tasks, use Continue, preview tasks, respond to suggestions,
+and edit settings without interrupting the turn or submitting input. Completion
+and CLI installation/upgrades still require an idle session. Another pending
+Pinote operation blocks the menu. Open menus do not block agent handoff updates.
 This package does not synchronize databases or paths between machines. Note text
 and fields loaded into Pi are sent to the configured model when used as context;
 avoid secrets. Agent commands do not send desktop notifications.

package/config-path.ts

@@ -0,0 +1,16 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Same personal configuration location in Pi and the standalone MCP process.
+export function getAgentDir(): string {
+  let path = process.env.PI_CODING_AGENT_DIR;
+  if (!path) return join(homedir(), '.pi', 'agent');
+  if (path === '~') return homedir();
+  if (process.platform === 'win32' && !path.includes('\\')) {
+    const match = /^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i.exec(path);
+    if (match) path = `${match[1].toUpperCase()}:\\${(match[2] ?? '').replaceAll('/', '\\')}`;
+  }
+  if (path.startsWith('~/') || process.platform === 'win32' && path.startsWith('~\\')) return join(homedir(), path.slice(2));
+  return path.startsWith('file://') ? fileURLToPath(path) : path;
+}

package/dist-mcp/config-path.js

@@ -0,0 +1,19 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// Same personal configuration location in Pi and the standalone MCP process.
+export function getAgentDir() {
+    let path = process.env.PI_CODING_AGENT_DIR;
+    if (!path)
+        return join(homedir(), '.pi', 'agent');
+    if (path === '~')
+        return homedir();
+    if (process.platform === 'win32' && !path.includes('\\')) {
+        const match = /^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i.exec(path);
+        if (match)
+            path = `${match[1].toUpperCase()}:\\${(match[2] ?? '').replaceAll('/', '\\')}`;
+    }
+    if (path.startsWith('~/') || process.platform === 'win32' && path.startsWith('~\\'))
+        return join(homedir(), path.slice(2));
+    return path.startsWith('file://') ? fileURLToPath(path) : path;
+}

package/dist-mcp/footer-config.js

@@ -0,0 +1,167 @@
+import { getAgentDir } from "./config-path.js";
+import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+export const defaultHandoffPrompt = "Read the current Pinote task. Summarize your understanding, but don’t start work yet.";
+export const defaultNewSessionPrompt = defaultHandoffPrompt;
+export function parseNewSessionPrompt(value) {
+    if (typeof value !== "string" || /[\x00-\x08\x0b-\x1f\x7f-\x9f]/u.test(value)) {
+        throw new Error("newSessionPrompt in pi-note.json must be a string without control characters (except tabs/newlines).");
+    }
+    return value;
+}
+export function parseHandoffPrompt(value) {
+    if (typeof value !== "string" || !value.trim() || /[\x00-\x08\x0b-\x1f\x7f-\x9f]/u.test(value)) {
+        throw new Error("handoffPrompt in pi-note.json must be a nonblank string without control characters (except tabs/newlines).");
+    }
+    return value;
+}
+export const defaultFooterConfig = { titleWidth: 60, fieldWidth: 60, maxFields: 4, fields: null };
+export const defaultFooterField = (name) => ({
+    name, label: name, link: true, format: name === "PR" ? "#<number>" : "<value>",
+});
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const width = (value) => Number.isInteger(value) && Number(value) >= 3 && Number(value) <= 1000;
+const safeText = (value) => typeof value === "string" && !/[\x00-\x1f\x7f-\x9f]/u.test(value);
+export function parseFooterConfig(value) {
+    if (!object(value))
+        throw new Error("expected an object");
+    if (value.footer === undefined)
+        return { ...defaultFooterConfig };
+    if (!object(value.footer))
+        throw new Error("footer must be an object");
+    const footer = value.footer;
+    for (const key of ["titleWidth", "fieldWidth"]) {
+        if (footer[key] !== undefined && !width(footer[key]))
+            throw new Error(`${key} must be an integer from 3 to 1000`);
+    }
+    if (footer.maxFields !== undefined &&
+        (!Number.isInteger(footer.maxFields) || Number(footer.maxFields) < 0 || Number(footer.maxFields) > 64)) {
+        throw new Error("maxFields must be an integer from 0 to 64");
+    }
+    let fields = null;
+    if (footer.fields !== undefined && footer.fields !== null) {
+        if (!Array.isArray(footer.fields) || footer.fields.length > 64)
+            throw new Error("fields must be null or an array of at most 64 fields");
+        const seen = new Set();
+        fields = footer.fields.map((entry) => {
+            const field = typeof entry === "string" ? { name: entry } : entry;
+            if (!object(field))
+                throw new Error("each field needs a name");
+            // Accept the original {label: name, width} form as well as explicit names.
+            const source = field.name === undefined ? field.label : field.name;
+            if (!safeText(source))
+                throw new Error("invalid field name");
+            const name = source.normalize("NFC").trim();
+            if (!name || [...name].length > 64 || name === "Bar")
+                throw new Error("invalid field name");
+            if (seen.has(name))
+                throw new Error("duplicate field name");
+            seen.add(name);
+            const label = field.name === undefined ? name : field.label === undefined ? name : field.label;
+            const format = field.format === undefined ? defaultFooterField(name).format : field.format;
+            if (!safeText(label) || [...label].length > 64)
+                throw new Error("invalid display label");
+            if (!safeText(format) || format.length > 4096 || /<(?!value>|number>|url>)[^>]*>/u.test(format)) {
+                throw new Error("format supports only <value>, <number>, and <url>");
+            }
+            if (field.link !== undefined && typeof field.link !== "boolean")
+                throw new Error("link must be a boolean");
+            if (field.width !== undefined && !width(field.width))
+                throw new Error("field width must be an integer from 3 to 1000");
+            return { name, label, link: field.link ?? true, format,
+                ...(field.width === undefined ? {} : { width: field.width }) };
+        });
+    }
+    return {
+        titleWidth: footer.titleWidth ?? defaultFooterConfig.titleWidth,
+        fieldWidth: footer.fieldWidth ?? defaultFooterConfig.fieldWidth,
+        maxFields: footer.maxFields ?? defaultFooterConfig.maxFields, fields,
+    };
+}
+function readRaw() {
+    try {
+        return readFileSync(join(getAgentDir(), "pi-note.json"), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export function readFooterDocument() {
+    const raw = readRaw();
+    let value = {};
+    if (raw !== null) {
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            throw new Error("Invalid JSON in pi-note.json.");
+        }
+    }
+    return { raw, config: parseFooterConfig(value) };
+}
+export function loadFooterConfig(warn) {
+    try {
+        return readFooterDocument().config;
+    }
+    catch {
+        warn("Cannot load pi-note.json; using default Pinote footer settings. Check the footer configuration in pi-note's README.");
+        return { ...defaultFooterConfig };
+    }
+}
+// Synchronous compare-and-replace: reject edits made while the settings dialog was open,
+// preserve unrelated keys, and never leave partial JSON behind.
+export function saveFooterConfig(config, expectedRaw, handoffPrompt, newSessionPrompt, taskOfferPolicy) {
+    if (taskOfferPolicy !== undefined && !["always", "github-remote", "never"].includes(taskOfferPolicy))
+        throw new Error("Invalid taskOfferPolicy");
+    const checked = parseFooterConfig({ footer: config });
+    const prompts = {
+        ...(handoffPrompt === undefined ? {} : { handoffPrompt: parseHandoffPrompt(handoffPrompt) }),
+        ...(newSessionPrompt === undefined ? {} : { newSessionPrompt: parseNewSessionPrompt(newSessionPrompt) }),
+    };
+    const directory = getAgentDir();
+    mkdirSync(directory, { recursive: true });
+    const path = join(directory, "pi-note.json");
+    const lock = join(directory, "pi-note.json.lock");
+    let descriptor;
+    try {
+        descriptor = openSync(lock, "wx", 0o600);
+    }
+    catch {
+        throw new Error("Pinote settings are locked. Retry after another save finishes; remove a stale pi-note.json.lock only when no save is running.");
+    }
+    const temp = join(directory, `.pi-note-${randomUUID()}.tmp`);
+    let raw;
+    try {
+        if (readRaw() !== expectedRaw)
+            throw new Error("Pi-note configuration changed while settings were open. Reopen settings before saving.");
+        if (lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink())
+            throw new Error("pi-note.json is a symlink. Edit its target manually rather than replacing the link.");
+        const root = expectedRaw === null ? {} : JSON.parse(expectedRaw);
+        if (!object(root))
+            throw new Error("Invalid pi-note configuration; expected an object.");
+        raw = `${JSON.stringify({ ...root, ...prompts, ...(taskOfferPolicy === undefined ? {} : { taskOfferPolicy }), footer: checked }, null, 2)}\n`;
+        writeFileSync(temp, raw, { flag: "wx", mode: 0o600 });
+        renameSync(temp, path);
+    }
+    finally {
+        rmSync(temp, { force: true });
+        closeSync(descriptor);
+        rmSync(lock, { force: true });
+    }
+    return { config: checked, raw };
+}
+export function effectiveFooterFields(config, notes = {}) {
+    if (config.fields !== null)
+        return config.fields;
+    const seen = new Set(["Bar"]);
+    return ["PR", ...(notes.Bar ?? "").split("\n")].flatMap((raw) => {
+        const name = raw.normalize("NFC").trim();
+        if (!name || seen.has(name))
+            return [];
+        seen.add(name);
+        return [defaultFooterField(name)];
+    });
+}

package/dist-mcp/icons/add.txt

@@ -0,0 +1 @@
+✚

package/dist-mcp/icons/check.txt

@@ -0,0 +1 @@
+✔

package/dist-mcp/icons/cross.txt

@@ -0,0 +1 @@
+✖

package/dist-mcp/icons/note.txt

@@ -0,0 +1 @@
+📌

package/dist-mcp/mcp/server.js

@@ -0,0 +1,290 @@
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFileSync } from 'node:fs';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { defaultFooterField, defaultHandoffPrompt, defaultNewSessionPrompt, effectiveFooterFields, parseFooterConfig, parseHandoffPrompt, parseNewSessionPrompt, readFooterDocument, saveFooterConfig } from "../footer-config.js";
+const URI = 'pinote://ui';
+const MIME = 'application/vnd.mcp-native-ui+json';
+const CONTEXT = 'native-ui/context';
+const exec = promisify(execFile);
+const noteCommand = process.env.PINOTE_NOTE_COMMAND || 'note';
+const icons = Object.fromEntries(['add', 'check', 'note'].map((name) => [name, readFileSync(new URL(`../icons/${name}.txt`, import.meta.url), 'utf8').trim()]));
+const Context = z.object({ conversationId: z.string().min(1).max(256), state: z.object({
+        selectedId: z.number().int().positive().safe().nullable().optional(), screen: z.enum(['tasks', 'settings', 'field']).optional(),
+        field: z.string().refine((value) => [...value].length <= 64, 'Field name exceeds 64 code points').optional(), search: z.string().max(256).optional(),
+    }).default({}) });
+const Action = z.object({ method: z.literal('native-ui/action'), params: z.object({
+        uri: z.literal(URI), revision: z.string().min(1).max(256), action: z.string().min(1).max(256),
+        value: z.union([z.string().max(20_000), z.number().finite(), z.boolean(), z.null()]).optional(), _meta: z.record(z.unknown()).optional(),
+    }) });
+const server = new Server({ name: 'pinote', version: '0.19.0' }, { capabilities: { tools: {}, resources: {}, experimental: { 'native-ui-v1': {} } } });
+// Serialize complete read/check/write cycles even when a host sends parallel calls.
+let queue = Promise.resolve();
+function serial(run) {
+    const result = queue.then(run);
+    queue = result.then(() => { }, () => { });
+    return result;
+}
+function context(meta) { return Context.parse(meta?.[CONTEXT]); }
+async function note(args, signal) {
+    signal.throwIfAborted();
+    const options = { signal, timeout: 10_000, maxBuffer: 4 * 1024 * 1024 };
+    const version = (await exec(noteCommand, ['--version'], options)).stdout.trim();
+    const match = /^pinote (\d+)\.(\d+)\.(\d+)$/.exec(version);
+    if (!match || Number(match[1]) === 0 && Number(match[2]) < 4)
+        throw new Error('Pinote MCP requires note 0.4.0+');
+    return (await exec(noteCommand, ['--no-notify', ...args], options)).stdout;
+}
+async function selected(state, signal) {
+    if (!state.selectedId)
+        return null;
+    const task = JSON.parse(await note(['agent', 'get', String(state.selectedId)], signal));
+    return task && ['active', 'in_progress'].includes(task.state) ? task : null;
+}
+function fields(config, notes) {
+    // Legacy Bar values are arbitrary task text, not validated field definitions.
+    return effectiveFooterFields(config, notes).flatMap((field) => {
+        try {
+            return parseFooterConfig({ footer: { fields: [field] } }).fields;
+        }
+        catch {
+            return [];
+        }
+    }).slice(0, 64);
+}
+function settings() {
+    const document = readFooterDocument();
+    const root = document.raw === null ? {} : JSON.parse(document.raw);
+    const handoffPrompt = 'handoffPrompt' in root ? parseHandoffPrompt(root.handoffPrompt) : defaultHandoffPrompt;
+    const newSessionPrompt = 'newSessionPrompt' in root ? parseNewSessionPrompt(root.newSessionPrompt) : defaultNewSessionPrompt;
+    const policy = Object.hasOwn(root, 'taskOfferPolicy') ? root.taskOfferPolicy : 'always';
+    if (!['always', 'github-remote', 'never'].includes(policy))
+        throw new Error('Invalid taskOfferPolicy in pi-note.json');
+    return { ...document, handoffPrompt, newSessionPrompt, policy };
+}
+async function snapshot(state, signal) {
+    const tasks = JSON.parse(await note(['list', '--json'], signal));
+    const task = await selected(state, signal);
+    const config = settings();
+    state = { ...state, selectedId: task?.id ?? null };
+    if (state.screen === 'field' && !fields(config.config, task?.agent_notes).some((f) => f.name === state.field))
+        state.screen = 'settings';
+    const revision = createHash('sha256').update(JSON.stringify({ state, tasks, task, raw: config.raw })).digest('hex');
+    return { state, tasks, task, config, revision };
+}
+function view(data) {
+    const { tasks, task, config, revision } = data;
+    const state = Context.parse({ conversationId: 'outgoing-state', state: { ...data.state, selectedId: task?.id ?? null } }).state;
+    const controls = [];
+    const action = (id, label, extra = {}) => controls.push({ id, label: label.slice(0, 2000), kind: 'action', ...extra });
+    let title = 'Pinote · Tasks';
+    let body = task ? task.text : 'Select a task or create one. No task is selected for this conversation.';
+    action('screen:tasks', 'Tasks', { icon: icons.note });
+    action('screen:settings', 'Settings', { description: 'Global prompts, task offers, and footer fields' });
+    if (state.screen === 'settings') {
+        title = 'Pinote · Settings';
+        body = 'Personal pi-note.json · changes save after confirmation';
+        for (const [id, label, value] of [['handoffPrompt', 'Task prompt', config.handoffPrompt], ['newSessionPrompt', 'New session prompt', config.newSessionPrompt]]) {
+            controls.push({ id, label, value, kind: 'text', multiline: true, confirm: 'Save this global prompt?' });
+        }
+        controls.push({ id: 'taskOfferPolicy', label: 'Task offers', kind: 'select', value: config.policy, options: ['always', 'github-remote', 'never'].map((value) => ({ label: value, value })), confirm: 'Save this global task-offer policy?' });
+        for (const key of ['titleWidth', 'fieldWidth', 'maxFields'])
+            controls.push({ id: key, label: key, kind: 'number', value: config.config[key], confirm: 'Save this global footer setting?' });
+        controls.push({ id: 'add-field', label: 'Add field', icon: icons.add, kind: 'text', value: '', confirm: 'Add this global footer field?' });
+        fields(config.config, task?.agent_notes).forEach((field) => action(`field:${field.name}`, field.name, { description: `${field.label || '(no label)'} · ${field.format}` }));
+    }
+    else if (state.screen === 'field') {
+        const field = fields(config.config, task?.agent_notes).find((f) => f.name === state.field);
+        if (!field)
+            throw new Error('Field no longer exists; open Settings again');
+        title = `Pinote · ${field.name}`;
+        body = 'Global footer display definition; task values are unchanged.';
+        controls.push({ id: 'label', label: 'Label', kind: 'text', value: field.label, confirm: 'Save this global field label?' });
+        controls.push({ id: 'format', label: 'Format', kind: 'text', value: field.format, description: '<value>, <url>, <number>', confirm: 'Save this global field format?' });
+        controls.push({ id: 'width', label: 'Width', kind: 'number', value: field.width ?? config.config.fieldWidth, confirm: 'Save this global field width?' });
+        controls.push({ id: 'link', label: 'Link', kind: 'toggle', value: field.link, confirm: 'Change this global link setting?' });
+        action('remove-field', 'Remove field', { confirm: 'Remove this global display definition? Task values are retained.' });
+    }
+    else {
+        if (task) {
+            if (config.handoffPrompt.length <= 20_000)
+                action('continue', 'Continue', { description: 'Request insertion of the task prompt; never submit it' });
+            action('preview', 'Preview full task', { description: 'Read-only local preview; never sent to the model' });
+            action('done', 'Complete task', { icon: icons.check, confirm: 'Complete this task? This does not start a new conversation.' });
+            action('clear', 'Clear selection', { description: 'Keep the task and its progress unchanged' });
+        }
+        controls.push({ id: 'add', label: 'New task', icon: icons.add, kind: 'text', multiline: true, value: '', confirm: 'Create and select this task?' });
+        controls.push({ id: 'search', label: 'Filter tasks', kind: 'text', value: state.search ?? '' });
+        const matches = tasks.filter((t) => `${t.text} ${t.tag ?? ''}`.toLowerCase().includes((state.search ?? '').toLowerCase()));
+        for (const candidate of matches.slice(0, 200))
+            action(`select:${candidate.id}`, `${candidate.tag ? `[${candidate.tag}] ` : ''}${candidate.text.split('\n')[0]}`, { description: `#${candidate.id} · ${candidate.state}`, confirm: 'Select and start this task for this conversation?' });
+        if (matches.length > 200)
+            body += '\nShowing the first 200 matches; use Filter tasks to narrow the list.';
+    }
+    const footer = [{ text: `${icons.note} ${task ? task.text.split('\n')[0].slice(0, 2000) : 'Pinote · no task'}`, width: config.config.titleWidth }];
+    if (task) {
+        for (const field of fields(config.config, task.agent_notes)) {
+            if (footer.length - 1 >= config.config.maxFields)
+                break;
+            const raw = task.agent_notes[field.name];
+            if (!raw)
+                continue;
+            const link = /^\[([^\n]*)\]\((https?:\/\/[^\s]+)\)$/.exec(raw);
+            const url = link?.[2] ?? (/^https?:\/\/[^\s]+$/.test(raw) ? raw : undefined);
+            const value = link?.[1] ?? raw;
+            const number = url?.match(/github\.com\/[^/]+\/[^/]+\/pull\/(\d+)\/?$/)?.[1] ?? (/^\d+$/.test(value) ? value : undefined);
+            if (field.format.includes('<url>') && !url || field.format.includes('<number>') && !number)
+                continue;
+            const substitutions = { value, url: url ?? '', number: number ?? '' };
+            const rendered = ` · ${field.label ? `${field.label}: ` : ''}${field.format.replace(/<(value|url|number)>/g, (_match, key) => substitutions[key])}`;
+            footer.push({ text: rendered.slice(0, 20_000), ...(field.link && url && url.length <= 2048 ? { url } : {}), width: field.width ?? config.config.fieldWidth });
+        }
+    }
+    const editable = controls.filter((control) => {
+        if (typeof control.value !== 'string' || control.value.length <= 20_000)
+            return true;
+        body = `${control.label} exceeds the editor limit; edit it outside this UI.\n${body}`;
+        return false;
+    });
+    const result = { version: 1, title, body: body.slice(0, 20_000), revision, state, controls: editable, footer };
+    // JSON escaping and expanded footer formats can exceed the host budget even
+    // with bounded row counts. Preserve navigation/filter controls ahead of rows.
+    let shortened = false;
+    while (JSON.stringify(result).length > 240_000) {
+        const row = result.controls.map((control) => control.id.startsWith('select:')).lastIndexOf(true);
+        if (row >= 0) {
+            result.controls.splice(row, 1);
+            shortened = true;
+        }
+        else if (result.footer.length > 1)
+            result.footer.pop();
+        else
+            throw new Error('UI exceeds its display budget; shorten configuration values');
+    }
+    if (shortened)
+        result.body = `More matches omitted to fit the display budget; narrow Filter tasks.\n${result.body}`.slice(0, 20_000);
+    return result;
+}
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: [{ uri: URI, name: 'Pinote', mimeType: MIME }] }));
+server.setRequestHandler(ReadResourceRequestSchema, (request, extra) => serial(async () => {
+    if (request.params.uri !== URI)
+        throw new Error('Unknown resource');
+    const data = await snapshot(context(request.params._meta).state, extra.signal);
+    return { contents: [{ uri: URI, mimeType: MIME, text: JSON.stringify(view(data)) }] };
+}));
+server.setRequestHandler(Action, (request, extra) => serial(async () => {
+    const state = context(request.params._meta).state;
+    const before = await snapshot(state, extra.signal);
+    if (before.revision !== request.params.revision)
+        throw new Error('View changed; refresh before acting');
+    const { action, value } = request.params;
+    if (!view(before).controls.some((c) => c.id === action))
+        throw new Error('Action is not available in this view');
+    const next = { ...state };
+    let draft, preview;
+    if (action.startsWith('screen:'))
+        next.screen = action.slice(7);
+    else if (action.startsWith('field:')) {
+        next.screen = 'field';
+        next.field = action.slice(6);
+    }
+    else if (action === 'search')
+        next.search = z.string().max(256).parse(value);
+    else if (action === 'clear')
+        next.selectedId = null;
+    else if (action === 'continue')
+        draft = before.config.handoffPrompt;
+    else if (action === 'preview')
+        preview = (before.task.text + '\n\n' + JSON.stringify(before.task.agent_notes, null, 2)).slice(0, 20_000);
+    else if (action.startsWith('select:')) {
+        const id = Number(action.slice(7));
+        if (!before.tasks.some((t) => t.id === id))
+            throw new Error('Task no longer selectable');
+        await note(['start', String(id)], extra.signal);
+        next.selectedId = id;
+    }
+    else if (action === 'add') {
+        const task = JSON.parse(await note(['agent', 'add', `--text=${z.string().min(1).parse(value)}`], extra.signal));
+        await note(['start', String(task.id)], extra.signal);
+        next.selectedId = task.id;
+    }
+    else if (action === 'done') {
+        await note(['agent', 'done', String(before.task.id), '--expected-updated-at', before.task.updated_at], extra.signal);
+        next.selectedId = null;
+    }
+    else {
+        const cfg = structuredClone(before.config.config);
+        let handoff = before.config.handoffPrompt, newSession = before.config.newSessionPrompt, policy = before.config.policy;
+        if (action === 'handoffPrompt')
+            handoff = z.string().parse(value);
+        else if (action === 'newSessionPrompt')
+            newSession = z.string().parse(value);
+        else if (action === 'taskOfferPolicy')
+            policy = z.enum(['always', 'github-remote', 'never']).parse(value);
+        else if (['titleWidth', 'fieldWidth', 'maxFields'].includes(action))
+            cfg[action] = z.number().int().parse(value);
+        else {
+            cfg.fields = fields(cfg, before.task?.agent_notes);
+            if (action === 'add-field')
+                cfg.fields.push(defaultFooterField(z.string().parse(value)));
+            else if (action === 'remove-field') {
+                cfg.fields = cfg.fields.filter((f) => f.name !== state.field);
+                next.screen = 'settings';
+            }
+            else {
+                const field = cfg.fields.find((f) => f.name === state.field);
+                if (action === 'link')
+                    field.link = z.boolean().parse(value);
+                else if (action === 'width')
+                    field.width = z.number().int().parse(value);
+                else if (action === 'label' || action === 'format')
+                    field[action] = z.string().parse(value);
+                else
+                    throw new Error('Unknown action');
+            }
+        }
+        extra.signal.throwIfAborted();
+        saveFooterConfig(cfg, before.config.raw, handoff, newSession, policy);
+    }
+    const result = { view: view(await snapshot(next, extra.signal)), ...(draft ? { draft } : {}), ...(preview ? { preview } : {}) };
+    await server.notification({ method: 'notifications/native-ui/changed', params: { uri: URI } });
+    return result;
+}));
+const empty = { type: 'object', properties: {}, additionalProperties: false };
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [
+        { name: 'get_current', description: 'Read the task selected through the native Pinote UI for this conversation. Returns null if unselected.', inputSchema: empty, annotations: { readOnlyHint: true } },
+        { name: 'fields', description: 'Read global footer field definitions before setting task handoff values. Does not edit settings.', inputSchema: empty, annotations: { readOnlyHint: true } },
+        { name: 'tags', description: 'List saved Pinote tags.', inputSchema: empty, annotations: { readOnlyHint: true } },
+        { name: 'update_current', description: 'Merge Markdown handoff fields on the selected task. Read get_current first. Keep handoff notes concise; PR is one GitHub PR URL.', inputSchema: { type: 'object', properties: { expected_updated_at: { type: 'string' }, set: { type: 'object', additionalProperties: { type: 'string' } }, remove: { type: 'array', items: { type: 'string' } } }, required: ['expected_updated_at'], additionalProperties: false } },
+    ] }));
+server.setRequestHandler(CallToolRequestSchema, (request, extra) => serial(async () => {
+    try {
+        const state = context(request.params._meta).state;
+        let result;
+        if (request.params.name === 'get_current')
+            result = await selected(state, extra.signal);
+        else if (request.params.name === 'fields')
+            result = settings().config;
+        else if (request.params.name === 'tags')
+            result = JSON.parse(await note(['agent', 'tags'], extra.signal));
+        else if (request.params.name === 'update_current') {
+            const args = z.object({ expected_updated_at: z.string(), set: z.record(z.string()).default({}), remove: z.array(z.string()).default([]) }).strict().parse(request.params.arguments);
+            const task = await selected(state, extra.signal);
+            if (!task)
+                throw new Error('No task is selected');
+            result = JSON.parse(await note(['agent', 'update', String(task.id), '--expected-updated-at', args.expected_updated_at, '--set-json', JSON.stringify(args.set), ...args.remove.map((key) => `--remove=${key}`)], extra.signal));
+            await server.notification({ method: 'notifications/native-ui/changed', params: { uri: URI } });
+        }
+        else
+            throw new Error('Unknown tool');
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    }
+    catch (error) {
+        return { isError: true, content: [{ type: 'text', text: String(error) }] };
+    }
+}));
+await server.connect(new StdioServerTransport());

package/footer-config.ts

@@ -1,4 +1,4 @@
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "./config-path.ts";
 import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -97,7 +97,8 @@ export function loadFooterConfig(warn: (message: string) => void): FooterConfig
 
 // Synchronous compare-and-replace: reject edits made while the settings dialog was open,
 // preserve unrelated keys, and never leave partial JSON behind.
-export function saveFooterConfig(config: FooterConfig, expectedRaw: string | null, handoffPrompt?: string, newSessionPrompt?: string) {
+export function saveFooterConfig(config: FooterConfig, expectedRaw: string | null, handoffPrompt?: string, newSessionPrompt?: string, taskOfferPolicy?: string) {
+  if (taskOfferPolicy !== undefined && !["always", "github-remote", "never"].includes(taskOfferPolicy)) throw new Error("Invalid taskOfferPolicy");
   const checked = parseFooterConfig({ footer: config });
   const prompts = {
     ...(handoffPrompt === undefined ? {} : { handoffPrompt: parseHandoffPrompt(handoffPrompt) }),
@@ -117,7 +118,7 @@ export function saveFooterConfig(config: FooterConfig, expectedRaw: string | nul
     if (lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink()) throw new Error("pi-note.json is a symlink. Edit its target manually rather than replacing the link.");
     const root = expectedRaw === null ? {} : JSON.parse(expectedRaw);
     if (!object(root)) throw new Error("Invalid pi-note configuration; expected an object.");
-    raw = `${JSON.stringify({ ...root, ...prompts, footer: checked }, null, 2)}\n`;
+    raw = `${JSON.stringify({ ...root, ...prompts, ...(taskOfferPolicy === undefined ? {} : { taskOfferPolicy }), footer: checked }, null, 2)}\n`;
     writeFileSync(temp, raw, { flag: "wx", mode: 0o600 });
     renameSync(temp, path);
   } finally { rmSync(temp, { force: true }); closeSync(descriptor); rmSync(lock, { force: true }); }

package/index.ts

@@ -169,6 +169,7 @@ export default function (pi: ExtensionAPI) {
   let epoch = 0;
   let refreshSerial = 0;
   let pending: symbol | undefined;
+  let menuPending: symbol | undefined;
   let previewPending = false;
   let setupAbort: AbortController | undefined;
   let activeContext: ExtensionContext | undefined;
@@ -318,7 +319,7 @@ export default function (pi: ExtensionAPI) {
     }
   };
   const preview = async (ctx: ExtensionContext, requestSignal?: AbortSignal): Promise<boolean> => {
-    if (!ctx.hasUI || ctx.mode !== "tui" || pending || previewPending || !validId(selectedId)) return false;
+    if (!ctx.hasUI || ctx.mode !== "tui" || pending || menuPending || previewPending || !validId(selectedId)) return false;
     const generation = epoch;
     const branch = branchEpoch;
     const id = selectedId;
@@ -346,7 +347,7 @@ export default function (pi: ExtensionAPI) {
     }
   };
   const dispatchCompletion = (ctx: ExtensionContext, displayed: Task, selection: string): Promise<boolean> => {
-    if (!ctx.isIdle() || pending || completionDispatch) return Promise.resolve(false);
+    if (!ctx.isIdle() || pending || menuPending || completionDispatch) return Promise.resolve(false);
     const token = `${selection}:${randomBytes(8).toString("hex")}`;
     return new Promise((resolve) => {
       const finish = (accepted: boolean) => {
@@ -367,7 +368,7 @@ export default function (pi: ExtensionAPI) {
     const token = args.trim();
     const request = token ? completionDispatch : undefined;
     if (token && (request?.token !== token || request.selection !== `${runtimeToken}:${epoch}:${branchEpoch}:${selectedId}`)) return;
-    if (!alive || !ctx.hasUI || ctx.mode !== "tui" || !ctx.isIdle() || pending || setupAbort || !validId(selectedId)) {
+    if (!alive || !ctx.hasUI || ctx.mode !== "tui" || !ctx.isIdle() || pending || menuPending || setupAbort || !validId(selectedId)) {
       request?.finish(false);
       if (ctx.hasUI) ctx.ui.notify("Select a task and wait until Pi is idle and the Pinote operation has finished.", "warning");
       return;
@@ -459,6 +460,7 @@ export default function (pi: ExtensionAPI) {
     if (!alive || generation !== epoch) return;
     // Keep the setup lock until its aborted subprocess has actually settled.
     if (!setupAbort) pending = undefined;
+    menuPending = undefined;
     await checkCLI(ctx, true);
     if (!alive || generation !== epoch) return;
     if (suggestion) previewBridge?.setSuggestion((choice) => respondToSuggestion(choice, ctx));
@@ -522,7 +524,7 @@ export default function (pi: ExtensionAPI) {
 
   const installCLI = async (upgrade: boolean, ctx: ExtensionCommandContext) => {
     if (!ctx.hasUI || ctx.mode !== "tui") return;
-    if (pending || !ctx.isIdle()) {
+    if (pending || menuPending || !ctx.isIdle()) {
       ctx.ui.notify("Wait until Pi is idle and the pinote operation has finished.", "warning");
       return;
     }
@@ -563,16 +565,18 @@ export default function (pi: ExtensionAPI) {
         return;
       }
       if (token) { ctx.ui.notify("Usage: /pi-note", "warning"); return; }
-      if (pending || !ctx.isIdle()) {
-        ctx.ui.notify("Wait until Pi is idle and the pinote operation has finished.", "warning");
+      if (pending || menuPending) {
+        ctx.ui.notify("Wait until the pinote operation has finished.", "warning");
         return;
       }
       const operation = Symbol();
-      pending = operation;
+      menuPending = operation;
       const generation = epoch;
       const branch = branchEpoch;
       const currentSession = () => alive && generation === epoch;
-      const canAct = () => currentSession() && ctx.isIdle() && branch === branchEpoch;
+      // Menus, task selection and preference edits do not interrupt the agent.
+      // Completion and CLI setup retain their own idle-only guards.
+      const canAct = () => currentSession() && branch === branchEpoch && menuPending === operation;
       try {
         await checkCLI(ctx);
         if (!canAct()) return;
@@ -633,7 +637,7 @@ export default function (pi: ExtensionAPI) {
             if (!canAct() || edited === undefined) return;
             if (edited === "tasks") { settings = false; continue; }
             if (!options.some((option) => option.result === edited)) return;
-            if (pending === operation) pending = undefined;
+            if (menuPending === operation) menuPending = undefined;
             if (edited === "preview") {
               if (!await preview(ctx)) ctx.ui.notify("The task is no longer available for preview.", "warning");
             } else if (edited === "done") await completeSelected("", ctx, current ?? undefined);
@@ -649,7 +653,7 @@ export default function (pi: ExtensionAPI) {
           if (!action || !canAct()) return;
           if (action === "Settings") { settings = true; continue; }
           if (action === "Done" && current) {
-            if (pending === operation) pending = undefined;
+            if (menuPending === operation) menuPending = undefined;
             await completeSelected("", ctx, current);
             return;
           }
@@ -667,6 +671,11 @@ export default function (pi: ExtensionAPI) {
             id = choice;
           } else return;
           const handoff = handoffPrompt();
+          if (pending) {
+            ctx.ui.notify("Wait until the pinote operation has finished.", "warning");
+            return;
+          }
+          pending = operation;
           refreshSerial++;
           const chosen = await startTask(id, canAct);
           if (!chosen || !canAct()) return;
@@ -679,6 +688,7 @@ export default function (pi: ExtensionAPI) {
         if (currentSession()) ctx.ui.notify(`Pinote: ${clean(error instanceof Error ? error.message : String(error))}`, "error");
       } finally {
         if (pending === operation) pending = undefined;
+        if (menuPending === operation) menuPending = undefined;
         if (currentSession()) await refresh(ctx);
       }
     },
@@ -755,7 +765,7 @@ export default function (pi: ExtensionAPI) {
       clearSuggestion(ctx);
       return true;
     }
-    if (pending || setupAbort) return false;
+    if (pending || menuPending || setupAbort) return false;
     const generation = epoch;
     const branch = branchEpoch;
     const operation = Symbol();
@@ -804,7 +814,7 @@ export default function (pi: ExtensionAPI) {
       const current = await selected(ctx, signal);
       if (!alive || generation !== epoch || branch !== branchEpoch) throw new Error("Pinote operation cancelled: the session changed.");
       if (current || selectedId !== null) throw new Error("A task is already selected; keep it unless the user asks to switch.");
-      if (pending || setupAbort) throw new Error("A pinote operation is already open. Retry after it finishes.");
+      if (pending || menuPending || setupAbort) throw new Error("A pinote operation is already open. Retry after it finishes.");
       const result = (status: string) => ({ content: [{ type: "text" as const, text: JSON.stringify({ status }) }], details: { status } });
       suggestion = { text: params.text, ...(params.tag === undefined ? {} : { tag: params.tag.trim() }) };
       saveSuggestion();
@@ -834,7 +844,7 @@ export default function (pi: ExtensionAPI) {
       const generation = epoch;
       const branch = branchEpoch;
       if (params.select !== true) return toolResult(await writeTask(ctx, signal, argv, undefined, "0.4.0"));
-      if (pending) throw new Error("A pinote operation is already open. Retry after it finishes.");
+      if (pending || menuPending) throw new Error("A pinote operation is already open. Retry after it finishes.");
       const operation = Symbol();
       const previousSelection = selectedId;
       pending = operation;

package/mcp/README.md

@@ -0,0 +1,95 @@
+# Pinote native UI over MCP
+
+An opt-in alternative to the Pinote-specific Pi extension. Pinote serves the task
+picker, settings forms, previews, footer data, and action validation through MCP;
+the generic [gateway UI host](https://github.com/kvidzibo/mcp-session-gateway)
+only renders and routes them. No model turn is needed for UI actions.
+
+This uses the gateway's **private native UI v1 protocol**, not browser MCP Apps or
+the built-in Pi MCP resource renderer. Use gateway 0.7.0+ with its Pi adapter.
+
+## Setup
+
+Requires Node.js 22.19+, Python 3.11+, and `note` 0.4.0+. From the Pinote checkout:
+
+```bash
+uv sync --locked
+npm --prefix pi ci --ignore-scripts
+npm --prefix pi run build:mcp
+```
+
+Add a service to the gateway config (use absolute paths):
+
+```json
+{
+  "servers": {
+    "pinote": {
+      "command": "node",
+      "args": ["/absolute/path/to/pinote/pi/dist-mcp/mcp/server.js"],
+      "env": { "PINOTE_NOTE_COMMAND": "/absolute/path/to/pinote/.venv/bin/note" }
+    }
+  }
+}
+```
+
+Then launch the gateway's generic Pi adapter and run `/gateway-ui pinote`.
+Do not also load `pi/index.ts` for this workflow. Nothing is automatically
+installed, activated, or migrated; keep the existing integration until you approve
+the switch. To test `/reload`, reload only a disposable session/profile first.
+
+The service shares the existing database and `pi-note.json`. `PINOTE_NOTE_COMMAND`
+selects an executable, not a shell command. Without it, `note` must be on PATH.
+Explicitly pass `PI_CODING_AGENT_DIR`, `XDG_DATA_HOME`, and `XDG_STATE_HOME` in service
+`env` when using overrides or disposable data. Defaults otherwise refer to your
+normal personal data. No desktop notifications are sent.
+
+## Use
+
+- **Tasks:** filter, select/start, create/select, clear selection, complete, preview,
+  and request insertion of the task prompt. Selecting a task asks for confirmation.
+- **Settings:** edit prompts, task-offer policy, footer limits, and field definitions
+  (label, link, format, width). Enter text as JSON strings (`\n` for line breaks)
+  so whitespace round-trips exactly. Saves are confirmed, validated, and atomic; concurrent
+  edits are rejected and unrelated settings are preserved. Invalid configuration
+  fails closed; repair it manually rather than replacing it with defaults.
+- **Footer:** selected task plus configured fields; safe HTTP(S) links are clickable.
+  Menu actions are keyboard-accessible, not footer icon buttons.
+- **Agent:** `get_current`, `update_current`, `fields`, and `tags` are available through
+  gateway tool discovery. They use the same host-supplied selection as the UI.
+  UI actions and settings writes are not advertised as model tools.
+
+The host owns durable conversation/branch state; the service does not store a
+second selection database. Reload/reconnect restores saved state, separate sessions
+in one folder stay independent, and a new conversation starts unselected. Pi must
+have saved the session for resume persistence. Existing extension selections are
+not imported. Changing the gateway config path or service name starts a separate
+selection namespace.
+
+## Initial-version limits
+
+This is a working alternative, **not full parity with the old extension**. It does
+not offer agent task suggestions, retag/edit existing tasks, install/upgrade the
+CLI, automatically retain selection on `/new`, reset conversations on completion,
+or provide clickable footer actions. Task-offer policy and new-session prompt can
+be edited for compatibility with the existing extension, but this host does not
+yet implement their automation. Continue requests a separately confirmed draft;
+it never overwrites existing editor text or submits a prompt. Previews are plain
+text/Markdown source, limited to 20,000 characters; the task list shows at most 200
+filtered matches (fewer if the serialized display budget is reached). Use the CLI for full text and unsupported task operations.
+
+Changes through this service notify the host. External CLI/GTK/config changes need
+Ctrl+R or reopening the app. Failed actions are never retried automatically: a
+write might have committed before an interruption. Read fresh state before retrying.
+Trusted services/agents have ordinary OS permissions; UI-only routing is not a
+secrecy or authorization boundary.
+
+## Validation
+
+```bash
+npm --prefix pi test
+```
+
+The MCP integration test runs the real stdio server and CLI against temporary
+storage, including settings conflicts, host selection isolation, handoff updates,
+completion, and reconnect. Visual validation must use Xvfb, private D-Bus, and
+explicit temporary service data/settings paths.

package/mcp/server.ts

@@ -0,0 +1,231 @@
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFileSync } from 'node:fs';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { defaultFooterField, defaultHandoffPrompt, defaultNewSessionPrompt, effectiveFooterFields, parseFooterConfig, parseHandoffPrompt, parseNewSessionPrompt, readFooterDocument, saveFooterConfig } from '../footer-config.ts';
+
+const URI = 'pinote://ui';
+const MIME = 'application/vnd.mcp-native-ui+json';
+const CONTEXT = 'native-ui/context';
+const exec = promisify(execFile);
+const noteCommand = process.env.PINOTE_NOTE_COMMAND || 'note';
+const icons = Object.fromEntries(['add', 'check', 'note'].map((name) => [name, readFileSync(new URL(`../icons/${name}.txt`, import.meta.url), 'utf8').trim()]));
+const Context = z.object({ conversationId: z.string().min(1).max(256), state: z.object({
+  selectedId: z.number().int().positive().safe().nullable().optional(), screen: z.enum(['tasks', 'settings', 'field']).optional(),
+  field: z.string().refine((value) => [...value].length <= 64, 'Field name exceeds 64 code points').optional(), search: z.string().max(256).optional(),
+}).default({}) });
+type State = z.infer<typeof Context>['state'];
+type Task = { id: number; text: string; state: string; tag: string | null; updated_at: string; agent_notes: Record<string, string> };
+type Scalar = string | number | boolean | null;
+type Control = { id: string; label: string; kind: 'action' | 'text' | 'number' | 'toggle' | 'select'; value?: Scalar; icon?: string; description?: string; multiline?: boolean; confirm?: string; options?: { label: string; value: Scalar }[] };
+const Action = z.object({ method: z.literal('native-ui/action'), params: z.object({
+  uri: z.literal(URI), revision: z.string().min(1).max(256), action: z.string().min(1).max(256),
+  value: z.union([z.string().max(20_000), z.number().finite(), z.boolean(), z.null()]).optional(), _meta: z.record(z.unknown()).optional(),
+}) });
+const server = new Server({ name: 'pinote', version: '0.19.0' }, { capabilities: { tools: {}, resources: {}, experimental: { 'native-ui-v1': {} } } });
+// Serialize complete read/check/write cycles even when a host sends parallel calls.
+let queue = Promise.resolve();
+function serial<T>(run: () => Promise<T>): Promise<T> {
+  const result = queue.then(run);
+  queue = result.then(() => {}, () => {});
+  return result;
+}
+function context(meta: Record<string, unknown> | undefined) { return Context.parse(meta?.[CONTEXT]); }
+async function note(args: string[], signal: AbortSignal): Promise<string> {
+  signal.throwIfAborted();
+  const options = { signal, timeout: 10_000, maxBuffer: 4 * 1024 * 1024 };
+  const version = (await exec(noteCommand, ['--version'], options)).stdout.trim();
+  const match = /^pinote (\d+)\.(\d+)\.(\d+)$/.exec(version);
+  if (!match || Number(match[1]) === 0 && Number(match[2]) < 4) throw new Error('Pinote MCP requires note 0.4.0+');
+  return (await exec(noteCommand, ['--no-notify', ...args], options)).stdout;
+}
+async function selected(state: State, signal: AbortSignal): Promise<Task | null> {
+  if (!state.selectedId) return null;
+  const task: Task | null = JSON.parse(await note(['agent', 'get', String(state.selectedId)], signal));
+  return task && ['active', 'in_progress'].includes(task.state) ? task : null;
+}
+function fields(config: ReturnType<typeof readFooterDocument>['config'], notes?: Record<string, string>) {
+  // Legacy Bar values are arbitrary task text, not validated field definitions.
+  return effectiveFooterFields(config, notes).flatMap((field) => {
+    try { return parseFooterConfig({ footer: { fields: [field] } }).fields!; }
+    catch { return []; }
+  }).slice(0, 64);
+}
+function settings() {
+  const document = readFooterDocument();
+  const root = document.raw === null ? {} : JSON.parse(document.raw);
+  const handoffPrompt = 'handoffPrompt' in root ? parseHandoffPrompt(root.handoffPrompt) : defaultHandoffPrompt;
+  const newSessionPrompt = 'newSessionPrompt' in root ? parseNewSessionPrompt(root.newSessionPrompt) : defaultNewSessionPrompt;
+  const policy = Object.hasOwn(root, 'taskOfferPolicy') ? root.taskOfferPolicy : 'always';
+  if (!['always', 'github-remote', 'never'].includes(policy)) throw new Error('Invalid taskOfferPolicy in pi-note.json');
+  return { ...document, handoffPrompt, newSessionPrompt, policy };
+}
+async function snapshot(state: State, signal: AbortSignal) {
+  const tasks: Task[] = JSON.parse(await note(['list', '--json'], signal));
+  const task = await selected(state, signal);
+  const config = settings();
+  state = { ...state, selectedId: task?.id ?? null };
+  if (state.screen === 'field' && !fields(config.config, task?.agent_notes).some((f) => f.name === state.field)) state.screen = 'settings';
+  const revision = createHash('sha256').update(JSON.stringify({ state, tasks, task, raw: config.raw })).digest('hex');
+  return { state, tasks, task, config, revision };
+}
+type Snapshot = Awaited<ReturnType<typeof snapshot>>;
+function view(data: Snapshot) {
+  const { tasks, task, config, revision } = data;
+  const state = Context.parse({ conversationId: 'outgoing-state', state: { ...data.state, selectedId: task?.id ?? null } }).state;
+  const controls: Control[] = [];
+  const action = (id: string, label: string, extra: Partial<Control> = {}) => controls.push({ id, label: label.slice(0, 2000), kind: 'action', ...extra });
+  let title = 'Pinote · Tasks';
+  let body = task ? task.text : 'Select a task or create one. No task is selected for this conversation.';
+  action('screen:tasks', 'Tasks', { icon: icons.note });
+  action('screen:settings', 'Settings', { description: 'Global prompts, task offers, and footer fields' });
+  if (state.screen === 'settings') {
+    title = 'Pinote · Settings'; body = 'Personal pi-note.json · changes save after confirmation';
+    for (const [id, label, value] of [['handoffPrompt', 'Task prompt', config.handoffPrompt], ['newSessionPrompt', 'New session prompt', config.newSessionPrompt]] as const) {
+      controls.push({ id, label, value, kind: 'text', multiline: true, confirm: 'Save this global prompt?' });
+    }
+    controls.push({ id: 'taskOfferPolicy', label: 'Task offers', kind: 'select', value: config.policy, options: ['always', 'github-remote', 'never'].map((value) => ({ label: value, value })), confirm: 'Save this global task-offer policy?' });
+    for (const key of ['titleWidth', 'fieldWidth', 'maxFields'] as const) controls.push({ id: key, label: key, kind: 'number', value: config.config[key], confirm: 'Save this global footer setting?' });
+    controls.push({ id: 'add-field', label: 'Add field', icon: icons.add, kind: 'text', value: '', confirm: 'Add this global footer field?' });
+    fields(config.config, task?.agent_notes).forEach((field) => action(`field:${field.name}`, field.name, { description: `${field.label || '(no label)'} · ${field.format}` }));
+  } else if (state.screen === 'field') {
+    const field = fields(config.config, task?.agent_notes).find((f) => f.name === state.field);
+    if (!field) throw new Error('Field no longer exists; open Settings again');
+    title = `Pinote · ${field.name}`; body = 'Global footer display definition; task values are unchanged.';
+    controls.push({ id: 'label', label: 'Label', kind: 'text', value: field.label, confirm: 'Save this global field label?' });
+    controls.push({ id: 'format', label: 'Format', kind: 'text', value: field.format, description: '<value>, <url>, <number>', confirm: 'Save this global field format?' });
+    controls.push({ id: 'width', label: 'Width', kind: 'number', value: field.width ?? config.config.fieldWidth, confirm: 'Save this global field width?' });
+    controls.push({ id: 'link', label: 'Link', kind: 'toggle', value: field.link, confirm: 'Change this global link setting?' });
+    action('remove-field', 'Remove field', { confirm: 'Remove this global display definition? Task values are retained.' });
+  } else {
+    if (task) {
+      if (config.handoffPrompt.length <= 20_000) action('continue', 'Continue', { description: 'Request insertion of the task prompt; never submit it' });
+      action('preview', 'Preview full task', { description: 'Read-only local preview; never sent to the model' });
+      action('done', 'Complete task', { icon: icons.check, confirm: 'Complete this task? This does not start a new conversation.' });
+      action('clear', 'Clear selection', { description: 'Keep the task and its progress unchanged' });
+    }
+    controls.push({ id: 'add', label: 'New task', icon: icons.add, kind: 'text', multiline: true, value: '', confirm: 'Create and select this task?' });
+    controls.push({ id: 'search', label: 'Filter tasks', kind: 'text', value: state.search ?? '' });
+    const matches = tasks.filter((t) => `${t.text} ${t.tag ?? ''}`.toLowerCase().includes((state.search ?? '').toLowerCase()));
+    for (const candidate of matches.slice(0, 200)) action(`select:${candidate.id}`, `${candidate.tag ? `[${candidate.tag}] ` : ''}${candidate.text.split('\n')[0]}`, { description: `#${candidate.id} · ${candidate.state}`, confirm: 'Select and start this task for this conversation?' });
+    if (matches.length > 200) body += '\nShowing the first 200 matches; use Filter tasks to narrow the list.';
+  }
+  const footer: { text: string; url?: string; width?: number }[] = [{ text: `${icons.note} ${task ? task.text.split('\n')[0].slice(0, 2000) : 'Pinote · no task'}`, width: config.config.titleWidth }];
+  if (task) {
+    for (const field of fields(config.config, task.agent_notes)) {
+      if (footer.length - 1 >= config.config.maxFields) break;
+      const raw = task.agent_notes[field.name];
+      if (!raw) continue;
+      const link = /^\[([^\n]*)\]\((https?:\/\/[^\s]+)\)$/.exec(raw);
+      const url = link?.[2] ?? (/^https?:\/\/[^\s]+$/.test(raw) ? raw : undefined);
+      const value = link?.[1] ?? raw;
+      const number = url?.match(/github\.com\/[^/]+\/[^/]+\/pull\/(\d+)\/?$/)?.[1] ?? (/^\d+$/.test(value) ? value : undefined);
+      if (field.format.includes('<url>') && !url || field.format.includes('<number>') && !number) continue;
+      const substitutions: Record<string, string> = { value, url: url ?? '', number: number ?? '' };
+      const rendered = ` · ${field.label ? `${field.label}: ` : ''}${field.format.replace(/<(value|url|number)>/g, (_match, key: string) => substitutions[key])}`;
+      footer.push({ text: rendered.slice(0, 20_000), ...(field.link && url && url.length <= 2048 ? { url } : {}), width: field.width ?? config.config.fieldWidth });
+    }
+  }
+  const editable = controls.filter((control) => {
+    if (typeof control.value !== 'string' || control.value.length <= 20_000) return true;
+    body = `${control.label} exceeds the editor limit; edit it outside this UI.\n${body}`;
+    return false;
+  });
+  const result = { version: 1, title, body: body.slice(0, 20_000), revision, state, controls: editable, footer };
+  // JSON escaping and expanded footer formats can exceed the host budget even
+  // with bounded row counts. Preserve navigation/filter controls ahead of rows.
+  let shortened = false;
+  while (JSON.stringify(result).length > 240_000) {
+    const row = result.controls.map((control) => control.id.startsWith('select:')).lastIndexOf(true);
+    if (row >= 0) { result.controls.splice(row, 1); shortened = true; }
+    else if (result.footer.length > 1) result.footer.pop();
+    else throw new Error('UI exceeds its display budget; shorten configuration values');
+  }
+  if (shortened) result.body = `More matches omitted to fit the display budget; narrow Filter tasks.\n${result.body}`.slice(0, 20_000);
+  return result;
+}
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: [{ uri: URI, name: 'Pinote', mimeType: MIME }] }));
+server.setRequestHandler(ReadResourceRequestSchema, (request, extra) => serial(async () => {
+  if (request.params.uri !== URI) throw new Error('Unknown resource');
+  const data = await snapshot(context(request.params._meta).state, extra.signal);
+  return { contents: [{ uri: URI, mimeType: MIME, text: JSON.stringify(view(data)) }] };
+}));
+server.setRequestHandler(Action, (request, extra) => serial(async () => {
+  const state = context(request.params._meta).state;
+  const before = await snapshot(state, extra.signal);
+  if (before.revision !== request.params.revision) throw new Error('View changed; refresh before acting');
+  const { action, value } = request.params;
+  if (!view(before).controls.some((c) => c.id === action)) throw new Error('Action is not available in this view');
+  const next: State = { ...state };
+  let draft: string | undefined, preview: string | undefined;
+  if (action.startsWith('screen:')) next.screen = action.slice(7) as State['screen'];
+  else if (action.startsWith('field:')) { next.screen = 'field'; next.field = action.slice(6); }
+  else if (action === 'search') next.search = z.string().max(256).parse(value);
+  else if (action === 'clear') next.selectedId = null;
+  else if (action === 'continue') draft = before.config.handoffPrompt;
+  else if (action === 'preview') preview = (before.task!.text + '\n\n' + JSON.stringify(before.task!.agent_notes, null, 2)).slice(0, 20_000);
+  else if (action.startsWith('select:')) {
+    const id = Number(action.slice(7));
+    if (!before.tasks.some((t) => t.id === id)) throw new Error('Task no longer selectable');
+    await note(['start', String(id)], extra.signal); next.selectedId = id;
+  } else if (action === 'add') {
+    const task: Task = JSON.parse(await note(['agent', 'add', `--text=${z.string().min(1).parse(value)}`], extra.signal));
+    await note(['start', String(task.id)], extra.signal); next.selectedId = task.id;
+  } else if (action === 'done') {
+    await note(['agent', 'done', String(before.task!.id), '--expected-updated-at', before.task!.updated_at], extra.signal);
+    next.selectedId = null;
+  } else {
+    const cfg = structuredClone(before.config.config);
+    let handoff = before.config.handoffPrompt, newSession = before.config.newSessionPrompt, policy = before.config.policy;
+    if (action === 'handoffPrompt') handoff = z.string().parse(value);
+    else if (action === 'newSessionPrompt') newSession = z.string().parse(value);
+    else if (action === 'taskOfferPolicy') policy = z.enum(['always', 'github-remote', 'never']).parse(value);
+    else if (['titleWidth', 'fieldWidth', 'maxFields'].includes(action)) cfg[action as 'titleWidth'] = z.number().int().parse(value);
+    else {
+      cfg.fields = fields(cfg, before.task?.agent_notes);
+      if (action === 'add-field') cfg.fields.push(defaultFooterField(z.string().parse(value)));
+      else if (action === 'remove-field') { cfg.fields = cfg.fields.filter((f) => f.name !== state.field); next.screen = 'settings'; }
+      else {
+        const field = cfg.fields.find((f) => f.name === state.field)!;
+        if (action === 'link') field.link = z.boolean().parse(value);
+        else if (action === 'width') field.width = z.number().int().parse(value);
+        else if (action === 'label' || action === 'format') field[action] = z.string().parse(value);
+        else throw new Error('Unknown action');
+      }
+    }
+    extra.signal.throwIfAborted();
+    saveFooterConfig(cfg, before.config.raw, handoff, newSession, policy);
+  }
+  const result = { view: view(await snapshot(next, extra.signal)), ...(draft ? { draft } : {}), ...(preview ? { preview } : {}) };
+  await server.notification({ method: 'notifications/native-ui/changed', params: { uri: URI } });
+  return result;
+}));
+const empty = { type: 'object' as const, properties: {}, additionalProperties: false };
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [
+  { name: 'get_current', description: 'Read the task selected through the native Pinote UI for this conversation. Returns null if unselected.', inputSchema: empty, annotations: { readOnlyHint: true } },
+  { name: 'fields', description: 'Read global footer field definitions before setting task handoff values. Does not edit settings.', inputSchema: empty, annotations: { readOnlyHint: true } },
+  { name: 'tags', description: 'List saved Pinote tags.', inputSchema: empty, annotations: { readOnlyHint: true } },
+  { name: 'update_current', description: 'Merge Markdown handoff fields on the selected task. Read get_current first. Keep handoff notes concise; PR is one GitHub PR URL.', inputSchema: { type: 'object' as const, properties: { expected_updated_at: { type: 'string' }, set: { type: 'object', additionalProperties: { type: 'string' } }, remove: { type: 'array', items: { type: 'string' } } }, required: ['expected_updated_at'], additionalProperties: false } },
+] }));
+server.setRequestHandler(CallToolRequestSchema, (request, extra) => serial(async () => {
+  try {
+    const state = context(request.params._meta).state;
+    let result: unknown;
+    if (request.params.name === 'get_current') result = await selected(state, extra.signal);
+    else if (request.params.name === 'fields') result = settings().config;
+    else if (request.params.name === 'tags') result = JSON.parse(await note(['agent', 'tags'], extra.signal));
+    else if (request.params.name === 'update_current') {
+      const args = z.object({ expected_updated_at: z.string(), set: z.record(z.string()).default({}), remove: z.array(z.string()).default([]) }).strict().parse(request.params.arguments);
+      const task = await selected(state, extra.signal);
+      if (!task) throw new Error('No task is selected');
+      result = JSON.parse(await note(['agent', 'update', String(task.id), '--expected-updated-at', args.expected_updated_at, '--set-json', JSON.stringify(args.set), ...args.remove.map((key) => `--remove=${key}`)], extra.signal));
+      await server.notification({ method: 'notifications/native-ui/changed', params: { uri: URI } });
+    } else throw new Error('Unknown tool');
+    return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+  } catch (error) { return { isError: true, content: [{ type: 'text', text: String(error) }] }; }
+}));
+await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-note",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Persistent pinote tasks, Markdown handoffs, and task status for Pi",
   "license": "MIT",
   "type": "module",
@@ -30,6 +30,9 @@
     "footer-status.ts",
     "footer-links.ts",
     "footer-config.ts",
+    "config-path.ts",
+    "mcp",
+    "dist-mcp",
     "footer-settings.ts",
     "task-picker.ts",
     "task-suggestion.ts",
@@ -47,10 +50,13 @@
     ]
   },
   "scripts": {
+    "build:mcp": "tsc -p tsconfig.mcp.json && node -e \"require('node:fs').cpSync('icons', 'dist-mcp/icons', { recursive: true })\"",
+    "prepack": "npm run build:mcp",
+    "mcp": "node dist-mcp/mcp/server.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": "npm run check && npm run test:unit && npm run test:load"
+    "test": "npm run build:mcp && npm run check && npm run test:unit && npm run test:load"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
@@ -63,5 +69,9 @@
     "@types/node": "22.20.3",
     "typebox": "1.3.7",
     "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^3.25.76"
   }
 }