pi-note 0.13.1 → 0.14.0

package/README.md

@@ -68,9 +68,7 @@ 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 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.
+The normal Pi status area shows selected-task controls and title without replacing other footers. The footer omits the task ID and state and shows only the first line, bounded by `footer.titleWidth` (default 60 terminal columns including the pin, controls, tag and title). Overflow ends with `...`. The title remains clickable for preview; task controls are separate. At very small widths controls are hidden (pin only). The pin and controls are bundled in `icons/note.txt`, `icons/check.txt`, `icons/cross.txt`, and `icons/add.txt`; they use terminal fonts, not a Nerd Font or icon theme.
 
 ### Display-only preview
 
@@ -171,8 +169,8 @@ 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
+- `pinote_propose`: show a suggested task beside the pin icon in the footer without
+  creating a note. Optional `tag`; full text is retained, but the footer 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
@@ -183,22 +181,29 @@ 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 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
+asking in chat. The pin footer shows a pending suggestion, distinct from a selected task:
+
+```text
+📌 ✕  + · [tag] Task title...
+📌 ✓    · [tag] Task title...
+```
+
+![Suggested task controls](../docs/images/pi-task-suggestion.png)
+![Selected task with Done control](../docs/images/pi-task-selected.png)
+
+- Muted **✕** dismisses without creating a note; further offers are suppressed until a new session or reload.
+- Accent **+** creates, starts, and selects the suggested task.
+- Green **✓** completes the selected task and clears the selection on success.
+
+Done occupies the former ✕ position, not the + position, so clicking Add twice cannot accidentally complete the new task. The former + cell stays blank. The selected task's title is a separate preview link.
+
+The configured `footer.titleWidth` bounds the entire row (default 60 columns). Controls stay first; the tag is dropped before truncating the first-line title with `...`. Tiny widths hide controls (pin only). Pi can still clip the combined status row on narrow terminals.
+
+Controls use the [Kitty preview handler](#display-only-preview), with no additional configuration. Fullscreen Kitty uses **Ctrl+Shift+click**. Keyboard alternatives are `/pi-note-no`, `/pi-note-yes`, and `/pi-note-done`. No action submits input or starts an agent turn; editor drafts stay unchanged.
+
+Completion requires an idle Pi session and no pending Pinote operation. It rejects stale selected-task links and externally changed revisions. Accepted mutations drain even if the helper disconnects. On an error, check `/pi-note` before retrying, because a write may already have committed.
+
+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. 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
@@ -216,7 +221,7 @@ Values are Markdown strings; no fields are required. `PR` enables the watcher be
 `Bar` chooses extra footer fields unless configuration overrides it:
 
 ```markdown
-# Agent
+## Agent
 PR: [Task selection #42](https://github.com/org/repo/pull/42)
 Dashboard: [Metrics](http://127.0.0.1:3000/d/app)
 Next: Address review comments

package/icons/add.txt

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

package/index.ts

@@ -10,7 +10,7 @@ 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";
+import { renderSuggestion, renderSelectedTask } 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 = {
@@ -18,7 +18,7 @@ const offerGuidance = {
   "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 = "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 consentGuidance = "The suggestion bar's plus 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 = {
@@ -131,7 +131,7 @@ export default function (pi: ExtensionAPI) {
   let offerDeclined = false;
   const clearSuggestion = (ctx: ExtensionContext) => {
     previewBridge?.clearSuggestion();
-    if (suggestion && ctx.hasUI && ctx.mode === "tui") ctx.ui.setWidget("pinote-suggestion", undefined);
+    if (suggestion && ctx.hasUI && ctx.mode === "tui") ctx.ui.setStatus("pinote", undefined);
     suggestion = undefined;
   };
   let alive = true;
@@ -142,6 +142,11 @@ export default function (pi: ExtensionAPI) {
   let activeContext: ExtensionContext | undefined;
   let cliState: CLIAction | undefined;
   let footerConfig = { ...defaultFooterConfig };
+  const suggestionStatus = (ctx: ExtensionContext) => suggestion ? renderSuggestion(
+    suggestion, footerConfig.titleWidth, ctx.ui.theme, {
+      yes: previewBridge?.suggestionUrl("yes"), no: previewBridge?.suggestionUrl("no"),
+    },
+  ) : undefined;
   const checkCLI = async (ctx: ExtensionContext, suggest = false) => {
     if (!ctx.hasUI || ctx.mode !== "tui" || setupAbort) return;
     const generation = epoch;
@@ -223,7 +228,7 @@ export default function (pi: ExtensionAPI) {
     const current = task(await run(["agent", "get", String(id)], signal, canUse));
     if (!canUse() || selectedId !== id) return null;
     if (!current || current.id !== id || !["active", "in_progress"].includes(current.state)) {
-      if (canUse() && selectedId === id) remember(null);
+      if (!pending && canUse() && selectedId === id) remember(null);
       return null;
     }
     return current;
@@ -262,17 +267,20 @@ export default function (pi: ExtensionAPI) {
         const previewId = current?.id ?? null;
         const previewBranch = branchEpoch;
         previewBridge?.setTask(previewId, (signal) => alive && generation === epoch && previewBranch === branchEpoch &&
-          selectedId === previewId ? preview(ctx, signal) : Promise.resolve(false));
-        const url = previewBridge?.url();
-        // 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);
+          selectedId === previewId ? preview(ctx, signal) : Promise.resolve(false), current ? {
+            revision: current.updated_at,
+            invoke: () => alive && generation === epoch && previewBranch === branchEpoch && selectedId === previewId
+              ? completeTask(ctx, current) : Promise.resolve(false),
+          } : undefined);
+        ctx.ui.setStatus("pinote", current ? renderSelectedTask(current, footerConfig.titleWidth, ctx.ui.theme, {
+          preview: previewBridge?.url(), done: previewBridge?.doneUrl(),
+        }) : suggestionStatus(ctx));
         watcher.update(ctx, current);
       }
     } catch {
       if (alive && generation === epoch && serial === refreshSerial) {
         previewBridge?.invalidate();
-        ctx.ui.setStatus("pinote", `${noteIcon} Pinote unavailable · ${cliState === "upgrade" ? "/pi-note-upgrade" : cliState === "setup" ? "/pi-note-setup" : "/pi-note"}`);
+        ctx.ui.setStatus("pinote", suggestionStatus(ctx) ?? `${noteIcon} Pinote unavailable · ${cliState === "upgrade" ? "/pi-note-upgrade" : cliState === "setup" ? "/pi-note-setup" : "/pi-note"}`);
       }
     }
   };
@@ -322,6 +330,45 @@ export default function (pi: ExtensionAPI) {
       if (pending === operation) pending = undefined;
     }
   };
+  const completeTask = async (ctx: ExtensionContext, displayed?: Task): Promise<boolean> => {
+    if (!alive || !ctx.hasUI || ctx.mode !== "tui" || !ctx.isIdle() || pending || setupAbort || !validId(selectedId)) return false;
+    const generation = epoch;
+    const branch = branchEpoch;
+    const id = selectedId;
+    const operation = Symbol();
+    pending = operation;
+    refreshSerial++;
+    const canAct = () => alive && generation === epoch && branch === branchEpoch && selectedId === id && ctx.isIdle();
+    let wrote = false;
+    try {
+      const current = displayed ?? await currentTask(undefined, canAct);
+      if (!current || current.id !== id || !canAct()) return false;
+      const completed = requiredTask(await run([
+        "agent", "done", String(id), "--expected-updated-at", current.updated_at,
+      ], undefined, canAct), id);
+      wrote = true;
+      if (completed.state !== "done") throw new Error(compatible);
+      if (!canAct()) throw new Error("The session or selection changed. Completion may have committed; read the task before retrying.");
+      remember(null, branch);
+      ctx.ui.notify(`Pinote #${id} completed.`, "info");
+      return true;
+    } catch (error) {
+      if (alive && generation === epoch) ctx.ui.notify(
+        `Pinote completion: ${clean(String(error))}${wrote ? " Check the task before retrying." : ""}`, "error");
+      return false;
+    } finally {
+      if (pending === operation) pending = undefined;
+      if (alive && generation === epoch) await refresh(ctx);
+    }
+  };
+  pi.registerCommand("pi-note-done", {
+    description: "Complete the selected task (same as the footer ✓)",
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI || ctx.mode !== "tui") return;
+      if (args.trim()) { ctx.ui.notify("Usage: /pi-note-done", "warning"); return; }
+      if (!await completeTask(ctx)) ctx.ui.notify("Select a task and wait until Pi is idle and Pinote is available before completing it.", "warning");
+    },
+  });
   pi.registerCommand("pi-note-preview", {
     description: "Display the selected task locally without sending it to the model",
     handler: async (args, ctx) => {
@@ -644,7 +691,7 @@ export default function (pi: ExtensionAPI) {
     }
   };
   pi.registerCommand("pi-note-yes", {
-    description: "Create, start and select the suggested task (same as ✓)",
+    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");
@@ -661,7 +708,7 @@ export default function (pi: ExtensionAPI) {
     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.",
+    description: "Show a suggested task beside the pin icon in the footer, 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 })),
@@ -681,13 +728,7 @@ export default function (pi: ExtensionAPI) {
       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" });
+      ctx.ui.setStatus("pinote", suggestionStatus(ctx));
       return result("pending; user can click ✓ to add and select or ✕ to dismiss, continue work without asking again");
     },
   });
@@ -718,7 +759,7 @@ export default function (pi: ExtensionAPI) {
       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.
+      // Chat consent consumes the same suggestion as clicking +, even if start fails.
       clearSuggestion(ctx);
       try {
         const created = requiredTask(await run(argv, signal, canAct, "0.4.0"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-note",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Persistent pinote tasks, Markdown handoffs, and task status for Pi",
   "license": "MIT",
   "type": "module",

package/preview-bridge.ts

@@ -16,10 +16,11 @@ export function createPreviewBridge() {
   let taskId: number | null = null;
   let callback: ((signal: AbortSignal) => Promise<boolean>) | undefined;
   let nonce: string | undefined;
+  let completion: { revision: string; nonce: string; invoke: () => Promise<boolean> } | 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 invalidate = () => { taskId = null; callback = undefined; nonce = undefined; completion = undefined; };
   const invalidateSuggestion = () => { suggestionCallback = undefined; suggestionNonce = undefined; };
   const cleanup = async () => {
     ready = false;
@@ -66,6 +67,7 @@ export function createPreviewBridge() {
             dispatched = true;
             const input = data.toString("utf8");
             const previewMatch = /^preview ([0-9a-f]{32}) ([1-9][0-9]*) ([0-9a-f]{32})\n$/u.exec(input);
+            const completionMatch = /^done ([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) &&
@@ -78,6 +80,18 @@ export function createPreviewBridge() {
                   () => { if (!client.destroyed) client.end("rejected\n"); });
               return;
             }
+            if (completionMatch && completionMatch[0] === input && completionMatch[1] === capability &&
+                Number(completionMatch[2]) === taskId && completionMatch[3] === completion?.nonce && completion) {
+              client.setTimeout(65000);
+              const acceptedCompletion = completion;
+              const acceptedId = taskId;
+              // Accepted writes drain even if the helper disconnects.
+              Promise.resolve().then(() => !closed && taskId === acceptedId && completion === acceptedCompletion
+                ? acceptedCompletion.invoke() : 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;
@@ -111,10 +125,13 @@ export function createPreviewBridge() {
       })();
       return starting;
     },
-    setTask(id: number | null, preview: (signal: AbortSignal) => Promise<boolean>): void {
+    setTask(id: number | null, preview: (signal: AbortSignal) => Promise<boolean>, done?: { revision: string; invoke: () => Promise<boolean> }): void {
       if (closed) return;
       if (id !== null && (!Number.isSafeInteger(id) || id <= 0)) throw new Error("Invalid preview task");
       if (id !== taskId) nonce = id === null ? undefined : randomBytes(16).toString("hex");
+      if (id === null || !done) completion = undefined;
+      else completion = { revision: done.revision, invoke: done.invoke,
+        nonce: id === taskId && completion?.revision === done.revision ? completion.nonce : randomBytes(16).toString("hex") };
       taskId = id;
       callback = id === null ? undefined : preview;
     },
@@ -123,6 +140,10 @@ export function createPreviewBridge() {
       if (!ready || closed || !socketPath || taskId === null || !nonce) return;
       return `pi-note-preview://${basename(socketPath, ".sock")}/${capability}/${taskId}/${nonce}`;
     },
+    doneUrl(): string | undefined {
+      if (!ready || closed || !socketPath || taskId === null || !completion) return;
+      return `pi-note-preview://${basename(socketPath, ".sock")}/${capability}/${taskId}/${completion.nonce}/done`;
+    },
     setSuggestion(suggestion: (choice: "yes" | "no") => Promise<boolean>): void {
       if (closed) return;
       suggestionCallback = suggestion;

package/preview-click.cjs

@@ -4,12 +4,12 @@ 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})(?:\/(yes|no))?$/;
+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|done))?$/;
 
 function parse(value) {
   if (typeof value !== 'string' || value.length > 180) throw new Error('Preview or suggestion unavailable');
   const m = urlPattern.exec(value);
-  if (!m || m[0] !== value || (m[6] && m[4] !== '1')) throw new Error('Preview or suggestion unavailable');
+  if (!m || m[0] !== value || (m[6] && m[6] !== 'done' && 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 or suggestion unavailable');
   return { pid, tag: m[2], capability: m[3], id, nonce: m[5], choice: m[6] };

package/task-suggestion.ts

@@ -3,18 +3,39 @@ import { stripVTControlCharacters } from "node:util";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 
+const pin = readFileSync(new URL("./icons/note.txt", import.meta.url), "utf8").trim();
 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 add = readFileSync(new URL("./icons/add.txt", import.meta.url), "utf8").trim();
+// Pi's default footer collapses ASCII spaces; NBSP preserves the control cells.
+const gap = "\u00a0";
 const link = (label: string, url?: string) => url ? `\x1b]8;;${url}\x07${label}\x1b]8;;\x07` : label;
+type Task = { text: string; tag?: string | null };
+type Colors = Pick<Theme, "fg">;
 
-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, "");
+function renderTask(task: Task, width: number, theme: Colors, prefix: string, previewUrl?: string): string {
+  // All controls or none: never let a narrow budget reveal only one pending choice.
+  if (visibleWidth(prefix) > width) return truncateToWidth(pin, width, "");
+  const remaining = width - visibleWidth(prefix) - 3; // separator: " · "
+  if (remaining < 4) return prefix.trimEnd();
   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}`;
+  const tag = `[${clean(task.tag ?? "Untagged")}]`;
+  const title = clean(task.text.split("\n", 1)[0]);
+  const tagWidth = visibleWidth(tag) + 1;
+  const label = remaining >= tagWidth + Math.min(12, visibleWidth(title))
+    ? `${theme.fg("muted", tag)} ${theme.fg("text", truncateToWidth(title, remaining - tagWidth, "..."))}`
+    : theme.fg("text", truncateToWidth(title, remaining, "..."));
+  return `${prefix}${theme.fg("muted", " · ")}${link(label, previewUrl)}`;
+}
+
+export function renderSuggestion(task: Task, width: number, theme: Colors, urls: { yes?: string; no?: string }): string {
+  return renderTask(task, width, theme,
+    `${pin} ${theme.fg("muted", link(cross, urls.no))}${gap.repeat(2)}${theme.fg("accent", link(add, urls.yes))}`);
+}
+
+export function renderSelectedTask(task: Task, width: number, theme: Colors, urls: { preview?: string; done?: string }): string {
+  // Reserve the former '+' cell: accepting twice at the same position cannot click Done.
+  return renderTask(task, width, theme,
+    `${pin} ${theme.fg("success", link(check, urls.done))}${gap.repeat(visibleWidth(cross) + 2 + visibleWidth(add) - visibleWidth(check))}`,
+    urls.preview);
 }