pi-note 0.36.0 → 0.39.0

package/dist-mcp/mcp/field-events.js

@@ -0,0 +1,295 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdirSync, lstatSync, openSync, closeSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { homedir } from 'node:os';
+import { z } from 'zod';
+import { readConfigDocument } from "../footer-config.js";
+const exec = promisify(execFile);
+const integer = z.number().int().nonnegative().safe();
+const field = z.string().min(1).max(128);
+const value = z.string().max(8192).nullable();
+const Event = z.object({ id: integer, taskId: integer.positive(), field,
+    event: z.enum(['added', 'changed', 'removed']), value, previousValue: value }).strict();
+const Batch = z.object({ cursor: integer, events: z.array(Event).max(3200) }).strict();
+export const FieldResult = z.object({
+    state: z.string().min(1).max(64).optional(), summary: z.string().max(1000).optional(),
+    display: z.object({ strikethrough: z.boolean().optional(), color: z.enum(['accent', 'muted', 'text', 'warning', 'error', 'success']).optional() }).strict().optional(),
+    notification: z.object({ key: z.string().min(1).max(256), message: z.string().min(1).max(1000) }).strict().optional(),
+    recheckAfterSeconds: z.number().int().min(10).max(86400).nullable().optional(),
+}).strict();
+export function configuredFieldHandler() {
+    const { value: config } = readConfigDocument();
+    const handler = config.fieldHandler;
+    if (handler === undefined || handler === null)
+        return undefined;
+    if (typeof handler !== 'string' || !isAbsolute(handler) || /[\u0000-\u001f\u007f]/u.test(handler))
+        throw new Error('fieldHandler must be an absolute executable file path');
+    return handler;
+}
+/** One bounded invocation, no shell. Kill the process group on cancellation/overflow. */
+export function runFieldHandler(handler, input, signal, timeoutMs = 30_000) {
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const child = spawn(handler, [], { cwd: dirname(handler), stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32' });
+        let output = '', bytes = 0, failed = false;
+        const kill = () => {
+            failed = true;
+            try {
+                if (process.platform !== 'win32' && child.pid)
+                    process.kill(-child.pid, 'SIGKILL');
+                else
+                    child.kill('SIGKILL');
+            }
+            catch { /* Already exited. */ }
+        };
+        const timer = setTimeout(kill, timeoutMs);
+        signal.addEventListener('abort', kill, { once: true });
+        const cleanup = () => { clearTimeout(timer); signal.removeEventListener('abort', kill); };
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => { bytes += Buffer.byteLength(chunk); if (bytes > 64 * 1024)
+            kill();
+        else
+            output += chunk; });
+        child.stderr.on('data', (chunk) => { bytes += chunk.length; if (bytes > 64 * 1024)
+            kill(); });
+        child.stdin.on('error', kill);
+        child.on('error', () => { cleanup(); reject(new Error('Field handler failed')); });
+        child.on('close', (code) => {
+            cleanup();
+            if (failed || code !== 0 || signal.aborted)
+                return reject(new Error('Field handler failed'));
+            try {
+                resolve(FieldResult.parse(JSON.parse(output)));
+            }
+            catch {
+                reject(new Error('Invalid field handler result'));
+            }
+        });
+        child.stdin.end(JSON.stringify(input));
+    });
+}
+/** Service-owned durable scheduler. A SQLite lease fences competing HTTP processes. */
+export class FieldAutomation {
+    db;
+    owner = randomUUID();
+    lifetime = new AbortController();
+    timer;
+    work;
+    handler;
+    noteCommand;
+    changed;
+    log;
+    constructor(db, handler, noteCommand, changed, log) {
+        this.db = db;
+        this.handler = handler;
+        this.noteCommand = noteCommand;
+        this.changed = changed;
+        this.log = log;
+        db.exec(`PRAGMA busy_timeout=5000;
+      CREATE TABLE IF NOT EXISTS scheduler (id INTEGER PRIMARY KEY CHECK(id=1), cursor INTEGER NOT NULL DEFAULT 0, handler TEXT NOT NULL, owner TEXT, lease_until INTEGER NOT NULL DEFAULT 0);
+      CREATE TABLE IF NOT EXISTS jobs (task_id INTEGER NOT NULL, field TEXT NOT NULL, job TEXT NOT NULL, PRIMARY KEY(task_id, field));
+      CREATE TABLE IF NOT EXISTS owners (task_id INTEGER PRIMARY KEY, context_id TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS notices (task_id INTEGER NOT NULL, field TEXT NOT NULL, id TEXT NOT NULL, message TEXT NOT NULL, PRIMARY KEY(task_id, field));`);
+        db.prepare('INSERT OR IGNORE INTO scheduler(id, handler) VALUES (1, ?)').run(handler);
+    }
+    static async open(options) {
+        const dataHome = process.env.XDG_DATA_HOME;
+        const database = join(dataHome && isAbsolute(dataHome) ? dataHome : join(homedir(), '.local/share'), 'pinote/notes.db');
+        const namespace = createHash('sha256').update(database).digest('hex').slice(0, 16);
+        const path = options.path ?? join(process.env.XDG_STATE_HOME || join(homedir(), '.local/state'), 'pinote/field-events', namespace, 'state.db');
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const directory = lstatSync(dirname(path));
+        if (!directory.isDirectory() || directory.uid !== process.getuid?.() || (directory.mode & 0o077))
+            throw new Error('Unsafe field automation directory');
+        try {
+            closeSync(openSync(path, 'wx', 0o600));
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.uid !== process.getuid?.() || (stat.mode & 0o077))
+            throw new Error('Unsafe field automation database');
+        const { DatabaseSync } = await import('node:sqlite');
+        const db = new DatabaseSync(path);
+        try {
+            return new FieldAutomation(db, options.handler, options.noteCommand ?? process.env.PINOTE_NOTE_COMMAND ?? 'note', options.changed ?? (() => { }), options.log ?? (() => { }));
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
+    }
+    async note(args) {
+        const { stdout } = await exec(this.noteCommand, ['--no-notify', ...args], { signal: this.lifetime.signal, timeout: 10_000, maxBuffer: 8 * 1024 * 1024 });
+        return JSON.parse(stdout);
+    }
+    leased() {
+        return Boolean(this.db.prepare('SELECT 1 FROM scheduler WHERE id=1 AND owner=? AND lease_until>?').get(this.owner, Date.now()));
+    }
+    transaction(work) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            if (!this.leased())
+                throw new Error('Field scheduler lease expired');
+            work();
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    save(job) {
+        this.db.prepare('INSERT INTO jobs(task_id,field,job) VALUES (?,?,?) ON CONFLICT(task_id,field) DO UPDATE SET job=excluded.job')
+            .run(job.event.taskId, job.event.field, JSON.stringify(job));
+    }
+    clear(taskId, name) {
+        this.db.prepare('DELETE FROM jobs WHERE task_id=? AND field=?').run(taskId, name);
+        this.db.prepare('DELETE FROM notices WHERE task_id=? AND field=?').run(taskId, name);
+    }
+    /** Explicit selection/write owns alerts; background reads can only claim unowned tasks. */
+    claim(taskId, contextId, replace = false) {
+        this.db.prepare(replace
+            ? 'INSERT INTO owners(task_id,context_id) VALUES (?,?) ON CONFLICT(task_id) DO UPDATE SET context_id=excluded.context_id'
+            : 'INSERT OR IGNORE INTO owners(task_id,context_id) VALUES (?,?)').run(taskId, contextId);
+    }
+    statuses(task) {
+        return this.db.prepare('SELECT job FROM jobs WHERE task_id=?').all(task.id).flatMap(({ job: raw }) => {
+            const job = JSON.parse(raw);
+            if (job.event.value === null || job.event.value !== task.agent_notes[job.event.field] || !job.result)
+                return [];
+            return [{ field: job.event.field, value: job.event.value, result: job.result, checkedAt: job.checkedAt, stale: job.stale ?? false }];
+        });
+    }
+    notices(task, contextId) {
+        this.claim(task.id, contextId);
+        const owner = this.db.prepare('SELECT context_id FROM owners WHERE task_id=?').get(task.id);
+        if (owner?.context_id !== contextId)
+            return [];
+        const fields = new Set(this.statuses(task).filter((s) => !s.stale && s.result.notification).map((s) => s.field));
+        return this.db.prepare('SELECT id, field, message FROM notices WHERE task_id=?').all(task.id)
+            .filter((n) => fields.has(n.field)).map((n) => ({ ...n, taskId: task.id }));
+    }
+    start() {
+        const schedule = () => {
+            if (this.lifetime.signal.aborted)
+                return;
+            let delay = 1000;
+            this.work = this.tick().catch(() => { delay = 30_000; this.log(); }).finally(() => {
+                this.work = undefined;
+                if (!this.lifetime.signal.aborted) {
+                    this.timer = setTimeout(schedule, delay);
+                    this.timer.unref();
+                }
+            });
+        };
+        schedule();
+    }
+    async tick() {
+        this.lifetime.signal.throwIfAborted();
+        const acquired = this.db.prepare('UPDATE scheduler SET owner=?, lease_until=? WHERE id=1 AND (lease_until<=? OR owner=?)')
+            .run(this.owner, Date.now() + 90_000, Date.now(), this.owner).changes;
+        if (!acquired)
+            return;
+        try {
+            let state = this.db.prepare('SELECT cursor, handler FROM scheduler WHERE id=1').get();
+            if (state.handler !== this.handler) {
+                this.transaction(() => {
+                    this.db.exec('DELETE FROM jobs; DELETE FROM notices;');
+                    this.db.prepare('UPDATE scheduler SET cursor=0, handler=? WHERE id=1').run(this.handler);
+                });
+                state = { cursor: 0, handler: this.handler };
+                this.changed();
+            }
+            const batch = Batch.parse(await this.note(['field-events', '--after', String(state.cursor), '--limit', '25']));
+            if (!this.leased())
+                return;
+            if (batch.cursor < state.cursor || batch.events.some((e) => e.id <= state.cursor || e.id > batch.cursor))
+                throw new Error('Invalid field event cursor');
+            if (batch.cursor !== state.cursor) {
+                this.transaction(() => {
+                    for (const event of batch.events) {
+                        // New input invalidates both old display and pending alerts immediately.
+                        this.clear(event.taskId, event.field);
+                        this.save({ event, due: Date.now(), attempts: 0 });
+                    }
+                    this.db.prepare('UPDATE scheduler SET cursor=? WHERE id=1').run(batch.cursor);
+                });
+                this.changed();
+                return; // Drain durable history before executing; coalesce superseded values.
+            }
+            const jobs = this.db.prepare('SELECT job FROM jobs').all().map(({ job }) => JSON.parse(job));
+            const job = jobs.filter((j) => j.due !== null && j.due <= Date.now()).sort((a, b) => a.due - b.due)[0];
+            if (!job)
+                return;
+            const event = job.event;
+            const task = await this.note(['agent', 'get', String(event.taskId)]);
+            if (!this.leased())
+                return;
+            const currentValue = task && ['active', 'in_progress'].includes(task.state) ? task.agent_notes[event.field] ?? null : null;
+            if (event.value !== currentValue) {
+                this.transaction(() => this.clear(event.taskId, event.field));
+                this.changed();
+                return;
+            }
+            let result, retryAfterSeconds = 0;
+            try {
+                result = await runFieldHandler(this.handler, {
+                    version: 1, eventId: `${event.id}:${event.field}`, taskId: event.taskId, field: event.field,
+                    event: job.checkedAt ? 'check' : event.event, value: event.value, previousValue: event.previousValue,
+                    ...(job.result ? { previousResult: job.result } : {}),
+                }, this.lifetime.signal);
+                if (result.state === 'error') {
+                    retryAfterSeconds = result.recheckAfterSeconds ?? 0;
+                    throw new Error('Handler reported unavailable data');
+                }
+            }
+            catch {
+                if (!this.leased() || this.lifetime.signal.aborted)
+                    return;
+                job.attempts++;
+                job.stale = true;
+                job.result ??= { state: 'error', summary: 'Field handler unavailable', display: { color: 'muted' } };
+                job.due = Date.now() + Math.max(retryAfterSeconds, Math.min(3600, 30 * 2 ** Math.min(job.attempts - 1, 7))) * 1000;
+                this.transaction(() => this.save(job));
+                this.changed();
+                this.log();
+                return;
+            }
+            const latest = await this.note(['agent', 'get', String(event.taskId)]);
+            if (!this.leased())
+                return;
+            if (latest?.updated_at !== task?.updated_at)
+                return; // Includes remove/re-add (ABA); next tick drains new events.
+            this.transaction(() => {
+                if (event.value === null)
+                    this.clear(event.taskId, event.field);
+                else {
+                    const notification = result.notification;
+                    if (!notification)
+                        this.db.prepare('DELETE FROM notices WHERE task_id=? AND field=?').run(event.taskId, event.field);
+                    else if (JSON.stringify(notification) !== JSON.stringify(job.result?.notification)) {
+                        this.db.prepare('INSERT INTO notices(task_id,field,id,message) VALUES (?,?,?,?) ON CONFLICT(task_id,field) DO UPDATE SET id=excluded.id,message=excluded.message')
+                            .run(event.taskId, event.field, randomUUID(), notification.message);
+                    }
+                    this.save({ event, result, due: result.recheckAfterSeconds ? Date.now() + result.recheckAfterSeconds * 1000 : null,
+                        attempts: 0, checkedAt: new Date().toISOString(), stale: false });
+                }
+            });
+            this.changed();
+        }
+        finally {
+            this.db.prepare('UPDATE scheduler SET lease_until=0 WHERE id=1 AND owner=?').run(this.owner);
+        }
+    }
+    async close() {
+        this.lifetime.abort();
+        clearTimeout(this.timer);
+        await this.work;
+        this.db.close();
+    }
+}

package/dist-mcp/mcp/http.js

@@ -9,6 +9,7 @@ import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { createPinoteServer } from "./core.js";
 import { completionEvents } from "./events.js";
 import { pinoteToken } from "../token.js";
+import { configuredFieldHandler, FieldAutomation } from "./field-events.js";
 function diagnostic(path, event) {
     const line = `${new Date().toISOString()} Pinote HTTP ${event}\n`;
     process.stdout.write(line);
@@ -48,6 +49,13 @@ export async function startPinoteHttpServer(options = {}) {
     if (configuredHosts?.some((value) => !/^(?:\[[0-9a-fA-F:]+\]|[a-zA-Z0-9.-]+)(?::[0-9]+)?$/.test(value)))
         throw new Error('Invalid allowed HTTP authority');
     let allowedHosts = new Set(configuredHosts);
+    const fieldListeners = new Set();
+    const handler = configuredFieldHandler();
+    const fieldAutomation = handler ? await FieldAutomation.open({ handler,
+        changed: () => { for (const listener of fieldListeners)
+            listener(); },
+        log: () => log('field automation check failed; will retry'),
+    }) : undefined;
     const reject = (res, status) => { res.writeHead(status, { 'Content-Type': 'text/plain' }); res.end(`${status}\n`); };
     const single = (req, name) => {
         const values = req.rawHeaders.filter((_, i) => i % 2 === 0 && req.rawHeaders[i].toLowerCase() === name);
@@ -132,6 +140,8 @@ export async function startPinoteHttpServer(options = {}) {
                 });
                 const entry = { transport, server: undefined, busy: 0, streams: 0, touched: Date.now() };
                 entry.server = createPinoteServer({
+                    fieldAutomation,
+                    onFieldChange: (listener) => { fieldListeners.add(listener); return () => { fieldListeners.delete(listener); }; },
                     onError: () => log('protocol or notification failed'),
                     onBusy: (delta) => { entry.busy += delta; entry.touched = Date.now(); },
                     onClose: () => { all.delete(entry); if (transport.sessionId)
@@ -165,7 +175,15 @@ export async function startPinoteHttpServer(options = {}) {
     });
     listener.requestTimeout = 30_000;
     listener.headersTimeout = 10_000;
-    await new Promise((ok, fail) => { listener.once('error', fail); listener.listen(port, host, () => { listener.off('error', fail); ok(); }); });
+    try {
+        await new Promise((ok, fail) => { listener.once('error', fail); listener.listen(port, host, () => { listener.off('error', fail); ok(); }); });
+    }
+    catch (error) {
+        await fieldAutomation?.close();
+        await events.close();
+        throw error;
+    }
+    fieldAutomation?.start();
     const address = listener.address();
     if (!address || typeof address === 'string')
         throw new Error('Missing HTTP address');
@@ -193,6 +211,7 @@ export async function startPinoteHttpServer(options = {}) {
         const force = setTimeout(() => listener.closeAllConnections(), 3000);
         try {
             await events.close();
+            await fieldAutomation?.close();
             await Promise.allSettled([...all].map((session) => session.server.close()));
             await closed;
         }

package/examples/field-events.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Configure this executable as a field-event handler. Requires authenticated `gh`.
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const errorResult = () => ({ state: 'error', summary: 'Unable to check PR status', recheckAfterSeconds: 120 });
+
+function validateResponse(pr) {
+  if (!object(pr) || !['OPEN', 'CLOSED', 'MERGED'].includes(pr.state)
+    || !['MERGEABLE', 'CONFLICTING', 'UNKNOWN'].includes(pr.mergeable)
+    || typeof pr.headRefOid !== 'string' || !/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/i.test(pr.headRefOid)
+    || !Array.isArray(pr.statusCheckRollup)) throw new Error('Invalid response');
+  return pr.statusCheckRollup.map((check) => {
+    if (!object(check)) throw new Error('Invalid check');
+    if (check.__typename === 'CheckRun') {
+      if (typeof check.name !== 'string' || !check.name
+        || !['COMPLETED', 'IN_PROGRESS', 'QUEUED', 'REQUESTED', 'WAITING', 'PENDING'].includes(check.status)
+        || !(check.conclusion === null || ['', 'SUCCESS', 'NEUTRAL', 'SKIPPED', 'FAILURE', 'CANCELLED', 'TIMED_OUT', 'ACTION_REQUIRED', 'STALE', 'STARTUP_FAILURE'].includes(check.conclusion))
+        || (check.status === 'COMPLETED' && !check.conclusion)
+        || (check.status !== 'COMPLETED' && check.conclusion)) throw new Error('Invalid check run');
+      const failed = check.status === 'COMPLETED' && !['SUCCESS', 'NEUTRAL', 'SKIPPED'].includes(check.conclusion);
+      return { failed, pending: check.status !== 'COMPLETED', fingerprint: ['CheckRun', check.name, check.status, check.conclusion] };
+    }
+    if (check.__typename === 'StatusContext') {
+      if (typeof check.context !== 'string' || !check.context
+        || !['EXPECTED', 'ERROR', 'FAILURE', 'PENDING', 'SUCCESS'].includes(check.state)) throw new Error('Invalid status context');
+      return { failed: ['ERROR', 'FAILURE'].includes(check.state), pending: ['EXPECTED', 'PENDING'].includes(check.state), fingerprint: ['StatusContext', check.context, check.state] };
+    }
+    throw new Error('Unknown check type');
+  });
+}
+
+export async function handleFieldEvent(event) {
+  if (!object(event) || event.version !== 1 || !['added', 'changed', 'removed', 'check'].includes(event.event)
+    || !Number.isSafeInteger(event.taskId) || typeof event.field !== 'string'
+    || !(event.value === null || typeof event.value === 'string')
+    || !(event.previousValue === null || typeof event.previousValue === 'string')
+    || typeof event.eventId !== 'string'
+    || (event.previousResult !== undefined && !object(event.previousResult))) throw new Error('Invalid event');
+  if (event.field !== 'PR' || event.event === 'removed') return {};
+  const value = event.value?.trim() ?? '';
+  const url = /^\[[^\]\r\n]*\]\(([^\s()]+)\)$/.exec(value)?.[1] ?? value;
+  const match = /^https:\/\/github\.com\/([A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)\/([A-Za-z0-9_.-]+)\/pull\/([1-9][0-9]*)$/.exec(url);
+  if (!match || ['.', '..'].includes(match[2])) return errorResult();
+  const [, owner, repo, number] = match;
+  const { stdout } = await run('gh', ['pr', 'view', number, '--repo', `${owner}/${repo}`, '--json', 'state,mergeable,statusCheckRollup,headRefOid'], { timeout: 20_000, maxBuffer: 1024 * 1024, encoding: 'utf8' });
+  const pr = JSON.parse(stdout);
+  const checks = validateResponse(pr);
+  const summary = `PR #${number}`;
+  if (pr.state === 'MERGED') return { state: 'merged', summary: `${summary} merged`, display: { strikethrough: true, color: 'muted' } };
+  if (pr.state === 'CLOSED') return { state: 'closed', summary: `${summary} closed`, display: { strikethrough: false, color: 'muted' } };
+  const conflict = pr.mergeable === 'CONFLICTING';
+  const failed = checks.filter((check) => check.failed);
+  if (conflict || failed.length) {
+    const state = conflict ? 'conflict' : 'failed';
+    const fingerprint = createHash('sha256').update(JSON.stringify([
+      pr.headRefOid.toLowerCase(), state,
+      failed.map((check) => JSON.stringify(check.fingerprint)).sort(),
+    ])).digest('hex');
+    return { state, summary: `${summary} ${conflict ? 'has merge conflicts' : 'checks failed'}`,
+      display: { strikethrough: false, color: 'warning' },
+      notification: { key: `pr:${owner}/${repo}:${number}:${fingerprint}`, message: conflict ? 'PR has merge conflicts' : 'PR checks failed' },
+      recheckAfterSeconds: 60 };
+  }
+  const pending = pr.mergeable === 'UNKNOWN' || checks.length === 0 || checks.some((check) => check.pending);
+  return { state: pending ? 'pending' : 'passing', summary: `${summary} ${pending ? 'checks pending' : 'checks passing'}`,
+    display: { strikethrough: false, color: pending ? 'muted' : 'success' }, recheckAfterSeconds: 60 };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    let input = '';
+    for await (const chunk of process.stdin) {
+      input += chunk;
+      if (Buffer.byteLength(input) > 1024 * 1024) throw new Error('Input too large');
+    }
+    process.stdout.write(`${JSON.stringify(await handleFieldEvent(JSON.parse(input)))}\n`);
+  } catch {
+    process.stderr.write('PR field handler failed\n');
+    process.stdout.write(`${JSON.stringify(errorResult())}\n`);
+  }
+}

package/mcp/FIELD_EVENTS.md

@@ -0,0 +1,151 @@
+# Field-event handler
+
+pi-note **0.39.0+** with **note 0.24.0+** can run one executable for all task-field
+changes. This is opt-in, on the **HTTP service machine**. No extra daemon or Pi-local
+watcher is installed. The local-only extension and stdio service do not run handlers.
+
+## Enable
+
+Create a trusted executable with a shebang, then add its absolute path to the
+service's `pi-note.json`, preserving existing settings:
+
+```json
+{
+  "fieldHandler": "/absolute/path/field-events.mjs"
+}
+```
+
+Restart the existing Pinote HTTP service; update clients and `/reload` Pi for alerts
+and footer styling. Removing the setting or setting it to `null`, then restarting,
+disables execution and hides automation results without modifying task fields.
+Scripts and settings are never installed or enabled automatically.
+
+The bundled [`examples/field-events.mjs`](../examples/field-events.mjs) handles `PR`
+and ignores other fields. Copy it to a user-owned location before customization,
+make it executable (`chmod u+x`), and ensure authenticated `gh` and Node are on the
+**service's** PATH. It accepts a GitHub PR URL or Markdown link, checks once, and
+requests another check in 60 seconds. It warns on failing checks/conflicts and
+strikes through merged PRs while keeping their links. Closed/merged PRs stop
+polling; merging never completes the Pinote task. Passing means reported checks
+passed, not that every review/branch-protection requirement is satisfied.
+
+To support another field, add another branch to this same file. No registry or
+plugin package is needed.
+
+## Script contract
+
+Pinote executes the file directly, **without a shell**, from its containing
+directory. It sends one JSON object on stdin, closes stdin, and expects one JSON
+object on stdout. Diagnostics belong on stderr. All values and external responses
+are untrusted data; never interpolate them into shell commands.
+
+```json
+{
+  "version": 1,
+  "eventId": "123:PR",
+  "event": "added",
+  "taskId": 402,
+  "field": "PR",
+  "value": "https://github.com/owner/repo/pull/123",
+  "previousValue": null
+}
+```
+
+- `added`, `changed`, `removed`: effective field-value changes from committed task
+  history, including CLI/GUI/other-client writes. Completing, removing or scheduling
+  a task removes its effective fields; restoring/reactivating adds them again.
+  Editing a global footer definition does **not** emit a task-field event.
+- `check`: a requested scheduled check. `eventId` and `previousValue` still identify
+  the originating change; `previousResult` contains the last stored result, if any.
+- A removed field has `value: null`. Its handler result cannot style, notify or
+  reschedule it. Removed/replaced inputs invalidate old results and alerts.
+
+Return `{}` for an ignored field, or:
+
+```json
+{
+  "state": "failed",
+  "summary": "PR #123 checks failed",
+  "display": { "color": "warning", "strikethrough": false },
+  "notification": { "key": "head-sha:failed-check-fingerprint", "message": "PR checks failed" },
+  "recheckAfterSeconds": 60
+}
+```
+
+All result properties are optional. Unknown properties are rejected.
+
+| Property | Meaning / limit |
+|---|---|
+| `state` | Status name, 1–64 characters; `error` is reserved for unavailable/failed checks |
+| `summary` | Observation for agent context, at most 1,000 characters |
+| `display` | `strikethrough` boolean; `color`: `accent`, `muted`, `text`, `warning`, `error`, `success` |
+| `notification` | Stable `key` (1–256 characters) and `message` (1–1,000); changes create a fresh alert |
+| `recheckAfterSeconds` | Integer 10–86,400; omitted/null stops successful checks |
+
+Results replace previous results, not the original field value. Omitting a
+notification clears the current alert. Identical notification key/message pairs
+are deduplicated; a resolved condition followed by another failure alerts again.
+
+## Delivery and reliability
+
+- The service stores its history cursor, scheduled checks, results and alert owner
+  under `$XDG_STATE_HOME/pinote/field-events/<database-path-hash>/state.db` (default
+  state home: `~/.local/state`). Keep this private and local, like `notes.db`.
+  It uses Node's built-in SQLite API; Node 22 may print its experimental warning.
+- Monitoring continues without an open Pi session while the HTTP service runs.
+  Deadlines survive restarts. A lease prevents overlapping normal execution by
+  competing service processes; run one service/configuration per notes database.
+- Initial activation reconstructs fields from durable history. Intake scans at
+  most 25 history rows per tick and coalesces superseded pending changes before
+  execution. This is a **current-field automation API**, not a lossless audit hook:
+  intermediate values may never reach the script. Old migrated history without
+  field snapshots cannot be reconstructed.
+- One handler runs at a time. Each invocation has a 30-second deadline and a
+  combined 64 KiB stdout/stderr limit. On Unix, cancellation kills its process
+  group. Scripts must not detach child processes. Invalid JSON/schema, nonzero
+  exit, timeout or `state: "error"` preserve the last good result as stale and
+  retry with exponential backoff (30 seconds to one hour, or a longer requested
+  retry). First-check failure appears as unavailable. Stale results don't alert.
+- Results are discarded if the task changed during execution, including
+  remove/re-add of the same value. Durable intake then reconciles new input.
+  Handler invocations are **at least once** after crashes: use `eventId` and
+  idempotent logic for external side effects; exactly-once execution is not promised.
+- Alerts belong to the conversation that last explicitly selected or updated the
+  task. For an unowned task, the first selected-task view claims alerts. Other
+  sessions still see shared field status. Explicitly selecting the task reclaims
+  ownership. No alert is delivered while that conversation has another task selected.
+- Pi shows an alert once and persists receipts across reload/resume (latest 4,096
+  IDs per branch). Current results reach the next agent run through fresh,
+  task-scoped context. Duplicate field values are not repeated; results exceeding
+  the context budget are omitted with a count, preserving the complete task first.
+  **No prompt submission, model wake-up, task selection or
+  completion is authorized by a handler result.**
+- Only the latest current alert per field is retained, not an offline alert log.
+  If a failure resolves while Pi is closed, it is not delivered later as a stale
+  failure. Network recovery remains explicit through `/pinote` or a tool call.
+- Changing the configured handler path resets automation state and reconstructs
+  history; editing the same file affects its next invocation, not stopped checks.
+  Restoring an older notes backup can invalidate the cursor: stop the service and
+  deliberately back up/reset its corresponding automation state before restarting.
+
+Handlers run with the service user's permissions and inherited environment,
+including available credentials. They are trusted code, **not sandboxed**. The
+remote UI and agent tools cannot configure executable paths. Service logs report
+failures generically; script output and stderr are not copied into logs. Run the
+script manually with synthetic input when debugging; don't put secrets in results,
+which may be displayed and sent to the configured model.
+
+## Read field history locally
+
+`note field-events [--after CURSOR] [--limit N]` is read-only. Without `--after`, it
+returns the current tail and an empty array. An explicit cursor (including `0`)
+scans up to N durable rows, advancing even across unrelated events. Limits are
+1–1,000 rows, default 256; several field changes can share one event-row ID:
+
+```json
+{"cursor":123,"events":[{"id":123,"taskId":402,"field":"PR","event":"added","value":"https://github.com/owner/repo/pull/123","previousValue":null}]}
+```
+
+Persist the **returned cursor**, not just the last emitted field ID. Cursors must
+be nonnegative safe integers and cannot be ahead of current history. This command
+does not execute handlers or change the existing completion-only `/events` stream.

package/mcp/README.md

@@ -141,6 +141,13 @@ Tests use temporary data and real HTTP/stdio connections, including authenticati
 shared notes, independent selections, conflicts and reconnects. Visual checks use
 Xvfb and private D-Bus; never point them at personal data.
 
+## Field automations
+
+A user-configured single executable can react to task-field changes and request
+scheduled checks inside this service. State survives restarts; no additional daemon
+is needed. Requires note 0.24.0+ and is disabled by default. See the
+[field-handler contract and PR example](FIELD_EVENTS.md) before enabling trusted code.
+
 ## Task-completion events
 
 `GET /events` on the same listener requires the same bearer token, Host allowlist