pi-note 0.16.0 → 0.16.2

package/README.md

@@ -81,7 +81,12 @@ to model**: it is a local custom session entry, excluded from subsequent model
 requests, compaction and branch summaries. It survives session resume but does not
 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.
+Click previews work while the agent is running, provided no other Pinote operation
+is open. Each click saves a fresh snapshot in the transcript, above any currently
+streaming response. Later output scrolls it upward; it does not expire. Preview
+reads never lock out the agent's task updates. Settings still requires Pi to be idle.
+
+![Preview above a running response](../docs/images/pi-note-active-preview.png)
 
 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.
@@ -132,9 +137,16 @@ Configure `~/.pi/agent/pi-note.json` (or the agent directory set by
 
 `taskOfferPolicy` controls the agent's task-offer guidance:
 
-- `always` (default): offer a task when given work with no task selected.
-- `github-remote`: first verify with Git that the repository has an HTTPS or SSH
-  remote hosted on `github.com`; otherwise do not offer. Local paths and other
+With no selected task, suggest a note only when implementation is expected to
+span multiple turns. Skip questions, investigation, recon, and small edits (such
+as changing a few configuration lines). If investigation develops into substantial
+implementation, suggest then. No plan is required: a short title identifies the
+work. Explicit user requests to create a task remain allowed under every policy.
+
+- `always` (default): offer for qualifying implementation in any repository.
+- `github-remote`: for qualifying implementation, first verify with Git that the
+  repository has an HTTPS or SSH remote hosted on `github.com`; otherwise do not
+  offer. Local paths and other
   hosts do not qualify. This is agent guidance, not a network or PR-access check.
 - `never`: do not offer tasks; explicit requests to create one remain allowed.
 
@@ -197,7 +209,7 @@ asking in chat. The pin footer shows a pending suggestion, distinct from a selec
 ![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.
+- Muted **✕** dismisses only the current suggestion without creating a note; the agent can suggest another task while none is selected.
 - Accent **+** creates, starts, and selects the suggested task.
 - Green **✓** completes the selected task, starts a clean unselected session, and reloads Pi without a completion prompt. Menu **Done** and **Complete task** in Settings do the same.
 
@@ -209,7 +221,7 @@ Controls use the [Kitty preview handler](#display-only-preview), with no additio
 
 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. Failed or stale writes never restart Pi. If another extension cancels the new session, the task remains completed and Pi reports the cancellation. The reload runs through the new session's fresh context; retired contexts are not reused.
 
-An existing suggestion is retained rather than replaced. Pending suggestions survive `/reload` and session resume, including their full text and tag; new links replace stale capabilities. Accepted or dismissed suggestions never reappear on reload. New sessions and forks start without a suggestion; selecting a task or navigating the tree clears it. Suggestion state is local, display-only session metadata, not model context. Pi saves the session after the first submitted message; quitting before that can still lose unsaved session state. 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
+An existing suggestion is retained rather than replaced. Pending suggestions survive `/reload` and session resume, including their full text and tag; new links replace stale capabilities. Accepted or dismissed suggestions never reappear on reload, but dismissal does not block new proposals—even in sessions saved by older versions. New sessions and forks start without a suggestion; selecting a task or navigating the tree clears it. Suggestion state is local, display-only session metadata, not model context. Pi saves the session after the first submitted message; quitting before that can still lose unsaved session state. 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

package/index.ts

@@ -14,12 +14,13 @@ import { createPreviewBridge } from "./preview-bridge.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 implementationOfferGuidance = "When no pinote task is selected, suggest one only when implementation is expected to span multiple turns. Skip suggestions for questions, investigation, recon, and small edits such as changing a few configuration lines. If investigation develops into substantial implementation, suggest then. No plan is required; use a short title describing the work. Explicit user requests to create one remain allowed.";
 const offerGuidance = {
-  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.",
+  always: `${implementationOfferGuidance} For eligible work, 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": `${implementationOfferGuidance} For eligible work, 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.`,
   never: "Do not offer to create a pinote task. Create one only when the user explicitly requests it.",
 };
-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 consentGuidance = "The suggestion bar's plus creates, starts and selects the note; its cross dismisses only that suggestion, not future suggestions. 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 = {
@@ -135,8 +136,7 @@ export default function (pi: ExtensionAPI) {
   let previewBridge: ReturnType<typeof createPreviewBridge> | undefined;
   const suggestionType = "pinote-suggestion";
   let suggestion: { text: string; tag?: string } | undefined;
-  let offerDeclined = false;
-  const saveSuggestion = () => pi.appendEntry(suggestionType, { suggestion: suggestion ?? null, declined: offerDeclined });
+  const saveSuggestion = () => pi.appendEntry(suggestionType, { suggestion: suggestion ?? null });
   const clearSuggestion = (ctx: ExtensionContext, persist = true) => {
     const hadSuggestion = suggestion !== undefined;
     previewBridge?.clearSuggestion();
@@ -146,23 +146,23 @@ export default function (pi: ExtensionAPI) {
   };
   const restoreSuggestion = (ctx: ExtensionContext) => {
     suggestion = undefined;
-    offerDeclined = false;
     for (const entry of ctx.sessionManager.getBranch()) {
       if (entry.type !== "custom" || entry.customType !== suggestionType) continue;
       const data = entry.data;
-      if (!record(data) || typeof data.declined !== "boolean") continue;
+      if (!record(data)) continue;
       const value = data.suggestion;
-      suggestion = record(value) && text(value.text) && value.text.trim() &&
+      // Legacy dismissal entries clear their proposal, but never block a new one.
+      suggestion = data.declined !== true && record(value) && text(value.text) && value.text.trim() &&
         (value.tag === undefined || (text(value.tag) && value.tag.trim() && value.tag.length <= 64))
         ? { text: value.text, ...(value.tag === undefined ? {} : { tag: value.tag as string }) } : undefined;
-      offerDeclined = data.declined;
     }
-    if (selectedId !== null || offerDeclined) suggestion = undefined;
+    if (selectedId !== null) suggestion = undefined;
   };
   let alive = true;
   let epoch = 0;
   let refreshSerial = 0;
   let pending: symbol | undefined;
+  let previewPending = false;
   let setupAbort: AbortController | undefined;
   let activeContext: ExtensionContext | undefined;
   let cliState: CLIAction | undefined;
@@ -311,18 +311,18 @@ export default function (pi: ExtensionAPI) {
     }
   };
   const preview = async (ctx: ExtensionContext, requestSignal?: AbortSignal): Promise<boolean> => {
-    if (!ctx.hasUI || ctx.mode !== "tui" || !ctx.isIdle() || pending || !validId(selectedId)) return false;
+    if (!ctx.hasUI || ctx.mode !== "tui" || pending || previewPending || !validId(selectedId)) return false;
     const generation = epoch;
     const branch = branchEpoch;
     const id = selectedId;
-    const operation = Symbol();
-    pending = operation;
+    // Serialize clicks without blocking the agent's task updates.
+    previewPending = true;
     // Complete before the bridge's 5s and helper's 6s deadlines; disconnection cancels reads too.
     const controller = new AbortController();
     const deadline = Date.now() + 4000;
     const timer = setTimeout(() => controller.abort(), 4000);
     const signal = requestSignal ? AbortSignal.any([requestSignal, controller.signal]) : controller.signal;
-    const canUse = () => alive && generation === epoch && branch === branchEpoch && selectedId === id && ctx.isIdle() &&
+    const canUse = () => alive && generation === epoch && branch === branchEpoch && selectedId === id && !pending &&
       !signal.aborted && Date.now() < deadline;
     try {
       const current = await currentTask(signal, canUse);
@@ -335,7 +335,7 @@ export default function (pi: ExtensionAPI) {
       return false;
     } finally {
       clearTimeout(timer);
-      if (pending === operation) pending = undefined;
+      previewPending = false;
     }
   };
   const dispatchCompletion = (ctx: ExtensionContext, displayed: Task, selection: string): Promise<boolean> => {
@@ -424,7 +424,6 @@ export default function (pi: ExtensionAPI) {
     if (_event.reason === "new" || _event.reason === "fork") {
       // A fork may include an ancestor proposal whose consent was consumed elsewhere.
       clearSuggestion(ctx, false);
-      offerDeclined = false;
       if (ctx.sessionManager.getBranch().some((entry) => entry.type === "custom" && entry.customType === suggestionType)) saveSuggestion();
     }
     footerConfig = loadFooterConfig((message) => {
@@ -718,7 +717,6 @@ export default function (pi: ExtensionAPI) {
     const proposed = suggestion;
     if (!alive || !proposed || selectedId !== null) return false;
     if (choice === "no") {
-      offerDeclined = true;
       clearSuggestion(ctx);
       return true;
     }
@@ -757,7 +755,7 @@ export default function (pi: ExtensionAPI) {
     name: "pinote_propose",
     label: "Pinote suggest task",
     promptGuidelines: createGuidance,
-    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.",
+    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; dismissal clears only that suggestion and allows later proposals. 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 })),
@@ -773,13 +771,12 @@ export default function (pi: ExtensionAPI) {
       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() }) };
       saveSuggestion();
       previewBridge?.setSuggestion((choice) => respondToSuggestion(choice, ctx));
       ctx.ui.setStatus("pinote", suggestionStatus(ctx));
-      return result("pending; user can click ✓ to add and select or ✕ to dismiss, continue work without asking again");
+      return result("pending; user can click + to add and select or ✕ to dismiss, continue work without asking again");
     },
   });
   pi.registerTool({

package/package.json

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

package/preview-click.cjs

@@ -59,7 +59,7 @@ if (require.main === module) {
     process.exitCode = 2;
   } else {
     preview(process.argv[2]).catch(() => {
-      console.error('Pinote preview or suggestion unavailable; select a task and wait until Pi is idle.');
+      console.error('Pinote action unavailable; select a task and retry after any Pinote operation finishes. Done also requires Pi to be idle.');
       process.exitCode = 1;
     });
   }