pi-note 0.11.0 → 0.12.0

package/README.md

@@ -7,7 +7,7 @@ The extension and Python app share a repository but install separately.
 
 ## Install
 
-Requires Node.js 22.19+ and **pinote 0.3.0+** (`note` on PATH). Add and tag listing need **pinote 0.4.0+**.
+Requires Pi 0.99.1+, Node.js 22.19+ and **pinote 0.3.0+** (`note` on PATH). Add and tag listing need **pinote 0.4.0+**.
 From this checkout, install the extension with `pi install ./pi`, then run
 `/reload` in interactive Pi. Use `/pi-note-setup` if the CLI is missing, or the
 suggested `/pi-note-upgrade` if it is older than the bundled CLI. The planned npm package name is
@@ -63,14 +63,46 @@ they are not copied into the draft. The default prompt asks for a summary, not i
 Existing drafts are preserved; nothing is submitted automatically.
 With a selected task it offers **Continue**, **Done**, **Switch task**, and **Settings**.
 Press **Tab** from the task menu or picker to open global settings; Tab
-returns to tasks without saving. Settings also lists fields found on the current
+returns to tasks, keeping saved changes. Settings also lists fields found on the current
 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 the terminal's emoji font, 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 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.
+
+### Display-only preview
+
+Run `/pi-note-preview` to print the selected task's full Markdown text and saved
+agent fields in the transcript. The preview is labeled **display only · not sent
+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.
+
+On Linux, the eye is a clickable OSC 8 link to a private per-session Unix socket.
+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.
+
+```conf
+protocol pi-note-preview
+action launch --type=background node /absolute/path/to/pi-note/preview-click.cjs ${URL}
+```
+
+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
+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.
 
 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
@@ -110,10 +142,11 @@ values or unreadable/malformed configuration suppress offers; interactive startu
 warns until you fix the file and reload. No project-local configuration is read.
 
 In `/pi-note → Settings`, select **Task prompt** to edit the text inserted after
-selection or **Continue**. **Shift+Enter** or **Ctrl+J** adds a newline; **Enter** applies it to
-the settings draft, **Ctrl+C** clears it, and **Esc** cancels that edit. Select **Save settings** to
-persist it globally; leaving Settings with **Esc** or **Tab** discards the draft.
-Saving never changes existing editor input or submits anything.
+selection or **Continue**. **Shift+Enter** or **Ctrl+J** adds a newline; **Enter** saves it
+globally, **Ctrl+C** clears the edit, and **Esc** cancels that unfinished edit.
+Settings and fields save automatically after each confirmed change; no separate
+Save action is needed. Leaving Settings with **Esc** or **Tab** keeps saved changes
+and discards only unfinished input. Saving never changes existing editor input or submits anything.
 
 Task selection and **Continue** reread `handoffPrompt` each time; changing that
 field needs no `/reload`. Its value is literal text, not a prompt template; use
@@ -197,7 +230,7 @@ Add `footer` to `~/.pi/agent/pi-note.json` (or `pi-note.json` under
 }
 ```
 
-Widths are terminal columns, including icons/tags or field labels, and must be
+Widths are terminal columns, including the eye, 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`.
@@ -209,9 +242,12 @@ accepted. Missing/blank values do not display and do not consume the field limit
 In `/pi-note → Settings`, **Add field** adds a global display definition, not a
 task value. Select any field to edit **Link**, **Label**, **Format**, and **Width**.
 Label starts as the field name; clear it for no prefix. Link off displays plain
-text without a clickable link. **Save** persists the draft; cancellation leaves
-configuration untouched. Saves include the task prompt and preserve unrelated
-settings (such as `taskOfferPolicy`) and reject configuration changes made while the dialog was open.
+text without a clickable link. Toggles, field additions/removals, and edits confirmed
+with **Enter** save immediately. **Esc** returns from a field to settings without
+undoing saved changes. Invalid edits and failed saves stay open with an error;
+failed saves leave saved values unchanged and can be retried. Saves include the task
+prompt, preserve unrelated settings (such as `taskOfferPolicy`), and reject external
+configuration changes made since opening settings or the last successful save.
 Concurrent saves use `pi-note.json.lock`; remove stale locks only when no save is
 running. Symlinked configuration must be edited manually; saves never replace the link.
 

package/footer-config.ts

@@ -90,7 +90,7 @@ export function loadFooterConfig(warn: (message: string) => void): FooterConfig
 
 // Synchronous compare-and-replace: reject edits made while the settings dialog was open,
 // preserve unrelated keys, and never leave partial JSON behind.
-export function saveFooterConfig(config: FooterConfig, expectedRaw: string | null, handoffPrompt?: string): FooterConfig {
+export function saveFooterConfig(config: FooterConfig, expectedRaw: string | null, handoffPrompt?: string) {
   const checked = parseFooterConfig({ footer: config });
   const prompt = handoffPrompt === undefined ? {} : { handoffPrompt: parseHandoffPrompt(handoffPrompt) };
   const directory = getAgentDir();
@@ -101,15 +101,17 @@ export function saveFooterConfig(config: FooterConfig, expectedRaw: string | nul
   try { descriptor = openSync(lock, "wx", 0o600); }
   catch { throw new Error("Pinote settings are locked. Retry after another save finishes; remove a stale pi-note.json.lock only when no save is running."); }
   const temp = join(directory, `.pi-note-${randomUUID()}.tmp`);
+  let raw: string;
   try {
     if (readRaw() !== expectedRaw) throw new Error("Pi-note configuration changed while settings were open. Reopen settings before saving.");
     if (lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink()) throw new Error("pi-note.json is a symlink. Edit its target manually rather than replacing the link.");
     const root = expectedRaw === null ? {} : JSON.parse(expectedRaw);
     if (!object(root)) throw new Error("Invalid pi-note configuration; expected an object.");
-    writeFileSync(temp, `${JSON.stringify({ ...root, ...prompt, footer: checked }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    raw = `${JSON.stringify({ ...root, ...prompt, footer: checked }, null, 2)}\n`;
+    writeFileSync(temp, raw, { flag: "wx", mode: 0o600 });
     renameSync(temp, path);
   } finally { rmSync(temp, { force: true }); closeSync(descriptor); rmSync(lock, { force: true }); }
-  return checked;
+  return { config: checked, raw };
 }
 
 export function effectiveFooterFields(config: FooterConfig, notes: Record<string, string> = {}): FooterField[] {

package/footer-settings.ts

@@ -44,7 +44,8 @@ export class FooterSettings {
   private knownFields: string[];
   private theme: Theme;
   private matches: Matches;
-  private done: (result: PinoteSettings | "tasks" | undefined) => void;
+  private done: (result: "tasks" | undefined) => void;
+  private save: (settings: PinoteSettings) => void;
   private requestRender: () => void;
   private index = 0;
   private field?: FooterField;
@@ -53,10 +54,12 @@ export class FooterSettings {
   private hasFocus = false;
 
   constructor(config: PinoteSettings, knownFields: string[], theme: Theme, matches: Matches,
-    done: (result: PinoteSettings | "tasks" | undefined) => void, requestRender: () => void, createEditor: () => Editor) {
+    done: (result: "tasks" | undefined) => void, requestRender: () => void, createEditor: () => Editor,
+    save: (settings: PinoteSettings) => void) {
     this.draft = structuredClone(config.footer);
     this.prompt = config.handoffPrompt;
     this.createEditor = createEditor;
+    this.save = save;
     this.draft.fields ??= [];
     this.knownFields = [...new Set(knownFields)].filter((name) => name !== "Bar");
     this.theme = theme; this.matches = matches; this.done = done; this.requestRender = requestRender;
@@ -76,6 +79,20 @@ export class FooterSettings {
   private validate(field: FooterField): FooterField {
     return parseFooterConfig({ footer: { fields: [field] } }).fields![0];
   }
+  private persist(footer = this.draft, handoffPrompt = this.prompt) {
+    const settings = { footer: parseFooterConfig({ footer }), handoffPrompt: parseHandoffPrompt(handoffPrompt) };
+    this.save(structuredClone(settings));
+    this.draft = settings.footer;
+    this.prompt = settings.handoffPrompt;
+  }
+  private persistField(field: FooterField) {
+    const candidate = this.validate(field);
+    const fields = this.draft.fields!.filter((entry) => entry.name !== candidate.name);
+    const index = this.draft.fields!.findIndex((entry) => entry.name === candidate.name);
+    fields.splice(index < 0 ? fields.length : index, 0, candidate);
+    this.persist({ ...this.draft, fields });
+    this.field = candidate;
+  }
   private edit(name: string) {
     this.field = structuredClone(this.draft.fields!.find((field) => field.name === name) ?? defaultFooterField(name));
     this.index = 0; this.error = "";
@@ -86,7 +103,7 @@ export class FooterSettings {
       action: () => this.ask(key, String(this.draft[key]), (value) => {
         const candidate = { ...this.draft, [key]: Number(value) };
         if (!value.trim()) throw new Error("Enter a number.");
-        this.draft = parseFooterConfig({ footer: candidate });
+        this.persist(candidate);
       }),
     }));
     rows.push({ label: `Task prompt: ${display(this.prompt)}`, action: () => {
@@ -101,40 +118,36 @@ export class FooterSettings {
     }
     rows.push({ label: "+ Add field", action: () => this.ask("Field name", "", (value) => {
       const field = this.validate(defaultFooterField(value));
-      this.edit(field.name);
-    }) }, { label: "Save settings", action: () => this.done({ footer: parseFooterConfig({ footer: this.draft }), handoffPrompt: parseHandoffPrompt(this.prompt) }) },
+      if (this.draft.fields!.some((entry) => entry.name === field.name)) this.edit(field.name);
+      else {
+        this.persistField(field);
+        this.index = 0;
+      }
+    }) },
     { label: "Return to tasks", action: () => this.done("tasks") });
     return rows;
   }
   private fieldRows(): Row[] {
     const field = this.field!;
     const rows: Row[] = [
-      { label: `Link: ${field.link ? "on" : "off (plain text)"}`, action: () => { field.link = !field.link; } },
+      { label: `Link: ${field.link ? "on" : "off (plain text)"}`, action: () => this.persistField({ ...field, link: !field.link }) },
       { label: `Label: ${display(field.label) || "(none)"}`, action: () => this.ask("Label (empty = no prefix)", field.label, (value) => {
-        this.field = this.validate({ ...field, label: value });
+        this.persistField({ ...field, label: value });
       }) },
       { label: `Format: ${display(field.format) || "(empty)"}`, action: () => this.ask("Format: <value>, <url>, <number>", field.format, (value) => {
-        this.field = this.validate({ ...field, format: value });
+        this.persistField({ ...field, format: value });
       }) },
       { label: `Width: ${field.width ?? `default (${this.draft.fieldWidth})`}`, action: () => this.ask("Width (empty = default)", field.width === undefined ? "" : String(field.width), (value) => {
         const candidate = { ...field };
         if (value.trim()) candidate.width = Number(value); else delete candidate.width;
-        this.field = this.validate(candidate);
+        this.persistField(candidate);
       }) },
-      { label: "Save field", action: () => {
-        const candidate = this.validate(field);
-        const fields = this.draft.fields!.filter((entry) => entry.name !== candidate.name);
-        const index = this.draft.fields!.findIndex((entry) => entry.name === candidate.name);
-        fields.splice(index < 0 ? fields.length : index, 0, candidate);
-        this.draft = parseFooterConfig({ footer: { ...this.draft, fields } });
-        this.field = undefined; this.index = 0;
-      } },
     ];
     if (this.draft.fields!.some((entry) => entry.name === field.name)) rows.push({ label: "Remove field", action: () => {
-      this.draft.fields = this.draft.fields!.filter((entry) => entry.name !== field.name);
+      this.persist({ ...this.draft, fields: this.draft.fields!.filter((entry) => entry.name !== field.name) });
       this.field = undefined; this.index = 0;
     } });
-    rows.push({ label: "Cancel field", action: () => { this.field = undefined; this.index = 0; } });
+    rows.push({ label: "Back to settings", action: () => { this.field = undefined; this.index = 0; } });
     return rows;
   }
   handleInput(data: string) {
@@ -146,7 +159,7 @@ export class FooterSettings {
         else if (this.matches(data, "tui.select.cancel")) this.editor = undefined;
         else if (this.matches(data, "tui.input.newLine")) this.editor.handleInput(data);
         else if (this.matches(data, "tui.select.confirm")) {
-          this.prompt = parseHandoffPrompt(this.editor.getExpandedText());
+          this.persist(this.draft, this.editor.getExpandedText());
           this.editor = undefined;
         } else this.editor.handleInput(data);
       } else if (this.input) {
@@ -172,10 +185,10 @@ export class FooterSettings {
     const lines = [this.theme.fg("accent", "Pinote — Global Settings"), this.theme.fg("dim", "Tasks (Tab) · Settings · Fields")];
     if (this.editor) {
       lines.push(this.theme.fg("accent", "Task prompt"), ...this.editor.render(width),
-        this.theme.fg("dim", "Enter apply · Shift+Enter/Ctrl+J newline · Ctrl+C clear · Esc cancel"));
+        this.theme.fg("dim", "Enter save · Shift+Enter/Ctrl+J newline · Ctrl+C clear · Esc cancel edit"));
     } else if (this.input) {
       lines.push(this.theme.fg("accent", this.input.heading), ...this.input.widget.render(width),
-        this.theme.fg("dim", "Enter apply to draft · Esc cancel"));
+        this.theme.fg("dim", "Enter save · Esc cancel edit"));
     } else {
       if (this.field) lines.push(this.theme.fg("accent", `Field: ${display(this.field.name)}`));
       const rows = this.field ? this.fieldRows() : this.rootRows();
@@ -184,10 +197,10 @@ export class FooterSettings {
       lines.push(...rows.slice(start, start + 8).map((row, offset) => offset + start === this.index
         ? this.theme.fg("accent", `> ${row.label}`) : `  ${row.label}`));
       if (rows.length > 8) lines.push(this.theme.fg("dim", `${this.index + 1}/${rows.length}`));
-      lines.push(this.theme.fg("dim", "↑↓ navigate · Enter edit · Esc cancel"));
+      lines.push(this.theme.fg("dim", "↑↓ navigate · Enter edit · Esc back"));
     }
     if (this.error) lines.push(this.theme.fg("error", this.error));
-    lines.push(this.theme.fg("dim", "Tab: tasks, discard draft · Save settings: persist globally"));
+    lines.push(this.theme.fg("dim", "Changes save automatically · Tab: tasks"));
     return lines.map((line) => truncateToWidth(line, width));
   }
   invalidate() { this.input?.widget.invalidate(); this.editor?.invalidate(); }

package/icons/eye.txt

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

package/index.ts

@@ -1,5 +1,5 @@
-import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Editor, truncateToWidth, type Keybinding } from "@earendil-works/pi-tui";
+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 { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
@@ -9,6 +9,7 @@ import { defaultFooterConfig, defaultHandoffPrompt, effectiveFooterFields, loadF
 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";
 
 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 = {
@@ -30,6 +31,8 @@ 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;
 const record = (value: unknown): value is Record<string, unknown> =>
@@ -115,6 +118,14 @@ function toolResult(value: Task | null) {
 
 export default function (pi: ExtensionAPI) {
   const { guidelines: createGuidance, error: offerConfigError } = creationGuidance();
+  pi.registerEntryRenderer<{ id: number; markdown: string }>(previewType, (entry, _options, theme) => {
+    if (!record(entry.data) || !validId(entry.data.id) || typeof entry.data.markdown !== "string") return;
+    const view = new Container();
+    view.addChild(new Text(theme.fg("muted", `Pinote #${entry.data.id} · display only · not sent to model`), 0, 0));
+    view.addChild(new Markdown(clean(entry.data.markdown), 0, 0, getMarkdownTheme()));
+    return view;
+  });
+  let previewBridge: ReturnType<typeof createPreviewBridge> | undefined;
   let alive = true;
   let epoch = 0;
   let refreshSerial = 0;
@@ -184,6 +195,7 @@ export default function (pi: ExtensionAPI) {
   let branchEpoch = 0;
   const remember = (id: number | null, branch = branchEpoch) => {
     if (!alive || branch !== branchEpoch || selectedId === id) return;
+    previewBridge?.invalidate();
     selectedId = id;
     pi.appendEntry(selectionType, { id });
   };
@@ -238,11 +250,20 @@ export default function (pi: ExtensionAPI) {
     try {
       const current = await selected(ctx);
       if (alive && generation === epoch && serial === refreshSerial) {
-        ctx.ui.setStatus("pinote", current ? truncateToWidth(`${noteIcon} ${taskTag(current)} ${firstLine(current)}`, footerConfig.titleWidth, "...") : undefined);
+        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();
+        // 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);
         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"}`);
       }
     }
@@ -265,14 +286,57 @@ export default function (pi: ExtensionAPI) {
     },
     refresh,
   });
+  const preview = async (ctx: ExtensionContext, requestSignal?: AbortSignal): Promise<boolean> => {
+    if (!ctx.hasUI || ctx.mode !== "tui" || !ctx.isIdle() || pending || !validId(selectedId)) return false;
+    const generation = epoch;
+    const branch = branchEpoch;
+    const id = selectedId;
+    const operation = Symbol();
+    pending = operation;
+    // 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() &&
+      !signal.aborted && Date.now() < deadline;
+    try {
+      const current = await currentTask(signal, canUse);
+      if (!current || !canUse()) return false;
+      // Custom entries are rendered locally, never conversation messages or compaction input.
+      pi.appendEntry(previewType, { id: current.id, markdown: current.markdown });
+      return true;
+    } catch (error) {
+      if (canUse()) ctx.ui.notify(`Pinote preview: ${clean(String(error))}`, "error");
+      return false;
+    } finally {
+      clearTimeout(timer);
+      if (pending === operation) pending = undefined;
+    }
+  };
+  pi.registerCommand("pi-note-preview", {
+    description: "Display the selected task locally without sending it to the model",
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI || ctx.mode !== "tui") return;
+      if (args.trim()) { ctx.ui.notify("Usage: /pi-note-preview", "warning"); return; }
+      if (!await preview(ctx)) ctx.ui.notify("Select a task with /pi-note and wait until Pi is idle before previewing.", "warning");
+    },
+  });
   pi.on("session_start", async (_event, ctx) => {
     setupAbort?.abort();
-    alive = true;
-    activeContext = ctx;
+    // Retire old polling before bridge teardown/startup yields to its scheduled callbacks.
+    watcher.stop();
+    alive = false;
     epoch++;
     branchEpoch++;
-    selectedId = readSelection(ctx);
     const generation = epoch;
+    const previousBridge = previewBridge;
+    previewBridge = undefined;
+    if (previousBridge) await previousBridge.stop();
+    if (generation !== epoch) return;
+    alive = true;
+    activeContext = ctx;
+    selectedId = readSelection(ctx);
     footerConfig = loadFooterConfig((message) => {
       if (ctx.hasUI) ctx.ui.notify(message, "warning");
     });
@@ -281,6 +345,18 @@ export default function (pi: ExtensionAPI) {
       if (offerConfigError) ctx.ui.notify(`Pinote task offers disabled: ${clean(offerConfigError)} Fix the configuration and /reload.`, "warning");
       ctx.ui.addAutocompleteProvider((current) => cliMenu(current, () => setupAbort ? undefined : cliState));
     }
+    if (ctx.hasUI && ctx.mode === "tui") {
+      const bridge = createPreviewBridge();
+      previewBridge = bridge;
+      try {
+        await bridge.start();
+      } catch {
+        await bridge.stop();
+        if (previewBridge === bridge) previewBridge = undefined;
+        ctx.ui.notify("Pinote eye link unavailable; use /pi-note-preview.", "warning");
+      }
+    }
+    if (!alive || generation !== epoch) return;
     // Keep the setup lock until its aborted subprocess has actually settled.
     if (!setupAbort) pending = undefined;
     await checkCLI(ctx, true);
@@ -291,6 +367,7 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_tree", async (_event, ctx) => {
     if (!alive) return;
     branchEpoch++;
+    previewBridge?.invalidate();
     const generation = branchEpoch;
     const id = readSelection(ctx);
     if (!alive || generation !== branchEpoch) return;
@@ -300,7 +377,7 @@ export default function (pi: ExtensionAPI) {
   });
   pi.on("before_agent_start", async (_event, ctx) => { await refresh(ctx); });
   pi.on("agent_end", async (_event, ctx) => { await refresh(ctx); });
-  pi.on("session_shutdown", (_event, ctx) => {
+  pi.on("session_shutdown", async (_event, ctx) => {
     setupAbort?.abort();
     alive = false;
     activeContext = undefined;
@@ -310,6 +387,9 @@ export default function (pi: ExtensionAPI) {
     refreshSerial++;
     watcher.stop();
     if (ctx.hasUI && ctx.mode === "tui") ctx.ui.setStatus("pinote", undefined);
+    const bridge = previewBridge;
+    previewBridge = undefined;
+    if (bridge) await bridge.stop();
   });
 
   const registerInstallCommand = (name: "pi-note-setup" | "pi-note-upgrade") => pi.registerCommand(name, {
@@ -380,7 +460,8 @@ export default function (pi: ExtensionAPI) {
               footer: { ...document.config, fields: effectiveFooterFields(document.config, current?.agent_notes) },
               handoffPrompt: "handoffPrompt" in root ? parseHandoffPrompt(root.handoffPrompt) : defaultHandoffPrompt,
             };
-            const edited = await ctx.ui.custom<PinoteSettings | "tasks" | undefined>((tui, theme, kb, done) =>
+            let expectedRaw = document.raw;
+            const edited = await ctx.ui.custom<"tasks" | undefined>((tui, theme, kb, done) =>
               new FooterSettings(config, Object.keys(current?.agent_notes ?? {}).filter((name) => name !== "Bar"),
                 theme, (data, action) => kb.matches(data, action as Keybinding), done, () => tui.requestRender(),
                 () => new Editor(tui, {
@@ -388,12 +469,16 @@ export default function (pi: ExtensionAPI) {
                   selectList: { selectedPrefix: (line) => theme.fg("accent", line), selectedText: (line) => theme.fg("accent", line),
                     description: (line) => theme.fg("muted", line), scrollInfo: (line) => theme.fg("dim", line),
                     noMatch: (line) => theme.fg("warning", line) },
-                })));
+                }), (updated) => {
+                  if (!canAct()) throw new Error("This session changed. Reopen settings before editing.");
+                  const saved = saveFooterConfig(updated.footer, expectedRaw, updated.handoffPrompt);
+                  expectedRaw = saved.raw;
+                  footerConfig = saved.config;
+                  void refresh(ctx);
+                }));
             if (!canAct() || edited === undefined) return;
-            if (edited === "tasks") { settings = false; continue; }
-            footerConfig = saveFooterConfig(edited.footer, document.raw, edited.handoffPrompt);
-            ctx.ui.notify("Global Pinote settings saved.", "info");
-            return;
+            settings = false;
+            continue;
           }
           const action = current
             ? await ctx.ui.custom<string | undefined>((tui, theme, kb, done) =>

package/kitty/open-actions.conf

@@ -0,0 +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.
+protocol pi-note-preview
+action launch --type=background node /absolute/path/to/pi-note/preview-click.cjs ${URL}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-note",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Persistent pinote tasks, Markdown handoffs, and task status for Pi",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,7 @@
   "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", "icons", "README.md", "LICENSE"],
+  "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"] },
   "scripts": {
     "check": "tsc --noEmit",

package/preview-bridge.ts

@@ -0,0 +1,113 @@
+import { randomBytes } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { createServer, type Server, type Socket } from "node:net";
+import { basename, join } from "node:path";
+
+// No note data travels through the socket or hyperlink; both identify a local selection.
+export function createPreviewBridge() {
+  const uid = process.getuid?.();
+  const capability = randomBytes(16).toString("hex");
+  let server: Server | undefined;
+  let socketPath: string | undefined;
+  let starting: Promise<void> | undefined;
+  let stopping: Promise<void> | undefined;
+  let closed = false;
+  let ready = false;
+  let taskId: number | null = null;
+  let callback: ((signal: AbortSignal) => Promise<boolean>) | undefined;
+  let nonce: string | undefined;
+  const clients = new Set<Socket>();
+  const invalidate = () => { taskId = null; callback = undefined; nonce = undefined; };
+  const cleanup = async () => {
+    ready = false;
+    for (const client of clients) client.destroy();
+    const instance = server;
+    server = undefined;
+    if (instance) await new Promise<void>((resolve) => instance.close(() => resolve()));
+    const file = socketPath;
+    socketPath = undefined;
+    if (file) {
+      try {
+        const st = await fs.lstat(file);
+        if (st.isSocket() && st.uid === uid) await fs.unlink(file);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      }
+    }
+  };
+  const api = {
+    async start(): Promise<void> {
+      if (closed || uid === undefined) throw new Error("Preview bridge unavailable");
+      if (starting) return starting;
+      starting = (async () => {
+        const dir = `/tmp/pi-note-preview-${uid}`;
+        await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+        const st = await fs.lstat(dir);
+        if (!st.isDirectory() || st.uid !== uid || (st.mode & 0o777) !== 0o700 || closed) {
+          throw new Error("Preview bridge unavailable");
+        }
+        socketPath = join(dir, `${process.pid}-${randomBytes(4).toString("hex")}.sock`);
+        const instance = createServer((client) => {
+          clients.add(client);
+          const request = new AbortController();
+          client.on("error", () => client.destroy());
+          client.on("close", () => { request.abort(); clients.delete(client); });
+          client.setTimeout(5000, () => { request.abort(); client.destroy(); });
+          let data = Buffer.alloc(0);
+          let dispatched = false;
+          client.on("data", (chunk) => {
+            if (dispatched || closed) return;
+            data = Buffer.concat([data, chunk]);
+            if (data.length > 128) { client.destroy(); return; }
+            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"); });
+          });
+        });
+        server = instance;
+        try {
+          await new Promise<void>((resolve, reject) => {
+            instance.once("error", reject);
+            instance.listen(socketPath!, resolve);
+          });
+          await fs.chmod(socketPath, 0o600);
+          if (closed) throw new Error("Preview bridge unavailable");
+          instance.on("error", () => { void api.stop().catch(() => {}); });
+          instance.unref();
+          ready = true;
+        } catch {
+          await cleanup();
+          throw new Error("Preview bridge unavailable");
+        }
+      })();
+      return starting;
+    },
+    setTask(id: number | null, preview: (signal: AbortSignal) => 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");
+      taskId = id;
+      callback = id === null ? undefined : preview;
+    },
+    invalidate,
+    url(): string | undefined {
+      if (!ready || closed || !socketPath || taskId === null || !nonce) return;
+      return `pi-note-preview://${basename(socketPath, ".sock")}/${capability}/${taskId}/${nonce}`;
+    },
+    async stop(): Promise<void> {
+      closed = true;
+      invalidate();
+      if (!stopping) stopping = (async () => { await starting?.catch(() => {}); await cleanup(); })();
+      return stopping;
+    },
+  };
+  return api;
+}

package/preview-click.cjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+'use strict';
+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})$/;
+
+function parse(value) {
+  if (typeof value !== 'string' || value.length > 160) throw new Error('Preview unavailable');
+  const m = urlPattern.exec(value);
+  if (!m || m[0] !== value) throw new Error('Preview 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] };
+}
+function socketPathFor(value) {
+  const p = parse(value);
+  return path.join(`/tmp/pi-note-preview-${typeof process.getuid === 'function' ? process.getuid() : -1}`, `${p.pid}-${p.tag}.sock`);
+}
+function verify(file) {
+  const uid = typeof process.getuid === 'function' ? process.getuid() : -1;
+  if (uid < 0) throw new Error('Preview unavailable');
+  const dir = `/tmp/pi-note-preview-${uid}`;
+  const ds = fs.lstatSync(dir);
+  if (!ds.isDirectory() || ds.isSymbolicLink() || ds.uid !== uid || (ds.mode & 0o777) !== 0o700) throw new Error('Preview unavailable');
+  const ss = fs.lstatSync(file);
+  if (!ss.isSocket() || ss.isSymbolicLink() || ss.uid !== uid || (ss.mode & 0o777) !== 0o600) throw new Error('Preview unavailable');
+}
+function preview(value) {
+  let p, file;
+  try { p = parse(value); file = socketPathFor(value); verify(file); }
+  catch { return Promise.reject(new Error('Preview unavailable')); }
+  return new Promise((resolve, reject) => {
+    const client = net.createConnection(file);
+    let response = Buffer.alloc(0), done = false;
+    const finish = (err, result) => {
+      if (done) return;
+      done = true; clearTimeout(timer); client.destroy();
+      err ? reject(new Error('Preview unavailable')) : resolve(result);
+    };
+    const timer = setTimeout(() => finish(new Error()), 6000);
+    client.on('connect', () => client.write(`preview ${p.capability} ${p.id} ${p.nonce}\n`));
+    client.on('data', chunk => {
+      response = Buffer.concat([response, chunk]);
+      if (response.length > 64) return finish(new Error());
+      const text = response.toString('utf8');
+      if (text.includes('\n')) finish(text === 'accepted\n' ? null : new Error(), text === 'accepted\n');
+    });
+    client.on('error', () => finish(new Error()));
+    client.on('end', () => { if (!done) finish(new Error()); });
+  });
+}
+if (require.main === module) {
+  if (process.argv.length !== 3) {
+    console.error('Usage: preview-click.cjs <preview URL>');
+    process.exitCode = 2;
+  } else {
+    preview(process.argv[2]).catch(() => {
+      console.error('Pinote preview unavailable; select a task and wait until Pi is idle.');
+      process.exitCode = 1;
+    });
+  }
+}
+module.exports = { preview, socketPathFor };