pi-note 0.18.1 → 0.20.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+**.

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,377 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+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', 'cross', 'note'].map((name) => [name, readFileSync(new URL(`../icons/${name}.txt`, import.meta.url), 'utf8').trim()]));
+const Proposal = z.object({ id: z.string().uuid(), text: z.string().min(1).max(4000), tag: z.string().trim().min(1).max(64).optional() }).strict();
+const Context = z.object({ conversationId: z.string().min(1).max(256), contextId: z.string().min(1).max(256).optional(), state: z.object({
+        proposal: Proposal.nullable().optional(),
+        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.20.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]); }
+// Consent receipts are not selection storage. Tombstones prevent old branch state
+// or a reconnect from creating the same proposed task twice, even after a crash.
+const receiptDir = join(process.env.XDG_STATE_HOME || join(homedir(), '.local/state'), 'pinote/mcp-proposals');
+async function consumed(id) {
+    try {
+        await fs.lstat(join(receiptDir, id));
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function consume(id) {
+    await fs.mkdir(receiptDir, { recursive: true, mode: 0o700 });
+    const stat = await fs.lstat(receiptDir);
+    if (!stat.isDirectory() || stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o700)
+        throw new Error('Unsafe proposal receipt directory');
+    const file = await fs.open(join(receiptDir, id), 'wx', 0o600);
+    try {
+        await file.writeFile('consumed\n');
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+}
+function boundedState(state) {
+    if (JSON.stringify(state).length > 8192)
+        throw new Error('Proposal exceeds the host state budget; shorten it');
+    return state;
+}
+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, proposal: task || state.proposal && await consumed(state.proposal.id) ? null : state.proposal ?? null };
+    if (state.screen === 'field' && !fields(config.config, task?.agent_notes).some((f) => f.name === state.field))
+        state.screen = 'settings';
+    state = Context.parse({ conversationId: 'canonical', state }).state;
+    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.';
+    // Footer actions remain valid on every screen, including Settings.
+    if (task) {
+        action('preview', 'Preview full task', { description: 'Display only; never sent to the model' });
+        action('done', 'Complete task', { icon: icons.check });
+    }
+    else if (state.proposal) {
+        action('proposal:accept', 'Accept suggestion', { icon: icons.add, description: state.proposal.text });
+        action('proposal:dismiss', 'Dismiss suggestion', { icon: icons.cross });
+    }
+    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('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} `, width: 3 }];
+    if (task) {
+        footer.push({ text: `${icons.check} `, action: 'done', width: 3 });
+        footer.push({ text: `${task.tag ? `[${task.tag}] ` : ''}${task.text.split('\n')[0].slice(0, 2000)}`, action: 'preview', width: config.config.titleWidth });
+    }
+    else if (state.proposal) {
+        footer.push({ text: `${icons.cross} `, action: 'proposal:dismiss', width: 3 }, { text: `${icons.add} `, action: 'proposal:accept', width: 3 });
+        footer.push({ text: `${state.proposal.tag ? `[${state.proposal.tag}] ` : ''}${state.proposal.text.split('\n')[0].slice(0, 2000)}`, width: config.config.titleWidth });
+    }
+    else
+        footer.push({ text: 'Pinote · no task', width: config.config.titleWidth });
+    const titleParts = footer.length;
+    if (task) {
+        for (const field of fields(config.config, task.agent_notes)) {
+            if (footer.length - titleParts >= 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: boundedState(state), retainOnNew: true, 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 = { ...before.state };
+    let draft, preview;
+    if (action === 'proposal:accept' || action === 'proposal:dismiss') {
+        const proposal = before.state.proposal;
+        if (!proposal || before.task)
+            throw new Error('Suggestion no longer available');
+        await consume(proposal.id); // Fail closed before any task mutation; never replay uncertain creation.
+        next.proposal = null;
+        if (action === 'proposal:accept') {
+            const task = JSON.parse(await note(['agent', 'add', `--text=${proposal.text}`, ...(proposal.tag ? [`--tag=${proposal.tag}`] : [])], extra.signal));
+            await note(['start', String(task.id)], extra.signal);
+            next.selectedId = task.id;
+        }
+    }
+    else 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');
+        if (next.proposal)
+            await consume(next.proposal.id);
+        await note(['start', String(id)], extra.signal);
+        next.selectedId = id;
+        next.proposal = null;
+    }
+    else if (action === 'add') {
+        if (next.proposal)
+            await consume(next.proposal.id);
+        next.proposal = null;
+        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: 'propose', description: 'Suggest a task without creating it. Requires no selected task. Show a short action-oriented title, optional details after a blank line, and reuse a saved tag. The user clicks + to create/start/select or dismiss. Replaces an unaccepted suggestion; continue working without asking again. Never creates a task before a user action.', inputSchema: { type: 'object', properties: { text: { type: 'string', minLength: 1, maxLength: 4000 }, tag: { type: 'string', minLength: 1, maxLength: 64 } }, required: ['text'], additionalProperties: false } },
+        { 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, outgoing;
+        if (request.params.name === 'propose') {
+            if (await selected(state, extra.signal))
+                throw new Error('A task is already selected');
+            const args = Proposal.omit({ id: true }).parse(request.params.arguments);
+            if (!args.text.trim())
+                throw new Error('Task text must not be blank');
+            outgoing = boundedState({ ...state, selectedId: null, proposal: { ...args, id: randomUUID() } });
+            if (state.proposal && !await consumed(state.proposal.id))
+                await consume(state.proposal.id);
+            result = { status: 'Suggested; user can accept (+) or dismiss. Continue working without asking again.' };
+        }
+        else 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) }], ...(outgoing ? { _meta: { 'native-ui/state': outgoing } } : {}) };
+    }
+    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/mcp/README.md

@@ -0,0 +1,112 @@
+# 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.12.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 open
+`/gateway` → Services → pinote → Open app.
+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.
+  The title previews the task; **✔** completes it and clears the selection without
+  resetting the conversation or editor. Suggestions show **✖ / ✚** to dismiss or
+  create/start/select. These use the gateway's generic footer actions, not a Pinote
+  extension or private handler. Install the gateway's Kitty protocol handler as
+  described in its native UI documentation; app menus remain the keyboard fallback.
+- **Agent:** `propose`, `get_current`, `update_current`, `fields`, and `tags` are
+  available through gateway tool discovery. `propose` returns opaque UI state;
+  it does not create a task. It replaces an unaccepted suggestion only when no task
+  is selected. Text is limited to 4,000 characters and the host's 8 KiB state budget.
+  Acceptance/dismissal consumes a durable receipt before mutation, so old links,
+  branch restores and reconnects cannot replay consent. An interrupted acceptance
+  may have created a task: inspect the task list, never blindly propose it again. 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 `/new` retains the current selection or pending
+suggestion. An unrelated fresh launch starts unselected. The stable service
+context is separate from both the Pi conversation ID and gateway process UUID. 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 retag/edit existing tasks or install/upgrade the CLI. Completion intentionally
+does not reset conversations. 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 display-only transcript entries (never model context), showing 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.
+
+Consent receipts live under `$XDG_STATE_HOME/pinote/mcp-proposals` (default
+`~/.local/state/pinote/mcp-proposals`). They contain no task content and are retained
+to reject historical proposals. Do not delete them while old sessions may resume.
+They are replay protection, not a second selection database or an authorization
+boundary against local processes.
+
+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,289 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+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', 'cross', 'note'].map((name) => [name, readFileSync(new URL(`../icons/${name}.txt`, import.meta.url), 'utf8').trim()]));
+const Proposal = z.object({ id: z.string().uuid(), text: z.string().min(1).max(4000), tag: z.string().trim().min(1).max(64).optional() }).strict();
+const Context = z.object({ conversationId: z.string().min(1).max(256), contextId: z.string().min(1).max(256).optional(), state: z.object({
+  proposal: Proposal.nullable().optional(),
+  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.20.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]); }
+// Consent receipts are not selection storage. Tombstones prevent old branch state
+// or a reconnect from creating the same proposed task twice, even after a crash.
+const receiptDir = join(process.env.XDG_STATE_HOME || join(homedir(), '.local/state'), 'pinote/mcp-proposals');
+async function consumed(id: string): Promise<boolean> {
+  try { await fs.lstat(join(receiptDir, id)); return true; }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false; throw error; }
+}
+async function consume(id: string): Promise<void> {
+  await fs.mkdir(receiptDir, { recursive: true, mode: 0o700 });
+  const stat = await fs.lstat(receiptDir);
+  if (!stat.isDirectory() || stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o700) throw new Error('Unsafe proposal receipt directory');
+  const file = await fs.open(join(receiptDir, id), 'wx', 0o600);
+  try { await file.writeFile('consumed\n'); await file.sync(); } finally { await file.close(); }
+}
+function boundedState(state: State): State {
+  if (JSON.stringify(state).length > 8192) throw new Error('Proposal exceeds the host state budget; shorten it');
+  return state;
+}
+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, proposal: task || state.proposal && await consumed(state.proposal.id) ? null : state.proposal ?? null };
+  if (state.screen === 'field' && !fields(config.config, task?.agent_notes).some((f) => f.name === state.field)) state.screen = 'settings';
+  state = Context.parse({ conversationId: 'canonical', state }).state;
+  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.';
+  // Footer actions remain valid on every screen, including Settings.
+  if (task) {
+    action('preview', 'Preview full task', { description: 'Display only; never sent to the model' });
+    action('done', 'Complete task', { icon: icons.check });
+  } else if (state.proposal) {
+    action('proposal:accept', 'Accept suggestion', { icon: icons.add, description: state.proposal.text });
+    action('proposal:dismiss', 'Dismiss suggestion', { icon: icons.cross });
+  }
+  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('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; action?: string; width?: number }[] = [{ text: `${icons.note} `, width: 3 }];
+  if (task) {
+    footer.push({ text: `${icons.check} `, action: 'done', width: 3 });
+    footer.push({ text: `${task.tag ? `[${task.tag}] ` : ''}${task.text.split('\n')[0].slice(0, 2000)}`, action: 'preview', width: config.config.titleWidth });
+  } else if (state.proposal) {
+    footer.push({ text: `${icons.cross} `, action: 'proposal:dismiss', width: 3 }, { text: `${icons.add} `, action: 'proposal:accept', width: 3 });
+    footer.push({ text: `${state.proposal.tag ? `[${state.proposal.tag}] ` : ''}${state.proposal.text.split('\n')[0].slice(0, 2000)}`, width: config.config.titleWidth });
+  } else footer.push({ text: 'Pinote · no task', width: config.config.titleWidth });
+  const titleParts = footer.length;
+  if (task) {
+    for (const field of fields(config.config, task.agent_notes)) {
+      if (footer.length - titleParts >= 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: boundedState(state), retainOnNew: true, 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 = { ...before.state };
+  let draft: string | undefined, preview: string | undefined;
+  if (action === 'proposal:accept' || action === 'proposal:dismiss') {
+    const proposal = before.state.proposal;
+    if (!proposal || before.task) throw new Error('Suggestion no longer available');
+    await consume(proposal.id); // Fail closed before any task mutation; never replay uncertain creation.
+    next.proposal = null;
+    if (action === 'proposal:accept') {
+      const task: Task = JSON.parse(await note(['agent', 'add', `--text=${proposal.text}`, ...(proposal.tag ? [`--tag=${proposal.tag}`] : [])], extra.signal));
+      await note(['start', String(task.id)], extra.signal); next.selectedId = task.id;
+    }
+  } else 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');
+    if (next.proposal) await consume(next.proposal.id);
+    await note(['start', String(id)], extra.signal); next.selectedId = id; next.proposal = null;
+  } else if (action === 'add') {
+    if (next.proposal) await consume(next.proposal.id);
+    next.proposal = null;
+    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: 'propose', description: 'Suggest a task without creating it. Requires no selected task. Show a short action-oriented title, optional details after a blank line, and reuse a saved tag. The user clicks + to create/start/select or dismiss. Replaces an unaccepted suggestion; continue working without asking again. Never creates a task before a user action.', inputSchema: { type: 'object' as const, properties: { text: { type: 'string', minLength: 1, maxLength: 4000 }, tag: { type: 'string', minLength: 1, maxLength: 64 } }, required: ['text'], additionalProperties: false } },
+  { 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, outgoing: State | undefined;
+    if (request.params.name === 'propose') {
+      if (await selected(state, extra.signal)) throw new Error('A task is already selected');
+      const args = Proposal.omit({ id: true }).parse(request.params.arguments);
+      if (!args.text.trim()) throw new Error('Task text must not be blank');
+      outgoing = boundedState({ ...state, selectedId: null, proposal: { ...args, id: randomUUID() } });
+      if (state.proposal && !await consumed(state.proposal.id)) await consume(state.proposal.id);
+      result = { status: 'Suggested; user can accept (+) or dismiss. Continue working without asking again.' };
+    } else 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) }], ...(outgoing ? { _meta: { 'native-ui/state': outgoing } } : {}) };
+  } 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.1",
+  "version": "0.20.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"
   }
 }