pi-note 0.12.0 → 0.13.0

package/README.md

@@ -170,6 +170,10 @@ user-level configuration only; project-local files are not read.
   populating relevant values with `pinote_update_current`. Empty/missing values
   stay hidden; this tool does not edit configuration.
 - `pinote_tags`: list saved tag names.
+- `pinote_propose`: show a nonmodal suggested-task bar below the input without
+  creating a note. Optional `tag`; full text is retained, but the bar shows only
+  its title. Requires a TUI with no selected task. The agent continues your work
+  while the suggestion awaits your choice.
 - `pinote_add`: create an active task. Optional `tag`. `select: true` starts and
   remembers it for this session only; use that only after the user agrees.
 
@@ -177,10 +181,27 @@ Version 0.7.0 replaces `pinote_get`/`pinote_update` with these current-task tool
 and removes `pinote_tag`, without aliases. Agents cannot read/update tasks by ID
 or retag existing tasks; use `/pi-note` to select an existing task.
 
-When allowed by `taskOfferPolicy`, the agent proposes one note as `[tag] text`
-and asks before creating it. No continues without a note. Yes calls
-`pinote_add` with `select: true`. An existing selection is not replaced unless the
-user asks to switch. Reuse a saved tag name when it fits.
+When allowed by `taskOfferPolicy`, the agent uses `pinote_propose` instead of
+asking in chat. A bar below the input shows `[tag] Task title  ✓  ✕`:
+
+- **✓** creates the note, starts it, and selects it for this session.
+- **✕** hides the suggestion without creating a note; further offers are suppressed
+  until a new session or reload.
+
+Neither action submits input or starts an agent turn; editor drafts stay unchanged.
+The icons reuse the [Kitty preview handler](#display-only-preview), with no additional
+configuration. Fullscreen Kitty uses **Ctrl+Shift+click**. Keyboard alternatives are
+`/pi-note-yes` and `/pi-note-no`, including when clickable links are unavailable.
+An existing suggestion is retained rather than replaced. Selection, tree navigation,
+reload and shutdown invalidate its links; repeated acceptance cannot duplicate a note.
+A busy Pinote operation blocks acceptance; retry after it finishes. On an error, check
+`/pi-note` before retrying, because a write may already have committed.
+Noninteractive agents still ask in chat before using `pinote_add` with `select: true`.
+An existing selection is not replaced unless the user asks to switch. Reuse a saved
+tag name when it fits.
+Task text starts with a short, action-oriented title (aim for at most 60 characters).
+Put context, URLs, commands, and acceptance criteria after a blank line; the title
+should not contain implementation details. This is agent guidance, not a storage limit.
 
 Agents are guided to keep notes to three short bullets total: relevant outcome,
 blocker, and next action. Replace stale notes; omit narration, repeated task text,

package/icons/check.txt

@@ -0,0 +1 @@
+✓

package/icons/cross.txt

@@ -0,0 +1 @@
+✕

package/index.ts

@@ -10,14 +10,16 @@ import { FooterSettings, TaskMenu, withSettingsTab } from "./footer-settings.ts"
 import { TaskPicker, taskState, taskTag } from "./task-picker.ts";
 import { bundledCLIVersion, cliMenu, detectCLI, setupCLI, setupHint, versionAtLeast, type CLIAction } from "./setup.ts";
 import { createPreviewBridge } from "./preview-bridge.ts";
+import { renderSuggestion } from "./task-suggestion.ts";
 
 const handoffGuidance = "Keep agent notes to at most three short bullets total: outcome, blocker, next action, only when relevant. Replace stale notes; omit narration, repeated task text, and routine test logs. Keep a GitHub pull request in the PR field. Read pinote_fields to learn the user's globally configured footer field names and presentation. Populate those fields with meaningful task values when relevant using pinote_update_current; fields without values stay hidden. Footer fields and widths are chosen by the user's pi-note.json config. Set configured fields with Markdown values; links are clickable. When footer.fields is unset, Bar selects labels, one per line. Do not list PR in Bar. Remove a field to hide it. Do not modify config without user approval.";
 const offerGuidance = {
-  always: "When the user gives work and no pinote task is selected, propose one note as `[tag] text` and ask before creating it.",
-  "github-remote": "When the user gives work and no pinote task is selected, first verify with Git that the current repository has a remote whose URL host is github.com (HTTPS or SSH). Only then propose one note as `[tag] text` and ask before creating it. Local paths, other hosts, and GitHub-looking URL paths do not qualify. If no GitHub remote is verified, do not offer a task; explicit user requests to create one remain allowed.",
+  always: "When the user gives work and no pinote task is selected, use pinote_propose to show one suggested `[tag] task` in the bottom bar instead of asking in chat. In noninteractive modes, ask before creating it.",
+  "github-remote": "When the user gives work and no pinote task is selected, first verify with Git that the current repository has a remote whose URL host is github.com (HTTPS or SSH). Only then use pinote_propose to show one suggested `[tag] task` in the bottom bar instead of asking in chat. In noninteractive modes, ask before creating it. Local paths, other hosts, and GitHub-looking URL paths do not qualify. If no GitHub remote is verified, do not offer a task; explicit user requests to create one remain allowed.",
   never: "Do not offer to create a pinote task. Create one only when the user explicitly requests it.",
 };
-const consentGuidance = "On no, continue without a note. On yes, call pinote_add with select true so it becomes this session's active task. Never add or select without a yes. If a task is already selected, do not replace it unless the user asks to switch.";
+const consentGuidance = "The suggestion bar's check creates, starts and selects the note; its cross dismisses it. Continue the requested work while the suggestion is pending; do not ask again in chat or create a note yourself. On a chat no, continue without a note; on a chat yes, call pinote_add with select true. Never add or select without consent. If a task is already selected, do not replace it unless the user asks to switch.";
+const titleGuidance = "Start task text with a short, action-oriented summary (aim for at most 60 characters). Put context, URLs, commands, and acceptance criteria after a blank line. Never put implementation details in the title.";
 const tagGuidance = "Reuse a pinote_tags name when it fits. One tag; case-sensitive, trimmed, at most 64 characters. Tags are set when creating tasks with pinote_add; agent tools cannot retag existing tasks. Do not use pinote_update_current for tags or task text.";
 type Task = {
   id: number;
@@ -74,7 +76,7 @@ function creationGuidance(): { guidelines: string[]; error?: string } {
     policy = "never";
     error = cause instanceof Error ? cause.message : String(cause);
   }
-  return { guidelines: [`${offerGuidance[policy]} ${consentGuidance}`, tagGuidance], error };
+  return { guidelines: [`${offerGuidance[policy]} ${consentGuidance}`, titleGuidance, tagGuidance], error };
 }
 
 function handoffPrompt(): string {
@@ -126,6 +128,13 @@ export default function (pi: ExtensionAPI) {
     return view;
   });
   let previewBridge: ReturnType<typeof createPreviewBridge> | undefined;
+  let suggestion: { text: string; tag?: string } | undefined;
+  let offerDeclined = false;
+  const clearSuggestion = (ctx: ExtensionContext) => {
+    previewBridge?.clearSuggestion();
+    if (suggestion && ctx.hasUI && ctx.mode === "tui") ctx.ui.setWidget("pinote-suggestion", undefined);
+    suggestion = undefined;
+  };
   let alive = true;
   let epoch = 0;
   let refreshSerial = 0;
@@ -196,6 +205,7 @@ export default function (pi: ExtensionAPI) {
   const remember = (id: number | null, branch = branchEpoch) => {
     if (!alive || branch !== branchEpoch || selectedId === id) return;
     previewBridge?.invalidate();
+    if (activeContext) clearSuggestion(activeContext);
     selectedId = id;
     pi.appendEntry(selectionType, { id });
   };
@@ -326,6 +336,8 @@ export default function (pi: ExtensionAPI) {
     setupAbort?.abort();
     // Retire old polling before bridge teardown/startup yields to its scheduled callbacks.
     watcher.stop();
+    clearSuggestion(activeContext ?? ctx);
+    offerDeclined = false;
     alive = false;
     epoch++;
     branchEpoch++;
@@ -367,6 +379,7 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_tree", async (_event, ctx) => {
     if (!alive) return;
     branchEpoch++;
+    clearSuggestion(ctx);
     previewBridge?.invalidate();
     const generation = branchEpoch;
     const id = readSelection(ctx);
@@ -379,6 +392,7 @@ export default function (pi: ExtensionAPI) {
   pi.on("agent_end", async (_event, ctx) => { await refresh(ctx); });
   pi.on("session_shutdown", async (_event, ctx) => {
     setupAbort?.abort();
+    clearSuggestion(ctx);
     alive = false;
     activeContext = undefined;
     selectedId = null;
@@ -592,13 +606,100 @@ export default function (pi: ExtensionAPI) {
       return { content: [{ type: "text" as const, text: JSON.stringify(value) }], details: value };
     },
   });
+  const respondToSuggestion = async (choice: "yes" | "no", ctx: ExtensionContext): Promise<boolean> => {
+    const proposed = suggestion;
+    if (!alive || !proposed || selectedId !== null) return false;
+    if (choice === "no") {
+      offerDeclined = true;
+      clearSuggestion(ctx);
+      return true;
+    }
+    if (pending || setupAbort) return false;
+    const generation = epoch;
+    const branch = branchEpoch;
+    const operation = Symbol();
+    pending = operation;
+    refreshSerial++;
+    const canAct = () => alive && generation === epoch && branch === branchEpoch && selectedId === null && pending === operation;
+    // Consume consent before yielding: repeat clicks cannot create duplicate notes.
+    clearSuggestion(ctx);
+    let created: Task | undefined;
+    try {
+      const argv = ["agent", "add", `--text=${proposed.text}`];
+      if (proposed.tag !== undefined) argv.push(`--tag=${proposed.tag}`);
+      // Accepted mutations drain even if the click helper disconnects.
+      created = requiredTask(await run(argv, undefined, canAct, "0.4.0"));
+      if (!canAct()) throw new Error("The session or selection changed; the note was created but not selected.");
+      const chosen = await startTask(created.id, canAct);
+      if (!chosen || !alive || generation !== epoch || branch !== branchEpoch || selectedId !== chosen.id) {
+        throw new Error("The session or selection changed; the note may have started but was not selected here.");
+      }
+      ctx.ui.notify(`Pinote #${chosen.id} created and selected.`, "info");
+      return true;
+    } catch (error) {
+      if (alive && generation === epoch) ctx.ui.notify(
+        `Pinote suggestion: ${clean(String(error))}${created ? ` Note #${created.id} was created; use /pi-note to select it. Do not add it again.` : " A write may have committed; check /pi-note before retrying."}`, "error");
+      return false;
+    } finally {
+      if (pending === operation) pending = undefined;
+      if (alive && generation === epoch) await refresh(ctx);
+    }
+  };
+  pi.registerCommand("pi-note-yes", {
+    description: "Create, start and select the suggested task (same as ✓)",
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI || ctx.mode !== "tui") return;
+      if (args.trim() || !await respondToSuggestion("yes", ctx)) ctx.ui.notify("No available suggestion, or a Pinote operation is busy. Retry when it finishes.", "warning");
+    },
+  });
+  pi.registerCommand("pi-note-no", {
+    description: "Dismiss the suggested task without creating a note (same as ✕)",
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI || ctx.mode !== "tui") return;
+      if (args.trim() || !await respondToSuggestion("no", ctx)) ctx.ui.notify("No available suggestion. Usage: /pi-note-no", "warning");
+    },
+  });
+  pi.registerTool({
+    name: "pinote_propose",
+    label: "Pinote suggest task",
+    promptGuidelines: createGuidance,
+    description: "Show a suggested task in a nonmodal bar below the input, without creating it or asking in chat. ✓ creates, starts and selects it; ✕ dismisses it. Continue the requested work while awaiting consent. Requires an interactive TUI with no selected task. An existing suggestion is retained; a dismissed offer is not repeated. In noninteractive modes ask in chat, then use pinote_add only after consent.",
+    parameters: Type.Object({
+      text: Type.String({ minLength: 1, description: "Short action-oriented title, then optional details after a blank line." }),
+      tag: Type.Optional(Type.String({ minLength: 1, maxLength: 64 })),
+    }, { additionalProperties: false }),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (!text(params.text) || !params.text.trim()) throw new Error("text must be a non-empty note.");
+      if (params.tag !== undefined && (!text(params.tag) || !params.tag.trim() || params.tag.trim().length > 64)) throw new Error("tag must be a non-empty name of at most 64 characters.");
+      if (!alive || !ctx.hasUI || ctx.mode !== "tui") throw new Error("Task suggestions need an interactive TUI. Ask in chat before using pinote_add.");
+      const generation = epoch;
+      const branch = branchEpoch;
+      const current = await selected(ctx, signal);
+      if (!alive || generation !== epoch || branch !== branchEpoch) throw new Error("Pinote operation cancelled: the session changed.");
+      if (current || selectedId !== null) throw new Error("A task is already selected; keep it unless the user asks to switch.");
+      if (pending || setupAbort) throw new Error("A pinote operation is already open. Retry after it finishes.");
+      const result = (status: string) => ({ content: [{ type: "text" as const, text: JSON.stringify({ status }) }], details: { status } });
+      if (offerDeclined) return result("dismissed; continue without a note and do not offer again");
+      if (suggestion) return result("pending; existing suggestion retained, continue work without asking again");
+      suggestion = { text: params.text, ...(params.tag === undefined ? {} : { tag: params.tag.trim() }) };
+      previewBridge?.setSuggestion((choice) => respondToSuggestion(choice, ctx));
+      const proposed = suggestion;
+      ctx.ui.setWidget("pinote-suggestion", (_tui, theme) => ({
+        render: (width) => [renderSuggestion(proposed, width, theme, {
+          yes: previewBridge?.suggestionUrl("yes"), no: previewBridge?.suggestionUrl("no"),
+        })],
+        invalidate() {},
+      }), { placement: "belowEditor" });
+      return result("pending; user can click ✓ to add and select or ✕ to dismiss, continue work without asking again");
+    },
+  });
   pi.registerTool({
     name: "pinote_add",
     label: "Pinote add",
     promptGuidelines: createGuidance,
-    description: "Create an active pinote task. Optional tag is registered if new. Set select true only after the user agrees to make it this session's active task; that starts it and remembers it for this session only. Omitting select leaves the current selection unchanged. Does not refresh the desktop notification or bind the project directory.",
+    description: "Create an active pinote task. Start text with a short task title; put details after a blank line. Optional tag is registered if new. Set select true only after the user agrees to make it this session's active task; that starts it and remembers it for this session only. Omitting select leaves the current selection unchanged. Does not refresh the desktop notification or bind the project directory.",
     parameters: Type.Object({
-      text: Type.String({ minLength: 1 }),
+      text: Type.String({ minLength: 1, description: "Short action-oriented title (aim for at most 60 characters), then optional blank line and details." }),
       tag: Type.Optional(Type.String({ minLength: 1 })),
       select: Type.Optional(Type.Boolean()),
     }),
@@ -612,17 +713,22 @@ export default function (pi: ExtensionAPI) {
       if (params.tag !== undefined) argv.push(`--tag=${params.tag}`);
       const generation = epoch;
       const branch = branchEpoch;
-      const created = await writeTask(ctx, signal, argv, undefined, "0.4.0");
-      if (params.select !== true) return toolResult(created);
-      if (!alive || generation !== epoch || branch !== branchEpoch) throw new Error("Pinote operation cancelled: the session changed.");
+      if (params.select !== true) return toolResult(await writeTask(ctx, signal, argv, undefined, "0.4.0"));
       if (pending) throw new Error("A pinote operation is already open. Retry after it finishes.");
       const operation = Symbol();
+      const previousSelection = selectedId;
       pending = operation;
+      refreshSerial++;
+      const canAct = () => alive && generation === epoch && branch === branchEpoch && pending === operation && selectedId === previousSelection;
+      // Chat consent consumes the same suggestion as clicking ✓, even if start fails.
+      clearSuggestion(ctx);
       try {
-        const chosen = await startTask(
-          created.id, () => alive && generation === epoch && branch === branchEpoch && pending === operation, signal,
-        );
-        if (!chosen) throw new Error("Pinote operation cancelled: the session changed.");
+        const created = requiredTask(await run(argv, signal, canAct, "0.4.0"));
+        if (!canAct()) throw new Error("Pinote operation cancelled: the session changed. The note was created; check /pi-note before retrying.");
+        const chosen = await startTask(created.id, canAct, signal);
+        if (!chosen || !alive || generation !== epoch || branch !== branchEpoch || selectedId !== chosen.id) {
+          throw new Error("Pinote operation cancelled: the session changed. The note may have started; check /pi-note before retrying.");
+        }
         return toolResult(chosen);
       } finally {
         if (pending === operation) pending = undefined;

package/package.json

@@ -1,21 +1,51 @@
 {
   "name": "pi-note",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Persistent pinote tasks, Markdown handoffs, and task status for Pi",
   "license": "MIT",
   "type": "module",
-  "keywords": ["pi-package", "tasks", "notes"],
-  "engines": { "node": ">=22.19.0" },
+  "keywords": [
+    "pi-package",
+    "tasks",
+    "notes"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kvidzibo/pinote.git",
     "directory": "pi"
   },
   "homepage": "https://github.com/kvidzibo/pinote/tree/main/pi#readme",
-  "bugs": { "url": "https://github.com/kvidzibo/pinote/issues" },
-  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
-  "files": ["index.ts", "pr-watch.ts", "footer-links.ts", "footer-config.ts", "footer-settings.ts", "task-picker.ts", "setup.ts", "preview-bridge.ts", "preview-click.cjs", "icons", "kitty", "README.md", "LICENSE"],
-  "pi": { "extensions": ["./index.ts"] },
+  "bugs": {
+    "url": "https://github.com/kvidzibo/pinote/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "index.ts",
+    "pr-watch.ts",
+    "footer-links.ts",
+    "footer-config.ts",
+    "footer-settings.ts",
+    "task-picker.ts",
+    "task-suggestion.ts",
+    "setup.ts",
+    "preview-bridge.ts",
+    "preview-click.cjs",
+    "icons",
+    "kitty",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
   "scripts": {
     "check": "tsc --noEmit",
     "test:unit": "node --test --experimental-strip-types tests/*.test.ts",

package/preview-bridge.ts

@@ -16,8 +16,11 @@ export function createPreviewBridge() {
   let taskId: number | null = null;
   let callback: ((signal: AbortSignal) => Promise<boolean>) | undefined;
   let nonce: string | undefined;
+  let suggestionCallback: ((choice: "yes" | "no") => Promise<boolean>) | undefined;
+  let suggestionNonce: string | undefined;
   const clients = new Set<Socket>();
   const invalidate = () => { taskId = null; callback = undefined; nonce = undefined; };
+  const invalidateSuggestion = () => { suggestionCallback = undefined; suggestionNonce = undefined; };
   const cleanup = async () => {
     ready = false;
     for (const client of clients) client.destroy();
@@ -62,14 +65,32 @@ export function createPreviewBridge() {
             if (!data.includes(10)) return;
             dispatched = true;
             const input = data.toString("utf8");
-            const match = /^preview ([0-9a-f]{32}) ([1-9][0-9]*) ([0-9a-f]{32})\n$/u.exec(input);
-            const id = match ? Number(match[2]) : NaN;
-            if (!match || match[0] !== input || match[1] !== capability || !Number.isSafeInteger(id) ||
-                id !== taskId || match[3] !== nonce || !callback) { client.end("rejected\n"); return; }
-            const invoke = callback;
-            Promise.resolve().then(() => !closed && !request.signal.aborted && taskId === id && nonce === match[3] ? invoke(request.signal) : false)
-              .then((accepted) => { if (!client.destroyed) client.end(accepted === true ? "accepted\n" : "rejected\n"); },
-                () => { if (!client.destroyed) client.end("rejected\n"); });
+            const previewMatch = /^preview ([0-9a-f]{32}) ([1-9][0-9]*) ([0-9a-f]{32})\n$/u.exec(input);
+            const suggestionMatch = /^(yes|no) ([0-9a-f]{32}) 1 ([0-9a-f]{32})\n$/u.exec(input);
+            const id = previewMatch ? Number(previewMatch[2]) : NaN;
+            if (previewMatch && previewMatch[0] === input && previewMatch[1] === capability && Number.isSafeInteger(id) &&
+                id === taskId && previewMatch[3] === nonce && callback) {
+              const invoke = callback;
+              const requestNonce = nonce;
+              Promise.resolve().then(() => !closed && !request.signal.aborted && taskId === id && nonce === requestNonce && callback === invoke
+                ? invoke(request.signal) : false)
+                .then((accepted) => { if (!client.destroyed) client.end(accepted === true ? "accepted\n" : "rejected\n"); },
+                  () => { if (!client.destroyed) client.end("rejected\n"); });
+              return;
+            }
+            if (suggestionMatch && suggestionMatch[0] === input && suggestionMatch[2] === capability && suggestionMatch[3] === suggestionNonce && suggestionCallback) {
+              client.setTimeout(65000);
+              const invoke = suggestionCallback;
+              const requestNonce = suggestionNonce;
+              const choice = suggestionMatch[1] as "yes" | "no";
+              // Add/start/select and refresh can run eleven 5s CLI calls; accepted mutations drain on disconnect.
+              Promise.resolve().then(() => !closed && suggestionNonce === requestNonce && suggestionCallback === invoke
+                ? invoke(choice) : false)
+                .then((accepted) => { if (!client.destroyed) client.end(accepted === true ? "accepted\n" : "rejected\n"); },
+                  () => { if (!client.destroyed) client.end("rejected\n"); });
+              return;
+            }
+            client.end("rejected\n");
           });
         });
         server = instance;
@@ -102,9 +123,20 @@ export function createPreviewBridge() {
       if (!ready || closed || !socketPath || taskId === null || !nonce) return;
       return `pi-note-preview://${basename(socketPath, ".sock")}/${capability}/${taskId}/${nonce}`;
     },
+    setSuggestion(suggestion: (choice: "yes" | "no") => Promise<boolean>): void {
+      if (closed) return;
+      suggestionCallback = suggestion;
+      suggestionNonce = randomBytes(16).toString("hex");
+    },
+    clearSuggestion(): void { invalidateSuggestion(); },
+    suggestionUrl(choice: "yes" | "no"): string | undefined {
+      if ((choice !== "yes" && choice !== "no") || !ready || closed || !socketPath || !suggestionNonce || !suggestionCallback) return;
+      return `pi-note-preview://${basename(socketPath, ".sock")}/${capability}/1/${suggestionNonce}/${choice}`;
+    },
     async stop(): Promise<void> {
       closed = true;
       invalidate();
+      invalidateSuggestion();
       if (!stopping) stopping = (async () => { await starting?.catch(() => {}); await cleanup(); })();
       return stopping;
     },

package/preview-click.cjs

@@ -4,15 +4,15 @@ const net = require('node:net');
 const fs = require('node:fs');
 const path = require('node:path');
 
-const urlPattern = /^pi-note-preview:\/\/([1-9][0-9]*)-([0-9a-f]{8})\/([0-9a-f]{32})\/([1-9][0-9]*)\/([0-9a-f]{32})$/;
+const urlPattern = /^pi-note-preview:\/\/([1-9][0-9]*)-([0-9a-f]{8})\/([0-9a-f]{32})\/([1-9][0-9]*)\/([0-9a-f]{32})(?:\/(yes|no))?$/;
 
 function parse(value) {
-  if (typeof value !== 'string' || value.length > 160) throw new Error('Preview unavailable');
+  if (typeof value !== 'string' || value.length > 180) throw new Error('Preview or suggestion unavailable');
   const m = urlPattern.exec(value);
-  if (!m || m[0] !== value) throw new Error('Preview unavailable');
+  if (!m || m[0] !== value || (m[6] && m[4] !== '1')) throw new Error('Preview or suggestion unavailable');
   const pid = Number(m[1]), id = Number(m[4]);
-  if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(id) || pid <= 0 || id <= 0) throw new Error('Preview unavailable');
-  return { pid, tag: m[2], capability: m[3], id, nonce: m[5] };
+  if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(id) || pid <= 0 || id <= 0) throw new Error('Preview or suggestion unavailable');
+  return { pid, tag: m[2], capability: m[3], id, nonce: m[5], choice: m[6] };
 }
 function socketPathFor(value) {
   const p = parse(value);
@@ -30,17 +30,19 @@ function verify(file) {
 function preview(value) {
   let p, file;
   try { p = parse(value); file = socketPathFor(value); verify(file); }
-  catch { return Promise.reject(new Error('Preview unavailable')); }
+  catch { return Promise.reject(new Error('Preview or suggestion unavailable')); }
   return new Promise((resolve, reject) => {
     const client = net.createConnection(file);
     let response = Buffer.alloc(0), done = false;
+    const message = p.choice ? `${p.choice} ${p.capability} ${p.id} ${p.nonce}\n` : `preview ${p.capability} ${p.id} ${p.nonce}\n`;
+    const errorMessage = 'Preview or suggestion unavailable';
     const finish = (err, result) => {
       if (done) return;
       done = true; clearTimeout(timer); client.destroy();
-      err ? reject(new Error('Preview unavailable')) : resolve(result);
+      err ? reject(new Error(errorMessage)) : resolve(result);
     };
-    const timer = setTimeout(() => finish(new Error()), 6000);
-    client.on('connect', () => client.write(`preview ${p.capability} ${p.id} ${p.nonce}\n`));
+    const timer = setTimeout(() => finish(new Error()), p.choice ? 70000 : 6000);
+    client.on('connect', () => client.write(message));
     client.on('data', chunk => {
       response = Buffer.concat([response, chunk]);
       if (response.length > 64) return finish(new Error());
@@ -57,7 +59,7 @@ if (require.main === module) {
     process.exitCode = 2;
   } else {
     preview(process.argv[2]).catch(() => {
-      console.error('Pinote preview unavailable; select a task and wait until Pi is idle.');
+      console.error('Pinote preview or suggestion unavailable; select a task and wait until Pi is idle.');
       process.exitCode = 1;
     });
   }

package/task-suggestion.ts

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+import { stripVTControlCharacters } from "node:util";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+const check = readFileSync(new URL("./icons/check.txt", import.meta.url), "utf8").trim();
+const cross = readFileSync(new URL("./icons/cross.txt", import.meta.url), "utf8").trim();
+const link = (label: string, url?: string) => url ? `\x1b]8;;${url}\x07${label}\x1b]8;;\x07` : label;
+
+export function renderSuggestion(
+  task: { text: string; tag?: string }, width: number, theme: Pick<Theme, "fg">,
+  urls: { yes?: string; no?: string },
+): string {
+  const actions = `${theme.fg("success", link(check, urls.yes))}  ${theme.fg("error", link(cross, urls.no))}`;
+  const actionsWidth = visibleWidth(actions);
+  if (width <= actionsWidth + 2) return truncateToWidth(actions, width, "");
+  const clean = (value: string) => stripVTControlCharacters(value).replace(/[\x00-\x1f\x7f-\x9f]/gu, " ").replace(/\s+/gu, " ").trim();
+  const label = `[${clean(task.tag ?? "Untagged")}] ${clean(task.text.split("\n", 1)[0])}`;
+  return `${theme.fg("muted", truncateToWidth(label, Math.max(0, width - actionsWidth - 2), "..."))}  ${actions}`;
+}