pi-note 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kvidzibo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# pi-note
+
+Persistent [pinote](https://github.com/kvidzibo/pinote) tasks and Markdown handoffs
+in Pi: selected-task footer status, `/pi-note`, and agent read/update tools.
+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).
+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
+`pi-note`; after its first release use `pi install npm:pi-note` instead.
+It is not published yet. npm installation does not run Python installers.
+
+### CLI setup and upgrades
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) first and
+restart Pi with `uv` on PATH. At startup the extension checks `note --version`
+against its bundled CLI version (currently 0.3.0), without network requests:
+
+- Missing/unrecognized CLI: show `/pi-note-setup` in the slash-command menu.
+- Older CLI: show and suggest `/pi-note-upgrade`.
+- Equal/newer CLI: hide both commands; no upgrade notification.
+
+Both commands ask before installing into uv's isolated tool environment.
+The menu refreshes after setup/upgrade; restart Pi or `/reload` after external
+CLI changes. Manually typing either command rechecks the version and never
+reinstalls an equal/newer CLI or intentionally downgrades it.
+Python 3.11+ is required; uv can download a suitable interpreter when missing.
+The command downloads a pinned GitHub source archive and build dependencies,
+not a similarly named PyPI package. It does not install GTK dependencies, edit
+shell configuration, or change tasks. This checks the Python CLI bundled with
+the installed extension, not the latest npm/GitHub release. Update the extension
+first to receive a newer bundled CLI. `/pi-note-setup --upgrade` is replaced by
+`/pi-note-upgrade`.
+
+Back up your database before upgrading and update an optional GUI separately.
+For checkout development, use `uv tool install --reinstall .` at the repo root
+instead, so local Python changes are installed.
+
+If setup reports a PATH problem, run `uv tool dir --bin` in your terminal,
+put that directory before older `note` executables on PATH, and restart Pi.
+Check `note --version`, then restart Pi or `/reload`. Network/build failures and
+conflicting executables are reported without forcibly overwriting another
+installer's commands. Fix the reported cause and retry; installs time out after
+three minutes. Setup/upgrade commands are hidden while installation runs.
+Missing uv is reported with its installation link, not installed
+automatically. The [GTK desktop app](../README.md#optional-gtk-checklist) is optional
+and still requires separate system dependencies.
+
+The extension probes `note --version` before task commands: older CLIs interpret
+unknown commands as note text and must be rejected before use. Remove the old
+standalone `settings/pi/extensions/pinote.ts` entry if installed; load only one copy.
+
+## Use
+
+`/pi-note` picks a task, starts it, and puts its full text and saved handoff fields
+in the editor. Existing drafts are preserved; nothing is submitted automatically.
+With a selected task it offers **Continue**, **Done**, and **Switch 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 60 terminal columns including the pin and tag.
+The pin glyph is bundled in `icons/note.txt`; it uses the terminal's emoji font, not a Nerd Font or icon theme.
+
+Selection is stored per canonical working directory in pinote's database. A new
+Pi session shows that selection; use **Continue** to load its current contents.
+Completing, removing, or scheduling a task clears its selections. Switching does
+not complete or reset the previous task. Task status refreshes at session start,
+before/after agent activity, and after commands/tools.
+
+Agent tools:
+
+- `pinote_get`: read the selected task, or an explicit `id`, including its revision.
+- `pinote_update`: supply `id`, `expected_updated_at` from that read, and arbitrary
+  `set` label/value pairs or `remove` labels. Updates merge fields, never replace
+  the task text. If another process changed the task, read again before retrying.
+
+Agents are guided to keep notes to three short bullets total: relevant outcome,
+blocker, and next action. Replace stale notes; omit narration, repeated task text,
+and routine test logs. Keep PR links in `PR`. This is guidance, not truncation or
+a storage limit.
+
+Values are Markdown strings; no fields are required. `PR` enables the watcher below:
+
+```markdown
+# Agent
+PR: [Task selection #42](https://github.com/org/repo/pull/42)
+Jira: [PROJ-123](https://example.atlassian.net/browse/PROJ-123)
+CWD: `/home/me/project`
+Next: Address review comments
+```
+
+The GTK preview renders this section using its existing safe Markdown renderer.
+Fields are stored separately from task text, retained in history, and survive
+sessions. Labels are case-sensitive (trimmed, Unicode-normalized), at most 64
+characters; values are at most 4096 characters. Maximum 64 fields / 32 KiB JSON
+per task. Use removal rather than empty values.
+
+### PR merge watcher
+
+Set `PR` with `pinote_update` to one `https://github.com/owner/repo/pull/123` URL
+or Markdown link. The footer adds a clickable, link-coloured **PR #123**, without
+status text. Other hosts, multiple links, and prose are not watched. Terminal
+OSC 8 support is required for clicking links.
+
+Interactive Pi checks only the selected task's PR using authenticated `gh`
+(`gh auth login`). Polling defaults to 60 seconds; launch Pi with
+`PINOTE_PR_POLL_SECONDS=120 pi` to change it, or `0` to disable polling.
+Allowed intervals are 10–86400 seconds. The selected task's link remains visible when polling is disabled.
+Network/authentication failures warn once until recovery and retry next interval.
+No polling runs in print/RPC mode or after Pi exits.
+
+On merge, Pi waits until idle and asks **Mark this task completed?** Confirmation
+uses the same guarded CLI Done operation as `/pi-note`; declining leaves the task
+unchanged. If it is already done, Pi says **PR #123 was merged and the task is
+already completed**, without completing it again. Completion clears the selection
+and hides the footer link, even with polling disabled. The background watch remains
+until another task is selected, the link is removed, or Pi exits. Removed/scheduled tasks are no longer watched.
+
+The watched task ID/link and merge acknowledgements are saved in the Pi session,
+so `/reload` and session resume retain completed-task watches without repeating
+acknowledged prompts. A new session can notify again for a
+selected task. Task or PR changes during confirmation cannot complete a different
+task. No completion-hook system is added; this uses Pinote's existing Done flow.
+A separate branch-based PR-status extension may show a duplicate link; disable it
+if you only want task-linked PRs.
+
+Task data stays local except for GitHub status requests. Tools work without a TUI,
+but `/pi-note` needs an idle TUI.
+This package does not synchronize databases or paths between machines. Note text
+and fields loaded into Pi are sent to the configured model when used as context;
+avoid secrets. Agent commands do not send desktop notifications.
+
+## Development and releases
+
+From the repository root:
+
+```sh
+uv sync --locked
+npm --prefix pi ci --ignore-scripts
+npm --prefix pi test
+(cd pi && npm pack --dry-run)
+```
+
+The load test uses the real Pi loader and checkout's `.venv/bin/note` with temporary
+data. Run visual checks under Xvfb/private D-Bus; never use personal task data.
+
+`.github/workflows/publish.yml` follows the other Pi packages: every push to
+`main` runs the full Python/GTK/Pi tests, then publishes a new npm version using
+OIDC trusted publishing and provenance. Existing versions are skipped; registry
+failures fail the workflow. No npm token is stored in GitHub.
+
+One-time maintainer setup (not performed by installing this package):
+
+1. From `pi/`, run `npm login`, then `npm publish --ignore-scripts --access public`
+   to bootstrap `pi-note` after checking name availability.
+2. In npm's package settings configure the GitHub trusted publisher: owner
+   `kvidzibo`, repository `pinote`, workflow `publish.yml`, no environment.
+3. Add verified npm and Pi package-directory links here after publication.
+
+The CLI source pin in `setup.ts` must point to a verified immutable commit with a
+compatible Python package. Update it and the bundled-version setup text together
+when releasing Python changes; verify installation in a temporary uv tool directory.
+
+Subsequent releases: run `npm version patch|minor|major --no-git-tag-version`
+inside `pi/`, commit both version files in a PR, and merge through the normal
+review/check process. Python and npm versions are independent; update the stated
+minimum CLI version whenever the integration contract changes.

package/icons/note.txt

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

package/index.ts

@@ -0,0 +1,324 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { readFileSync } from "node:fs";
+import { stripVTControlCharacters } from "node:util";
+import { Type } from "typebox";
+import { createPRWatcher } from "./pr-watch.ts";
+import { TaskPicker, taskState, taskTag } from "./task-picker.ts";
+import { bundledCLIVersion, cliMenu, detectCLI, compatibleVersion, setupCLI, setupHint, type CLIAction } from "./setup.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 PR links in the separate PR field.";
+type Task = {
+  id: number;
+  text: string;
+  state: "active" | "in_progress" | "done" | "removed" | "scheduled";
+  tag: string | null;
+  updated_at: string;
+  agent_notes: Record<string, string>;
+  markdown: string;
+};
+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 idSchema = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
+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> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+const text = (value: unknown): value is string =>
+  typeof value === "string" && !/[\x00-\x08\x0b-\x1f\x7f-\x9f]/u.test(value);
+const clean = (value: string) => stripVTControlCharacters(value).replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/gu, "�");
+const firstLine = (task: Summary) => clean(task.text.split("\n", 1)[0]).replace(/\s+/gu, " ").trim();
+const title = (task: Summary) => truncateToWidth(`#${task.id} ${firstLine(task)}`, 60);
+
+function parse(raw: string): unknown {
+  try { return JSON.parse(raw); } catch { throw new Error(compatible); }
+}
+function task(raw: string): Task | null {
+  const value = parse(raw);
+  if (value === null) return null;
+  if (!record(value) || !validId(value.id) || !text(value.text) || !value.text.trim() ||
+      typeof value.state !== "string" || !["active", "in_progress", "done", "removed", "scheduled"].includes(value.state) ||
+      !(value.tag === null || text(value.tag)) || !text(value.updated_at) || !value.updated_at.trim() ||
+      !record(value.agent_notes) || !Object.entries(value.agent_notes).every(([key, v]) => text(key) && text(v)) ||
+      !text(value.markdown)) throw new Error(compatible);
+  return value as Task;
+}
+function requiredTask(raw: string, id?: number): Task {
+  const value = task(raw);
+  if (!value) throw new Error("No selected pinote task. Select one with /pi-note first.");
+  if (id !== undefined && value.id !== id) throw new Error(compatible);
+  return value;
+}
+function taskList(raw: string): Summary[] {
+  const value = parse(raw);
+  if (!Array.isArray(value) || !value.every((v) => record(v) && validId(v.id) && text(v.text) &&
+      v.text.trim() && (v.tag === null || text(v.tag)) &&
+      typeof v.state === "string" && ["active", "in_progress"].includes(v.state))) throw new Error(compatible);
+  return value.sort((a, b) => b.id - a.id);
+}
+
+function toolResult(value: Task) {
+  // Keep the model payload under 50 KiB at the CLI's limits; don't send the same fields twice.
+  const { markdown: _markdown, ...data } = value;
+  return { content: [{ type: "text" as const, text: JSON.stringify(data) }], details: value };
+}
+
+export default function (pi: ExtensionAPI) {
+  let alive = true;
+  let epoch = 0;
+  let refreshSerial = 0;
+  let pending: symbol | undefined;
+  let setupAbort: AbortController | undefined;
+  let activeContext: ExtensionContext | undefined;
+  let cliState: CLIAction | undefined;
+  const checkCLI = async (ctx: ExtensionContext, suggest = false) => {
+    if (!ctx.hasUI || ctx.mode !== "tui" || setupAbort) return;
+    const generation = epoch;
+    const action = await detectCLI(pi);
+    if (!alive || generation !== epoch || setupAbort) return;
+    cliState = action;
+    if (suggest && action === "upgrade") {
+      ctx.ui.notify(`Pinote CLI ${bundledCLIVersion} is bundled with this extension. Run /pi-note-upgrade to update your older CLI.`, "info");
+    }
+  };
+
+  const invoke = async (argv: string[], signal?: AbortSignal) => {
+    signal?.throwIfAborted();
+    let result;
+    try {
+      result = await pi.exec("note", argv, { timeout: 5000, signal });
+    } catch (error) {
+      throw new Error(`Pinote CLI unavailable: ${clean(String(error))}. ${setupHint}`);
+    }
+    if (result.killed || result.code !== 0) {
+      const detail = clean((result.stderr || result.stdout || "note failed or timed out").trim());
+      throw new Error(`${detail}${argv[0] === "--version" ? ` ${setupHint}` : result.killed ? " Read the task before retrying; a write may have committed." : ""}`);
+    }
+    return result.stdout;
+  };
+  const run = async (argv: string[], signal?: AbortSignal, canRun = () => true) => {
+    if (setupAbort) throw new Error("Pinote CLI setup is still running. Retry after it finishes.");
+    // Old pinote treats unknown commands as note text. Probe safely before every call,
+    // including tools in headless sessions, and do not cache across CLI upgrades/downgrades.
+    const version = (await invoke(["--version"], signal)).trim();
+    if (!compatibleVersion(version)) {
+      throw new Error(`pi-note requires pinote 0.3.0+; found ${clean(version) || "an unknown CLI"}. ${setupHint}`);
+    }
+    if (!canRun()) throw new Error("Pinote operation cancelled: the session changed.");
+    return invoke(argv, signal);
+  };
+  const selected = async (ctx: ExtensionContext, signal?: AbortSignal) =>
+    task(await run(["agent", "selected", "--cwd", ctx.cwd], signal));
+
+  const refresh = async (ctx: ExtensionContext) => {
+    if (!alive || setupAbort || !ctx.hasUI || ctx.mode !== "tui") return;
+    const generation = epoch;
+    const serial = ++refreshSerial;
+    try {
+      const current = await selected(ctx);
+      if (alive && generation === epoch && serial === refreshSerial) {
+        ctx.ui.setStatus("pinote", current ? truncateToWidth(`${noteIcon} ${taskTag(current)} ${firstLine(current)}`, 60) : undefined);
+        watcher.update(ctx, current);
+      }
+    } catch {
+      if (alive && generation === epoch && serial === refreshSerial) {
+        ctx.ui.setStatus("pinote", `${noteIcon} Pinote unavailable · ${cliState === "upgrade" ? "/pi-note-upgrade" : cliState === "setup" ? "/pi-note-setup" : "/pi-note"}`);
+      }
+    }
+  };
+  const watcher = createPRWatcher(pi, {
+    selected,
+    get: async (id) => requiredTask(await run(["agent", "get", String(id)]), id),
+    done: async (current, canAct) => {
+      const result = requiredTask(await run([
+        "agent", "done", String(current.id), "--expected-updated-at", current.updated_at,
+      ], undefined, canAct), current.id);
+      if (result.state !== "done") throw new Error(compatible);
+    },
+    claim: () => {
+      if (pending) return;
+      const operation = Symbol();
+      pending = operation;
+      return () => { if (pending === operation) pending = undefined; };
+    },
+    refresh,
+  });
+  pi.on("session_start", async (_event, ctx) => {
+    setupAbort?.abort();
+    alive = true;
+    activeContext = ctx;
+    epoch++;
+    const generation = epoch;
+    cliState = undefined;
+    if (ctx.hasUI && ctx.mode === "tui") {
+      ctx.ui.addAutocompleteProvider((current) => cliMenu(current, () => setupAbort ? undefined : cliState));
+    }
+    // Keep the setup lock until its aborted subprocess has actually settled.
+    if (!setupAbort) pending = undefined;
+    await checkCLI(ctx, true);
+    if (!alive || generation !== epoch) return;
+    if (!setupAbort) watcher.start(ctx);
+    await refresh(ctx);
+  });
+  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) => {
+    setupAbort?.abort();
+    alive = false;
+    activeContext = undefined;
+    epoch++;
+    refreshSerial++;
+    watcher.stop();
+    if (ctx.hasUI && ctx.mode === "tui") ctx.ui.setStatus("pinote", undefined);
+  });
+
+  const registerInstallCommand = (name: "pi-note-setup" | "pi-note-upgrade") => pi.registerCommand(name, {
+    description: name === "pi-note-setup" ? "Install the missing Python CLI with uv" : "Upgrade an older Python CLI to the bundled version",
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI || ctx.mode !== "tui") return;
+      if (args.trim()) {
+        ctx.ui.notify(`Usage: /${name}`, "warning");
+        return;
+      }
+      if (pending || !ctx.isIdle()) {
+        ctx.ui.notify("Wait until Pi is idle and the pinote operation has finished.", "warning");
+        return;
+      }
+      const operation = Symbol();
+      pending = operation;
+      const generation = epoch;
+      const controller = new AbortController();
+      setupAbort = controller;
+      watcher.stop();
+      const currentSession = () => alive && generation === epoch;
+      try {
+        await setupCLI(pi, ctx, name === "pi-note-upgrade",
+          () => currentSession() && ctx.isIdle(), controller.signal);
+      } catch (error) {
+        if (currentSession()) ctx.ui.notify(`Pinote setup: ${clean(String(error))}`, "error");
+      } finally {
+        if (pending === operation) pending = undefined;
+        if (setupAbort === controller) setupAbort = undefined;
+        const latestContext = activeContext ?? (currentSession() ? ctx : undefined);
+        if (alive && latestContext) {
+          const generation = epoch;
+          await checkCLI(latestContext, !currentSession());
+          if (!alive || generation !== epoch || setupAbort) return;
+          watcher.start(latestContext);
+          await refresh(latestContext);
+        }
+      }
+    },
+  });
+  registerInstallCommand("pi-note-setup");
+  registerInstallCommand("pi-note-upgrade");
+
+  pi.registerCommand("pi-note", {
+    description: "Continue, complete, or switch the selected pinote task",
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI || ctx.mode !== "tui") return;
+      if (args.trim()) { ctx.ui.notify("Usage: /pi-note", "warning"); return; }
+      if (pending || !ctx.isIdle()) {
+        ctx.ui.notify("Wait until Pi is idle and the pinote operation has finished.", "warning");
+        return;
+      }
+      const operation = Symbol();
+      pending = operation;
+      const generation = epoch;
+      const currentSession = () => alive && generation === epoch;
+      const canAct = () => currentSession() && ctx.isIdle();
+      try {
+        const current = await selected(ctx);
+        if (!canAct()) return;
+        const action = current
+          ? await ctx.ui.select(`Pinote — ${taskState(current)} ${taskTag(current)} ${title(current)}`, ["Continue", "Done", "Switch task"])
+          : "Switch task";
+        if (!action || !canAct()) return;
+        if (action === "Done" && current) {
+          refreshSerial++;
+          const completed = requiredTask(await run([
+            "agent", "done", String(current.id), "--expected-updated-at", current.updated_at,
+          ], undefined, canAct), current.id);
+          if (completed.state !== "done") throw new Error(compatible);
+          if (currentSession()) ctx.ui.notify(`Pinote #${current.id} completed.`, "info");
+          return;
+        }
+        let id: number;
+        if (action === "Continue" && current) {
+          id = current.id;
+        } else if (action === "Switch task") {
+          const tasks = taskList(await run(["list", "--json"]));
+          if (!canAct()) return;
+          if (!tasks.length) { ctx.ui.notify("No active pinote tasks.", "info"); return; }
+          const choice = await ctx.ui.custom<number | undefined>((tui, theme, kb, done) =>
+            new TaskPicker(tasks, theme, (data, action) => kb.matches(data, action), done, () => tui.requestRender()));
+          if (choice === undefined || !canAct()) return;
+          id = choice;
+        } else return;
+        // Validate/start the explicit task and return its latest handoff in one transaction.
+        refreshSerial++;
+        const chosen = requiredTask(await run(["agent", "select", String(id), "--cwd", ctx.cwd], undefined, canAct), id);
+        if (!canAct()) return;
+        const draft = ctx.ui.getEditorText();
+        const handoff = `Pinote task #${chosen.id} (revision ${chosen.updated_at}).\n` +
+          "Use pinote_get to read current task data and pinote_update to save agent handoff fields.\n" +
+          handoffGuidance + "\n\n" + chosen.markdown;
+        ctx.ui.setEditorText(draft ? `${draft}\n\n${handoff}` : handoff);
+        ctx.ui.notify(`Pinote #${chosen.id} is in progress. Task added to input.`, "info");
+      } catch (error) {
+        if (currentSession()) ctx.ui.notify(`Pinote: ${clean(error instanceof Error ? error.message : String(error))}`, "error");
+      } finally {
+        if (pending === operation) pending = undefined;
+        if (currentSession()) await refresh(ctx);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "pinote_get",
+    label: "Pinote get",
+    description: "Read a pinote task and its Markdown agent fields/revision. Omit id to read this project's selected task; supply id to read another task. Use the returned updated_at for pinote_update.",
+    parameters: Type.Object({ id: Type.Optional(idSchema) }),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (params.id !== undefined && !validId(params.id)) throw new Error("id must be a positive safe integer.");
+      const argv = params.id === undefined
+        ? ["agent", "selected", "--cwd", ctx.cwd]
+        : ["agent", "get", String(params.id)];
+      const result = requiredTask(await run(argv, signal), params.id);
+      return toolResult(result);
+    },
+  });
+  pi.registerTool({
+    name: "pinote_update",
+    label: "Pinote update",
+    promptGuidelines: [handoffGuidance],
+    description: "Patch arbitrary agent handoff fields on an explicit pinote task. Read first with pinote_get; pass its updated_at as expected_updated_at. set merges label/value pairs without replacing other fields or task text; values are Markdown, e.g. PR: [Fix #42](https://github.com/org/repo/pull/42). Set PR to one GitHub pull-request URL or Markdown link to show it in the footer and watch for merge confirmation in interactive Pi. remove deletes named fields. A stale revision fails; read again before retrying. Does not complete the task.",
+    parameters: Type.Object({
+      id: idSchema,
+      expected_updated_at: Type.String({ minLength: 1 }),
+      set: Type.Optional(Type.Record(Type.String(), Type.String())),
+      remove: Type.Optional(Type.Array(Type.String())),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (!validId(params.id) || !text(params.expected_updated_at) || !params.expected_updated_at.trim()) {
+        throw new Error("id and expected_updated_at are required; read the task first.");
+      }
+      if (pending) throw new Error("A pinote operation is already open. Retry after it finishes.");
+      const operation = Symbol();
+      pending = operation;
+      const generation = epoch;
+      refreshSerial++;
+      try {
+        const argv = ["agent", "update", String(params.id), "--expected-updated-at", params.expected_updated_at,
+          "--set-json", JSON.stringify(params.set ?? {})];
+        for (const label of params.remove ?? []) argv.push(`--remove=${label}`);
+        const result = requiredTask(await run(argv, signal, () => alive && generation === epoch), params.id);
+        return toolResult(result);
+      } finally {
+        if (pending === operation) pending = undefined;
+        if (alive && generation === epoch) await refresh(ctx);
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pi-note",
+  "version": "0.4.0",
+  "description": "Persistent pinote tasks, Markdown handoffs, and task status for Pi",
+  "license": "MIT",
+  "type": "module",
+  "keywords": ["pi-package", "tasks", "notes"],
+  "engines": { "node": ">=22.19.0" },
+  "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", "task-picker.ts", "setup.ts", "icons", "README.md", "LICENSE"],
+  "pi": { "extensions": ["./index.ts"] },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test:unit": "node --test --experimental-strip-types tests/*.test.ts",
+    "test:load": "node --test --experimental-strip-types test-load.ts",
+    "test": "npm run check && npm run test:unit && npm run test:load"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.99.1",
+    "@earendil-works/pi-tui": "0.99.1",
+    "@types/node": "22.20.3",
+    "typebox": "1.3.7",
+    "typescript": "5.9.3"
+  }
+}

package/pr-watch.ts

@@ -0,0 +1,203 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export type WatchedTask = {
+  id: number;
+  state: string;
+  updated_at: string;
+  agent_notes: Record<string, string>;
+};
+type PR = { url: string; number: string };
+type Dependencies = {
+  selected: (ctx: ExtensionContext) => Promise<WatchedTask | null>;
+  get: (id: number) => Promise<WatchedTask>;
+  done: (task: WatchedTask, canAct: () => boolean) => Promise<void>;
+  claim: () => (() => void) | undefined;
+  refresh: (ctx: ExtensionContext) => Promise<void>;
+};
+const entryType = "pinote-pr-acknowledged";
+const watchEntryType = "pinote-pr-watched";
+
+// Accept one bare URL or Markdown link, never arbitrary hosts or terminal escapes.
+export function taskPR(task: WatchedTask | null): PR | undefined {
+  const field = task?.agent_notes.PR?.trim();
+  if (!field) return;
+  const url = /^\[[^\r\n]*\]\(([^\s]+)\)$/u.exec(field)?.[1] ?? field;
+  const match = /^https:\/\/github\.com\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_.-]+)\/pull\/([1-9][0-9]*)\/?$/u.exec(url);
+  if (!match || [".", ".."].includes(match[2]) || !Number.isSafeInteger(Number(match[3]))) return;
+  return { url: `https://github.com/${match[1]}/${match[2]}/pull/${match[3]}`, number: match[3] };
+}
+const keyFor = (task: WatchedTask, pr: PR) => JSON.stringify([task.id, pr.url.toLowerCase()]);
+const watchKey = (task: WatchedTask | null) => {
+  const pr = taskPR(task);
+  return task && pr ? keyFor(task, pr) : undefined;
+};
+
+export function createPRWatcher(pi: ExtensionAPI, deps: Dependencies) {
+  let ctx: ExtensionContext | undefined;
+  let watched: WatchedTask | null = null;
+  let visiblePR: PR | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let controller = new AbortController();
+  let generation = 0;
+  let revision = 0;
+  let running = false;
+  let interval = 60_000;
+  let warned = false;
+  let acknowledged = new Set<string>();
+
+  const remember = (current: WatchedTask | null) => {
+    const changed = watchKey(current) !== watchKey(watched);
+    watched = current;
+    if (changed && ctx) pi.appendEntry(watchEntryType, {
+      cwd: ctx.cwd, task: current ? { id: current.id, url: taskPR(current)!.url } : null,
+    });
+    return changed;
+  };
+  const paint = () => {
+    if (!ctx) return;
+    const pr = visiblePR;
+    ctx.ui.setStatus("pinote-pr", pr
+      ? ctx.ui.theme.fg("mdLink", `\x1b]8;;${pr.url}\x1b\\PR #${pr.number}\x1b]8;;\x1b\\`)
+      : undefined);
+  };
+  const schedule = (delay = interval) => {
+    if (!ctx || !interval || running) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => { void poll(); }, delay);
+    timer.unref();
+  };
+  const update = (context: ExtensionContext, current: WatchedTask | null) => {
+    if (!ctx || ctx.cwd !== context.cwd) return;
+    revision++;
+    // Display only the active selection, independently of the retained merge watch.
+    visiblePR = current && ["active", "in_progress"].includes(current.state) ? taskPR(current) : undefined;
+    // Completion clears selection. Keep the last task until poll verifies its state.
+    const changed = current ? remember(taskPR(current) ? current : null) : false;
+    paint();
+    if (changed) schedule(0);
+  };
+  const latest = async (context: ExtensionContext, previous: WatchedTask | null) => {
+    const current = await deps.selected(context);
+    if (current) return taskPR(current) ? current : null;
+    if (!previous) return null;
+    const old = await deps.get(previous.id);
+    return old.state === "done" && taskPR(old) ? old : null;
+  };
+  async function poll() {
+    if (!ctx || running) return;
+    const context = ctx;
+    const epoch = generation;
+    const signal = controller.signal;
+    const valid = () => ctx === context && generation === epoch && !signal.aborted;
+    running = true;
+    try {
+      await deps.refresh(context);
+      if (!valid()) return;
+      const snapshot = revision;
+      const candidate = await latest(context, watched);
+      if (!valid() || revision !== snapshot) return;
+      remember(candidate);
+      paint();
+      const pr = taskPR(candidate);
+      if (!candidate || !pr) return;
+      const key = keyFor(candidate, pr);
+      const same = () => valid() && watched !== null && taskPR(watched)?.url === pr.url && watched.id === candidate.id;
+      if (acknowledged.has(key)) return;
+      const result = await pi.exec("gh", ["pr", "view", pr.url, "--json", "state,url"], {
+        cwd: context.cwd, timeout: 10_000, signal,
+      });
+      if (!same()) return;
+      if (result.code !== 0 || result.killed) throw new Error("GitHub CLI failed");
+      const data = JSON.parse(result.stdout);
+      // GitHub canonicalizes owner/repository casing in its response URL.
+      if (typeof data.url !== "string" || data.url.toLowerCase() !== pr.url.toLowerCase() ||
+          !["OPEN", "CLOSED", "MERGED"].includes(data.state)) throw new Error("Invalid PR response");
+      warned = false;
+      if (data.state !== "MERGED" || !context.isIdle()) return;
+      const release = deps.claim();
+      if (!release) return;
+      try {
+        const current = await latest(context, candidate);
+        if (!same() || !current || current.id !== candidate.id || taskPR(current)?.url !== pr.url || !context.isIdle()) return;
+        const acknowledge = () => {
+          pi.appendEntry(entryType, { cwd: context.cwd, key });
+          acknowledged.add(key);
+        };
+        const alreadyDone = () => {
+          context.ui.notify(`PR #${pr.number} was merged and the task is already completed.`, "info");
+          acknowledge();
+        };
+        if (current.state === "done") { alreadyDone(); return; }
+        if (!["active", "in_progress"].includes(current.state)) return;
+        const confirmed = await context.ui.confirm(`PR #${pr.number} was merged`, "Mark this task completed?", { signal });
+        if (!same() || !context.isIdle()) return;
+        // Re-read selection, link, and revision after the dialog; never complete a changed task.
+        const fresh = await latest(context, current);
+        if (!same() || !fresh || fresh.id !== current.id || taskPR(fresh)?.url !== pr.url) return;
+        if (fresh.state === "done") { alreadyDone(); return; }
+        if (fresh.updated_at !== current.updated_at) {
+          context.ui.notify("Pinote task changed while confirming. The merge will be checked again.", "warning");
+          return;
+        }
+        if (confirmed) {
+          await deps.done(fresh, () => same() && context.isIdle());
+          if (!valid()) return;
+          context.ui.notify(`Pinote #${fresh.id} completed.`, "info");
+        }
+        acknowledge();
+      } finally {
+        release();
+        if (valid()) await deps.refresh(context);
+      }
+    } catch {
+      if (valid() && !warned) {
+        warned = true;
+        context.ui.notify("Pinote PR check failed. Check gh authentication and note availability; polling will retry.", "warning");
+      }
+    } finally {
+      // A previous session's request must not affect a replacement watcher's timer.
+      if (valid()) { running = false; schedule(); }
+    }
+  }
+  return {
+    update,
+    start(context: ExtensionContext) {
+      this.stop();
+      if (!context.hasUI || context.mode !== "tui") return;
+      const seconds = Number(process.env.PINOTE_PR_POLL_SECONDS ?? "60");
+      interval = Number.isInteger(seconds) && (seconds === 0 || seconds >= 10 && seconds <= 86400)
+        ? seconds * 1000 : 60_000;
+      if (interval !== seconds * 1000) context.ui.notify("Invalid PINOTE_PR_POLL_SECONDS; using 60 seconds (allowed: 0 or 10–86400).", "warning");
+      ctx = context;
+      const branch = context.sessionManager.getBranch();
+      // Persist only the identity; latest() must verify the real task state before polling.
+      for (const entry of branch) {
+        if (entry.type !== "custom" || entry.customType !== watchEntryType) continue;
+        const data = entry.data as { cwd?: unknown; task?: { id?: unknown; url?: unknown } | null } | undefined;
+        if (data?.cwd !== context.cwd) continue;
+        if (data.task === null) { watched = null; continue; }
+        if (!data.task || !Number.isSafeInteger(data.task.id) || Number(data.task.id) < 1 || typeof data.task.url !== "string") continue;
+        const restored = { id: Number(data.task.id), state: "unknown", updated_at: "", agent_notes: { PR: data.task.url } };
+        if (taskPR(restored)) watched = restored;
+      }
+      acknowledged = new Set(branch.flatMap((entry) => {
+        if (entry.type !== "custom" || entry.customType !== entryType) return [];
+        const data = entry.data as { cwd?: unknown; key?: unknown } | undefined;
+        return data?.cwd === context.cwd && typeof data.key === "string" ? [data.key] : [];
+      }));
+      schedule(0);
+    },
+    stop() {
+      generation++;
+      controller.abort();
+      controller = new AbortController();
+      clearTimeout(timer);
+      ctx?.ui.setStatus("pinote-pr", undefined);
+      ctx = undefined;
+      watched = null;
+      visiblePR = undefined;
+      running = false;
+      warned = false;
+    },
+  };
+}

package/setup.ts

@@ -0,0 +1,103 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { stripVTControlCharacters } from "node:util";
+import type { AutocompleteProvider } from "@earendil-works/pi-tui";
+
+// Immutable source: the Python app is not yet published to PyPI.
+export const cliSource = "https://github.com/kvidzibo/pinote/archive/9c6795f655e6b9d2c51c735fc84b6485fb663bb1.tar.gz";
+export const bundledCLIVersion = "0.3.0";
+export const setupHint = "Use /pi-note-setup for a missing CLI or /pi-note-upgrade for an older CLI; note must be on PATH.";
+export type CLIAction = "setup" | "upgrade" | "ready";
+
+export function cliAction(version: string): CLIAction {
+  const match = /^pinote (\d+)\.(\d+)\.(\d+)$/u.exec(version.trim());
+  if (!match) return "setup";
+  const installed = match.slice(1).map(BigInt);
+  const bundled = bundledCLIVersion.split(".").map(BigInt);
+  for (let i = 0; i < 3; i++) {
+    if (installed[i] < bundled[i]) return "upgrade";
+    if (installed[i] > bundled[i]) return "ready";
+  }
+  return "ready";
+}
+
+export async function detectCLI(pi: ExtensionAPI, signal?: AbortSignal): Promise<CLIAction> {
+  try {
+    const result = await pi.exec("note", ["--version"], { timeout: 5000, signal });
+    return !result.killed && result.code === 0 ? cliAction(result.stdout) : "setup";
+  } catch { return "setup"; }
+}
+
+export function cliMenu(current: AutocompleteProvider, action: () => CLIAction | undefined): AutocompleteProvider {
+  return {
+    triggerCharacters: current.triggerCharacters,
+    async getSuggestions(...args) {
+      const suggestions = await current.getSuggestions(...args);
+      if (!suggestions || !/^\/\S*$/u.test(suggestions.prefix)) return suggestions;
+      const items = suggestions.items.filter(({ value }) => {
+        const name = value.replace(/^\//u, "");
+        return name === "pi-note-setup" ? action() === "setup"
+          : name === "pi-note-upgrade" ? action() === "upgrade" : true;
+      });
+      return items.length ? { ...suggestions, items } : null;
+    },
+    applyCompletion: (...args) => current.applyCompletion(...args),
+    shouldTriggerFileCompletion: (...args) => current.shouldTriggerFileCompletion?.(...args) ?? true,
+  };
+}
+export function compatibleVersion(version: string): boolean {
+  const match = /^pinote (\d+)\.(\d+)\.(\d+)$/u.exec(version.trim());
+  return !!match && (Number(match[1]) > 0 || Number(match[2]) >= 3);
+}
+const clean = (value: string) => stripVTControlCharacters(value).replace(/[\x00-\x1f\x7f-\x9f]/gu, " ").slice(0, 1500);
+
+export async function setupCLI(
+  pi: ExtensionAPI, ctx: ExtensionContext, upgrade: boolean,
+  canAct: () => boolean, signal: AbortSignal,
+): Promise<void> {
+  const exec = (command: string, args: string[], timeout = 5000) =>
+    pi.exec(command, args, { timeout, signal });
+  const action = await detectCLI(pi, signal);
+  if (!canAct() || signal.aborted) return;
+  if (action === "ready") {
+    ctx.ui.notify(`Pinote CLI is ready (bundled version ${bundledCLIVersion} or newer). Use /pi-note.`, "info");
+    return;
+  }
+  const command = action === "upgrade" ? "/pi-note-upgrade" : "/pi-note-setup";
+  if (upgrade !== (action === "upgrade")) {
+    ctx.ui.notify(`Use ${command} ${action === "upgrade" ? "to upgrade the older CLI" : "to install the missing CLI"}.`, "info");
+    return;
+  }
+  try {
+    const uv = await exec("uv", ["--version"]);
+    if (uv.killed || uv.code !== 0) throw new Error("uv unavailable");
+  } catch {
+    if (canAct()) ctx.ui.notify(`Install uv from https://docs.astral.sh/uv/getting-started/installation/ and restart Pi with uv on PATH, then run ${command}. Python 3.11+ is required; uv can download it.`, "error");
+    return;
+  }
+  if (!canAct() || signal.aborted) return;
+  const approved = await ctx.ui.confirm("Install Pinote CLI?",
+    `Install bundled pinote ${bundledCLIVersion} in uv's isolated tool environment (may replace an existing uv installation). ` +
+    "Downloads source and build dependencies; uv may download Python 3.11+. No GTK, shell configuration, or task changes. " +
+    `Source: ${cliSource}`);
+  if (!approved || !canAct() || signal.aborted) return;
+  const confirmedAction = await detectCLI(pi, signal);
+  if (!canAct() || signal.aborted) return;
+  if (confirmedAction !== action) {
+    ctx.ui.notify("Pinote CLI changed while confirmation was open; installation skipped.", "info");
+    return;
+  }
+  ctx.ui.notify("Installing Pinote CLI with uv… (up to 3 minutes)", "info");
+  const installed = await exec("uv", ["--no-config", "tool", "install", "--reinstall", "--python", ">=3.11", `pinote @ ${cliSource}`], 180000);
+  if (signal.aborted) return;
+  if (installed.killed || installed.code !== 0) {
+    throw new Error(`CLI installation failed or timed out: ${clean(installed.stderr || installed.stdout)}. Check uv/network access and retry ${command}. Conflicting executables are not overwritten; resolve them manually.`);
+  }
+  if (!canAct()) return;
+  try {
+    const version = await exec("note", ["--version"]);
+    if (version.killed || version.code !== 0 || cliAction(version.stdout) !== "ready") throw new Error("note unavailable or older than bundled CLI");
+    if (canAct()) ctx.ui.notify(`${clean(version.stdout.trim())} is ready. Use /pi-note. GTK is optional and installed separately.`, "info");
+  } catch {
+    if (canAct()) ctx.ui.notify("Pinote installed, but note on PATH is missing or older than the bundled CLI. Run uv tool dir --bin in your terminal, add that directory to PATH before older note executables, then restart Pi.", "warning");
+  }
+}

package/task-picker.ts

@@ -0,0 +1,81 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Input, SelectList, truncateToWidth } from "@earendil-works/pi-tui";
+
+export type TaskSummary = {
+  id: number;
+  text: string;
+  state: string;
+  tag: string | null;
+};
+const singleLine = (value: string) => value.replace(/\s+/gu, " ").trim();
+export const taskState = (task: TaskSummary) => task.state === "in_progress" ? "●" : "○";
+export const taskTag = (task: TaskSummary) => task.tag ? `[${singleLine(task.tag)}]` : "[Untagged]";
+
+const selectionActions = ["tui.select.up", "tui.select.down", "tui.select.confirm", "tui.select.cancel"] as const;
+type Matches = (data: string, action: typeof selectionActions[number]) => boolean;
+
+export class TaskPicker {
+  private input = new Input({ prompt: "Search: ", placeholder: "task text, #id, tag, or state" });
+  private list!: SelectList;
+  private count = 0;
+
+  private tasks: TaskSummary[];
+  private theme: Theme;
+  private matches: Matches;
+  private done: (id: number | undefined) => void;
+  private requestRender: () => void;
+
+  constructor(tasks: TaskSummary[], theme: Theme, matches: Matches,
+    done: (id: number | undefined) => void, requestRender: () => void) {
+    this.tasks = tasks;
+    this.theme = theme;
+    this.matches = matches;
+    this.done = done;
+    this.requestRender = requestRender;
+    this.filter();
+  }
+
+  get focused() { return this.input.focused; }
+  set focused(value: boolean) { this.input.focused = value; }
+
+  private filter() {
+    const terms = this.input.getValue().toLocaleLowerCase().trim().split(/\s+/u).filter(Boolean);
+    const tasks = this.tasks.filter((task) => {
+      const search = `${task.text} #${task.id} ${taskTag(task)} ${task.state.replaceAll("_", " ")}`.toLocaleLowerCase();
+      return terms.every((term) => search.includes(term));
+    });
+    this.count = tasks.length;
+    this.list = new SelectList(tasks.map((task) => ({
+      value: String(task.id),
+      label: `${taskState(task)} ${taskTag(task)} #${task.id} ${singleLine(task.text)}`,
+    })), 8, {
+      selectedPrefix: (s) => this.theme.fg("accent", s),
+      selectedText: (s) => this.theme.fg("accent", s),
+      description: (s) => this.theme.fg("muted", s),
+      scrollInfo: (s) => this.theme.fg("dim", s),
+      noMatch: (s) => this.theme.fg("warning", s),
+    });
+    this.list.onSelect = (item) => this.done(Number(item.value));
+    this.list.onCancel = () => this.done(undefined);
+  }
+
+  handleInput(data: string) {
+    if (selectionActions.some((action) => this.matches(data, action))) this.list.handleInput(data);
+    else {
+      const before = this.input.getValue();
+      this.input.handleInput(data);
+      if (this.input.getValue() !== before) this.filter();
+    }
+    this.requestRender();
+  }
+
+  render(width: number) {
+    return [
+      truncateToWidth(this.theme.fg("accent", `Pinote — select a task (${this.count}/${this.tasks.length})`), width),
+      ...this.input.render(width),
+      ...this.list.render(width),
+      truncateToWidth(this.theme.fg("dim", "Type to filter · ↑↓ navigate · Enter select · Esc cancel"), width),
+    ];
+  }
+  invalidate() { this.input.invalidate(); this.list.invalidate(); }
+}