pi-note 0.12.1 → 0.13.1

package/README.md

@@ -68,9 +68,9 @@ task, so existing values can be configured without creating another task.
 Type in the task picker to filter by text, ID, tag, or state (all words must match).
 Use ↑/↓ and Enter to select, or Esc to cancel. Rows show **●** for in progress or
 **○** for active, followed by the tag (`[Untagged]` when absent).
-The normal Pi status area shows `👁 📌 [tag] Task title` without replacing other footers.
-The footer omits the task ID and state and shows only the first line, truncated to the configured width (default 60 terminal columns including the eye, pin and tag). Overflow ends with `...`.
-The glyphs are bundled in `icons/eye.txt` and `icons/note.txt`; they use terminal fonts, not a Nerd Font or icon theme.
+The normal Pi status area shows `📌 [tag] Task title` without replacing other footers.
+The footer omits the task ID and state and shows only the first line, truncated to the configured width (default 60 terminal columns including the pin and tag). Overflow ends with `...`.
+The pin glyph is bundled in `icons/note.txt`; it uses terminal fonts, not a Nerd Font or icon theme.
 
 ### Display-only preview
 
@@ -82,12 +82,13 @@ modify the note, editor draft or task selection, and never starts a model call.
 The agent can still read the task separately with `pinote_get_current`.
 Previewing requires Pi to be idle with no other Pinote operation open.
 
-On Linux, the eye is a clickable OSC 8 link to a private per-session Unix socket.
+On Linux, the task text (pin, tag and title) is a clickable OSC 8 link to a
+private per-session Unix socket. Overflow at the configured title width stays linked.
 The package ships [a Kitty configuration example](kitty/open-actions.conf).
 Append its block to `~/.config/kitty/open-actions.conf`, preserving existing
 actions. Replace `/absolute/path/to/pi-note` with the installed package directory
 containing `preview-click.cjs`; for this checkout, that directory is `pi/`.
-Keep `${URL}` literal: Kitty substitutes the clicked eye's link.
+Keep `${URL}` literal: Kitty substitutes the clicked task's link.
 
 ```conf
 protocol pi-note-preview
@@ -97,12 +98,12 @@ action launch --type=background node /absolute/path/to/pi-note/preview-click.cjs
 Do not replace or symlink your entire Kitty configuration to the example: it
 contains only Pinote's handler. Package installation does not edit Kitty files.
 
-Reload Kitty with **Ctrl+Shift+F5**. In Pi's regular mode, click the eye; in
+Reload Kitty with **Ctrl+Shift+F5**. In Pi's regular mode, click the task text; in
 fullscreen mode, use **Ctrl+Shift+click** so Kitty handles the link instead of
 Pi's system URL opener. The helper sends only an authenticated selection
 identifier, never note content or a model prompt. Stale links after task switching, tree navigation, reload or session exit
 are rejected. Other terminals can use `/pi-note-preview`; if the socket cannot
-start, the eye is omitted and that command remains available.
+start, the task remains visible without a link and that command remains available.
 
 Each Pi session remembers its own task, including several sessions in one folder.
 Resume restores that session's task; a new session starts unselected and does not import
@@ -170,6 +171,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 +182,24 @@ 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.
@@ -233,7 +252,7 @@ Add `footer` to `~/.pi/agent/pi-note.json` (or `pi-note.json` under
 }
 ```
 
-Widths are terminal columns, including the eye, pin, tags or field labels, and must be
+Widths are terminal columns, including the pin, tags or field labels, and must be
 integers from 3 to 1000. Defaults: `titleWidth: 60`, `fieldWidth: 60`,
 `maxFields: 4` (allowed 0–64). Each field can override `fieldWidth` with `width`.
 `fields` selects task field names in order, regardless of a task's `Bar`.
@@ -285,8 +304,9 @@ By default, at most four extra fields are shown, each truncated to 60 columns.
 Overflow ends with `...`, including cuts between Markdown/link segments. Removing
 a listed field hides it even if configuration or `Bar` still names it. Terminal
 OSC 8 support is required for clicking links. Pi joins footer statuses on one
-line and truncates the combined line with `...` when the terminal is narrow;
-this extension does not replace other footers. Other fields, such as `Jira` and
+line and truncates the combined line with `...` when the terminal is narrow.
+Pi's final ellipsis is plain text; click the remaining task text to preview it.
+This extension does not replace other footers. Other fields, such as `Jira` and
 `CWD` in the example, stay off the footer unless selected.
 
 ### PR merge watcher

package/icons/check.txt

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

package/icons/cross.txt

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

package/index.ts

@@ -1,5 +1,5 @@
 import { getAgentDir, getMarkdownTheme, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Container, Editor, Markdown, Text, truncateToWidth, visibleWidth, type Keybinding } from "@earendil-works/pi-tui";
+import { Container, Editor, Markdown, Text, truncateToWidth, type Keybinding } from "@earendil-works/pi-tui";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
@@ -10,14 +10,15 @@ 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 = {
@@ -32,7 +33,6 @@ type Task = {
 type Summary = Pick<Task, "id" | "text" | "state" | "tag">;
 // The standard Pi footer accepts text, so ship a portable terminal glyph, not a theme icon.
 const noteIcon = readFileSync(new URL("./icons/note.txt", import.meta.url), "utf8").trim();
-const eyeIcon = readFileSync(new URL("./icons/eye.txt", import.meta.url), "utf8").trim();
 const previewType = "pinote-preview";
 const compatible = "Incompatible note CLI response. Install pinote 0.3.0+ and check note on PATH.";
 const validId = (value: unknown): value is number => Number.isSafeInteger(value) && Number(value) > 0;
@@ -127,6 +127,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;
@@ -197,6 +204,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 });
   };
@@ -256,10 +264,9 @@ export default function (pi: ExtensionAPI) {
         previewBridge?.setTask(previewId, (signal) => alive && generation === epoch && previewBranch === branchEpoch &&
           selectedId === previewId ? preview(ctx, signal) : Promise.resolve(false));
         const url = previewBridge?.url();
-        // Keep the eye outside title truncation, including the minimum title width.
-        const eye = url ? `\x1b]8;;${url}\x07${eyeIcon}\x1b]8;;\x07 ` : "";
-        const width = Math.max(0, footerConfig.titleWidth - (eye ? visibleWidth(eyeIcon) + 1 : 0));
-        ctx.ui.setStatus("pinote", current ? eye + truncateToWidth(`${noteIcon} ${taskTag(current)} ${firstLine(current)}`, width, "...") : undefined);
+        // Truncate before linking so the task label, including configured overflow, is clickable.
+        const label = current ? truncateToWidth(`${noteIcon} ${taskTag(current)} ${firstLine(current)}`, footerConfig.titleWidth, "...") : undefined;
+        ctx.ui.setStatus("pinote", label && url ? `\x1b]8;;${url}\x07${label}\x1b]8;;\x07` : label);
         watcher.update(ctx, current);
       }
     } catch {
@@ -327,6 +334,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++;
@@ -354,7 +363,7 @@ export default function (pi: ExtensionAPI) {
       } catch {
         await bridge.stop();
         if (previewBridge === bridge) previewBridge = undefined;
-        ctx.ui.notify("Pinote eye link unavailable; use /pi-note-preview.", "warning");
+        ctx.ui.notify("Pinote task link unavailable; use /pi-note-preview.", "warning");
       }
     }
     if (!alive || generation !== epoch) return;
@@ -368,6 +377,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);
@@ -380,6 +390,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;
@@ -593,6 +604,93 @@ 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",
@@ -613,17 +711,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/kitty/open-actions.conf

@@ -1,5 +1,5 @@
 # Append this block to ~/.config/kitty/open-actions.conf; preserve existing actions.
 # Replace /absolute/path/to/pi-note with the directory containing preview-click.cjs.
-# Keep ${URL} literal: Kitty substitutes the clicked eye's link.
+# Keep ${URL} literal: Kitty substitutes the clicked task's link.
 protocol pi-note-preview
 action launch --type=background node /absolute/path/to/pi-note/preview-click.cjs ${URL}

package/package.json

@@ -1,21 +1,51 @@
 {
   "name": "pi-note",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "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}`;
+}

package/icons/eye.txt

@@ -1 +0,0 @@
-👁