pi-note 0.19.0 → 0.20.1

package/dist-mcp/mcp/server.js

@@ -1,4 +1,7 @@
-import { createHash } from 'node:crypto';
+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';
@@ -12,8 +15,10 @@ 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({
+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({}) });
@@ -21,7 +26,7 @@ const Action = z.object({ method: z.literal('native-ui/action'), params: z.objec
         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': {} } } });
+const server = new Server({ name: 'pinote', version: '0.20.1' }, { 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) {
@@ -30,6 +35,39 @@ function serial(run) {
     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 };
@@ -70,9 +108,10 @@ 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 };
+    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 };
 }
@@ -83,6 +122,15 @@ function view(data) {
     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') {
@@ -113,8 +161,6 @@ function view(data) {
         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?' });
@@ -125,10 +171,21 @@ function view(data) {
         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 }];
+    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 - 1 >= config.config.maxFields)
+            if (footer.length - titleParts >= config.config.maxFields)
                 break;
             const raw = task.agent_notes[field.name];
             if (!raw)
@@ -150,7 +207,7 @@ function view(data) {
         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 };
+    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;
@@ -184,9 +241,21 @@ server.setRequestHandler(Action, (request, extra) => serial(async () => {
     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 };
+    const next = { ...before.state };
     let draft, preview;
-    if (action.startsWith('screen:'))
+    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';
@@ -204,10 +273,16 @@ server.setRequestHandler(Action, (request, extra) => serial(async () => {
         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;
@@ -256,7 +331,8 @@ server.setRequestHandler(Action, (request, extra) => serial(async () => {
 }));
 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: 'propose', description: 'Before multi-step implementation or configuration migrations, suggest a task if get_current returns null; skip informational questions and trivial edits. Show a short action-oriented title, optional details after a blank line, and reuse a saved tag from tags. The user clicks + to create/start/select or dismiss. Replaces an unaccepted suggestion; continue working without waiting or 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 before multi-step implementation or configuration migrations. Returns null if unselected; then use tags and propose to suggest a task without creating one. Skip informational questions and trivial edits; never replace an existing selection.', 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 } },
@@ -264,8 +340,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [
 server.setRequestHandler(CallToolRequestSchema, (request, extra) => serial(async () => {
     try {
         const state = context(request.params._meta).state;
-        let result;
-        if (request.params.name === 'get_current')
+        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;
@@ -281,7 +368,7 @@ server.setRequestHandler(CallToolRequestSchema, (request, extra) => serial(async
         }
         else
             throw new Error('Unknown tool');
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        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) }] };

package/mcp/README.md

@@ -6,7 +6,7 @@ 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.
+the built-in Pi MCP resource renderer. Use gateway 0.12.0+ with its Pi adapter.
 
 ## Setup
 
@@ -32,7 +32,8 @@ Add a service to the gateway config (use absolute paths):
 }
 ```
 
-Then launch the gateway's generic Pi adapter and run `/gateway-ui pinote`.
+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.
@@ -53,30 +54,58 @@ normal personal data. No desktop notifications are sent.
   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.
+  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 a new conversation starts unselected. Pi must
+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.
 
+## Task-offer guidance
+
+Before multi-step implementation or configuration migrations, agents should call
+`get_current`. If it returns null, use `tags` and `propose` to suggest a short task
+with a saved tag, then continue without waiting. Skip informational questions and
+trivial edits. Never replace an existing selection or create/select without consent.
+
+The tool descriptions reinforce this workflow after discovery. For proactive
+discovery, include the same guidance in the client's always-loaded agent rules;
+tool descriptions alone cannot make an agent discover the service.
+
 ## 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
+not retag/edit existing tasks or install/upgrade the CLI. Completion intentionally
+does not reset conversations. The legacy `taskOfferPolicy` and new-session prompt
+remain editable for native-extension compatibility; the MCP host does not apply
+them automatically. Agent-side task offers follow the client rules and tool
+descriptions above. 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.

package/mcp/server.ts

@@ -1,4 +1,7 @@
-import { createHash } from 'node:crypto';
+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';
@@ -13,8 +16,10 @@ 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({
+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({}) });
@@ -26,7 +31,7 @@ const Action = z.object({ method: z.literal('native-ui/action'), params: z.objec
   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': {} } } });
+const server = new Server({ name: 'pinote', version: '0.20.1' }, { 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> {
@@ -35,6 +40,24 @@ function serial<T>(run: () => Promise<T>): Promise<T> {
   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 };
@@ -68,8 +91,9 @@ 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 };
+  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 };
 }
@@ -81,6 +105,14 @@ function view(data: Snapshot) {
   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') {
@@ -104,8 +136,6 @@ function view(data: Snapshot) {
   } 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?' });
@@ -114,10 +144,18 @@ function view(data: Snapshot) {
     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 }];
+  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 - 1 >= config.config.maxFields) break;
+      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);
@@ -135,7 +173,7 @@ function view(data: Snapshot) {
     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 };
+  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;
@@ -160,9 +198,18 @@ server.setRequestHandler(Action, (request, extra) => serial(async () => {
   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 };
+  const next: State = { ...before.state };
   let draft: string | undefined, preview: string | undefined;
-  if (action.startsWith('screen:')) next.screen = action.slice(7) as State['screen'];
+  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;
@@ -171,8 +218,11 @@ server.setRequestHandler(Action, (request, extra) => serial(async () => {
   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;
+    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') {
@@ -206,7 +256,8 @@ server.setRequestHandler(Action, (request, extra) => serial(async () => {
 }));
 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: 'propose', description: 'Before multi-step implementation or configuration migrations, suggest a task if get_current returns null; skip informational questions and trivial edits. Show a short action-oriented title, optional details after a blank line, and reuse a saved tag from tags. The user clicks + to create/start/select or dismiss. Replaces an unaccepted suggestion; continue working without waiting or 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 before multi-step implementation or configuration migrations. Returns null if unselected; then use tags and propose to suggest a task without creating one. Skip informational questions and trivial edits; never replace an existing selection.', 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 } },
@@ -214,8 +265,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [
 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);
+    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') {
@@ -225,7 +283,7 @@ server.setRequestHandler(CallToolRequestSchema, (request, extra) => serial(async
       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) }] };
+    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.19.0",
+  "version": "0.20.1",
   "description": "Persistent pinote tasks, Markdown handoffs, and task status for Pi",
   "license": "MIT",
   "type": "module",