pi-note 0.39.4 → 0.40.1

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

@@ -6,6 +6,7 @@ import { dirname, isAbsolute, join } from 'node:path';
 import { homedir } from 'node:os';
 import { z } from 'zod';
 import { readConfigDocument } from "../footer-config.js";
+import { discoverFieldWatchers } from "../field-watchers.js";
 const exec = promisify(execFile);
 const integer = z.number().int().nonnegative().safe();
 const field = z.string().min(1).max(128);
@@ -19,15 +20,6 @@ export const FieldResult = z.object({
     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();
@@ -77,24 +69,30 @@ export class FieldAutomation {
     lifetime = new AbortController();
     timer;
     work;
-    handler;
+    watchers;
+    enabled = [];
+    signature = '';
+    generation = 0;
+    invocation;
+    ticking = false;
     noteCommand;
     changed;
     log;
-    constructor(db, handler, noteCommand, changed, log) {
+    constructor(db, watchers, noteCommand, changed, log) {
         this.db = db;
-        this.handler = handler;
+        this.watchers = watchers;
         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 fw_scheduler (id INTEGER PRIMARY KEY CHECK(id=1), owner TEXT, lease_until INTEGER NOT NULL DEFAULT 0);
+      CREATE TABLE IF NOT EXISTS fw_watchers (id TEXT PRIMARY KEY, path TEXT NOT NULL, cursor INTEGER NOT NULL DEFAULT 0);
+      CREATE TABLE IF NOT EXISTS fw_jobs (watcher_id TEXT NOT NULL, task_id INTEGER NOT NULL, field TEXT NOT NULL, job TEXT NOT NULL, PRIMARY KEY(watcher_id,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);
+      CREATE TABLE IF NOT EXISTS fw_notices (watcher_id TEXT NOT NULL, task_id INTEGER NOT NULL, field TEXT NOT NULL, id TEXT NOT NULL, message TEXT NOT NULL, PRIMARY KEY(watcher_id,task_id,field));
+      INSERT OR IGNORE INTO fw_scheduler(id) VALUES (1);`);
     }
-    static async open(options) {
+    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);
@@ -116,7 +114,7 @@ export class FieldAutomation {
         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 ?? (() => { }));
+            return new FieldAutomation(db, options.watchers ?? (() => discoverFieldWatchers(readConfigDocument().value)), options.noteCommand ?? process.env.PINOTE_NOTE_COMMAND ?? 'note', options.changed ?? (() => { }), options.log ?? (() => { }));
         }
         catch (error) {
             db.close();
@@ -128,7 +126,7 @@ export class FieldAutomation {
         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()));
+        return Boolean(this.db.prepare('SELECT 1 FROM fw_scheduler WHERE id=1 AND owner=? AND lease_until>?').get(this.owner, Date.now()));
     }
     transaction(work) {
         this.db.exec('BEGIN IMMEDIATE');
@@ -143,13 +141,43 @@ export class FieldAutomation {
             throw error;
         }
     }
+    reconcile() {
+        const enabled = this.watchers().filter((watcher) => watcher.enabled);
+        if (enabled.length > 32 || new Set(enabled.map((w) => w.id)).size !== enabled.length)
+            throw new Error('Invalid enabled watchers');
+        const signature = JSON.stringify(enabled.map((w) => [w.id, w.path]));
+        if (signature === this.signature)
+            return;
+        this.generation++;
+        this.invocation?.abort();
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            for (const row of this.db.prepare('SELECT id,path FROM fw_watchers').all()) {
+                if (!enabled.some((w) => w.id === row.id && w.path === row.path)) {
+                    this.db.prepare('DELETE FROM fw_jobs WHERE watcher_id=?').run(row.id);
+                    this.db.prepare('DELETE FROM fw_notices WHERE watcher_id=?').run(row.id);
+                    this.db.prepare('DELETE FROM fw_watchers WHERE id=?').run(row.id);
+                }
+            }
+            for (const watcher of enabled)
+                this.db.prepare('INSERT OR IGNORE INTO fw_watchers(id,path) VALUES (?,?)').run(watcher.id, watcher.path);
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+        this.enabled = enabled;
+        this.signature = signature;
+        this.changed();
+    }
     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));
+        this.db.prepare('INSERT INTO fw_jobs(watcher_id,task_id,field,job) VALUES (?,?,?,?) ON CONFLICT(watcher_id,task_id,field) DO UPDATE SET job=excluded.job')
+            .run(job.watcherId, 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);
+    clear(watcherId, taskId, name) {
+        this.db.prepare('DELETE FROM fw_jobs WHERE watcher_id=? AND task_id=? AND field=?').run(watcherId, taskId, name);
+        this.db.prepare('DELETE FROM fw_notices WHERE watcher_id=? AND task_id=? AND field=?').run(watcherId, taskId, name);
     }
     /** Explicit selection/write owns alerts; background reads can only claim unowned tasks. */
     claim(taskId, contextId, replace = false) {
@@ -158,21 +186,23 @@ export class FieldAutomation {
             : '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 }) => {
+        this.reconcile();
+        return this.enabled.flatMap((watcher) => this.db.prepare('SELECT job FROM fw_jobs WHERE watcher_id=? AND task_id=?').all(watcher.id, 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)
+            if (job.event.value === null || job.event.value !== task.agent_notes[job.event.field] || !job.result || Object.keys(job.result).length === 0)
                 return [];
-            return [{ field: job.event.field, value: job.event.value, result: job.result, checkedAt: job.checkedAt, stale: job.stale ?? false }];
-        });
+            return [{ watcherId: watcher.id, field: job.event.field, value: job.event.value, result: job.result, checkedAt: job.checkedAt, stale: job.stale ?? false }];
+        }));
     }
-    notices(task, contextId) {
+    notices(task, contextId, receipts = []) {
         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 }));
+        const received = new Set(receipts);
+        const fields = new Set(this.statuses(task).filter((s) => !s.stale && s.result.notification).map((s) => `${s.watcherId}:${s.field}`));
+        return this.db.prepare('SELECT watcher_id, id, field, message FROM fw_notices WHERE task_id=?').all(task.id)
+            .filter((n) => !received.has(n.id) && fields.has(`${n.watcher_id}:${n.field}`)).slice(0, 64).map(({ id, field, message }) => ({ id, field, message, taskId: task.id }));
     }
     start() {
         const schedule = () => {
@@ -189,67 +219,96 @@ export class FieldAutomation {
         };
         schedule();
     }
-    async tick() {
+    tick() {
+        if (this.ticking)
+            return this.work ?? Promise.resolve();
+        this.ticking = true;
+        const work = this.performTick().finally(() => { this.ticking = false; if (this.work === work)
+            this.work = undefined; });
+        this.work = work;
+        return work;
+    }
+    async performTick() {
         this.lifetime.signal.throwIfAborted();
-        const acquired = this.db.prepare('UPDATE scheduler SET owner=?, lease_until=? WHERE id=1 AND (lease_until<=? OR owner=?)')
+        const acquired = this.db.prepare('UPDATE fw_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();
+            this.reconcile();
+            const generation = this.generation;
+            const valid = () => {
+                this.reconcile();
+                if (!this.leased() || generation !== this.generation || this.lifetime.signal.aborted)
+                    return false;
+                // Many watchers can make intake longer than one lease; each bounded operation renews it.
+                this.db.prepare('UPDATE fw_scheduler SET lease_until=? WHERE id=1 AND owner=?').run(Date.now() + 90_000, this.owner);
+                return true;
+            };
+            let drained = false;
+            for (const watcher of this.enabled) {
+                const state = this.db.prepare('SELECT cursor FROM fw_watchers WHERE id=?').get(watcher.id);
+                const batch = Batch.parse(await this.note(['field-events', '--after', String(state.cursor), '--limit', '25']));
+                if (!valid())
+                    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) {
+                            this.clear(watcher.id, event.taskId, event.field);
+                            this.save({ watcherId: watcher.id, event, due: Date.now(), attempts: 0 });
+                        }
+                        this.db.prepare('UPDATE fw_watchers SET cursor=? WHERE id=?').run(batch.cursor, watcher.id);
+                    });
+                    drained = true;
+                }
             }
-            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);
-                });
+            if (drained) {
                 this.changed();
-                return; // Drain durable history before executing; coalesce superseded values.
+                return;
             }
-            const jobs = this.db.prepare('SELECT job FROM jobs').all().map(({ job }) => JSON.parse(job));
+            const jobs = this.db.prepare('SELECT job FROM fw_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 watcher = this.enabled.find((w) => w.id === job.watcherId);
+            if (!watcher)
+                return;
             const task = await this.note(['agent', 'get', String(event.taskId)]);
-            if (!this.leased())
+            if (!valid())
                 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.transaction(() => this.clear(job.watcherId, event.taskId, event.field));
                 this.changed();
                 return;
             }
             let result, retryAfterSeconds = 0;
+            const invocation = new AbortController();
+            this.invocation = invocation;
+            const abort = () => invocation.abort();
+            this.lifetime.signal.addEventListener('abort', abort, { once: true });
+            const poll = setInterval(() => { try {
+                this.reconcile();
+            }
+            catch {
+                invocation.abort();
+            } }, 100);
             try {
-                result = await runFieldHandler(this.handler, {
+                result = await runFieldHandler(watcher.path, {
                     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);
+                }, invocation.signal);
                 if (result.state === 'error') {
                     retryAfterSeconds = result.recheckAfterSeconds ?? 0;
                     throw new Error('Handler reported unavailable data');
                 }
             }
             catch {
-                if (!this.leased() || this.lifetime.signal.aborted)
+                if (!valid() || invocation.signal.aborted)
                     return;
                 job.attempts++;
                 job.stale = true;
@@ -260,30 +319,38 @@ export class FieldAutomation {
                 this.log();
                 return;
             }
+            finally {
+                clearInterval(poll);
+                this.lifetime.signal.removeEventListener('abort', abort);
+                if (this.invocation === invocation)
+                    this.invocation = undefined;
+            }
+            if (!valid() || invocation.signal.aborted)
+                return;
             const latest = await this.note(['agent', 'get', String(event.taskId)]);
-            if (!this.leased())
+            if (!valid())
                 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);
+                    this.clear(job.watcherId, 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);
+                        this.db.prepare('DELETE FROM fw_notices WHERE watcher_id=? AND task_id=? AND field=?').run(job.watcherId, 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.db.prepare('INSERT INTO fw_notices(watcher_id,task_id,field,id,message) VALUES (?,?,?,?,?) ON CONFLICT(watcher_id,task_id,field) DO UPDATE SET id=excluded.id,message=excluded.message')
+                            .run(job.watcherId, event.taskId, event.field, randomUUID(), notification.message);
                     }
-                    this.save({ event, result, due: result.recheckAfterSeconds ? Date.now() + result.recheckAfterSeconds * 1000 : null,
+                    this.save({ watcherId: job.watcherId, 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);
+            this.db.prepare('UPDATE fw_scheduler SET lease_until=0 WHERE id=1 AND owner=?').run(this.owner);
         }
     }
     async close() {

package/dist-mcp/mcp/http.js

@@ -9,7 +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";
+import { FieldAutomation } from "./field-events.js";
 function diagnostic(path, event) {
     const line = `${new Date().toISOString()} Pinote HTTP ${event}\n`;
     process.stdout.write(line);
@@ -50,12 +50,11 @@ export async function startPinoteHttpServer(options = {}) {
         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,
+    const fieldAutomation = await FieldAutomation.open({
         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);

package/field-watchers.ts

@@ -0,0 +1,49 @@
+import { createHash } from 'node:crypto';
+import { accessSync, constants, lstatSync, readdirSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, normalize } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export type FieldWatcherConfig = { path: string; enabled: boolean };
+export type FieldWatcher = FieldWatcherConfig & { id: string; name: string; bundled: boolean };
+const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+// tsc emits this module one level below the package root; discovery stays in
+// the same shipped package directory in source and compiled entry points.
+const bundledDirectory = join(basename(moduleDirectory) === 'dist-mcp' ? dirname(moduleDirectory) : moduleDirectory, 'watchers');
+function watcherPath(path: unknown): string {
+  if (typeof path !== 'string' || path.length > 4096 || !isAbsolute(path) || /[\u0000-\u001f\u007f-\u009f]/u.test(path)) {
+    throw new Error('Watcher path must be an absolute executable file path (max 4096 characters)');
+  }
+  return normalize(path);
+}
+export function parseFieldWatchers(root: Record<string, unknown>): FieldWatcherConfig[] {
+  let entries = root.fieldWatchers;
+  if (entries === undefined) entries = root.fieldHandler == null ? [] : [{ path: root.fieldHandler, enabled: false }];
+  if (!Array.isArray(entries) || entries.length > 32) throw new Error('fieldWatchers must be an array of at most 32 watchers');
+  const seen = new Set<string>();
+  return entries.map((entry: unknown) => {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry) || Object.keys(entry).some((key) => key !== 'path' && key !== 'enabled')) throw new Error('Invalid field watcher');
+    const config = entry as Record<string, unknown>;
+    const path = watcherPath(config.path);
+    if (typeof config.enabled !== 'boolean' || seen.has(path)) throw new Error('Invalid or duplicate field watcher');
+    seen.add(path);
+    return { path, enabled: config.enabled };
+  });
+}
+/** Validation only: never starts the executable or invokes a shell. */
+export function validateWatcherExecutable(path: string): void {
+  const canonical = watcherPath(path);
+  if (!lstatSync(canonical).isFile()) throw new Error('Watcher must be a regular executable file');
+  accessSync(canonical, constants.X_OK);
+}
+export function discoverFieldWatchers(root: Record<string, unknown>): FieldWatcher[] {
+  const stored = parseFieldWatchers(root);
+  const bundled = new Set<string>();
+  for (const name of readdirSync(bundledDirectory).sort()) {
+    if (!name.endsWith('.mjs')) continue;
+    const path = join(bundledDirectory, name);
+    try { validateWatcherExecutable(path); bundled.add(path); } catch { /* Not a regular executable. */ }
+  }
+  const merged = [...stored, ...[...bundled].filter((path) => !stored.some((entry) => entry.path === path)).map((path) => ({ path, enabled: false }))];
+  if (merged.length > 32) throw new Error('At most 32 discovered field watchers are supported');
+  return merged.map((config) => ({ ...config, id: createHash('sha256').update(config.path).digest('hex'), name: basename(config.path) === 'github-pr.mjs' && bundled.has(config.path) ? 'GitHub PR' : basename(config.path, '.mjs'), bundled: bundled.has(config.path) }));
+}

package/footer-config.ts

@@ -2,6 +2,7 @@ import { getAgentDir } from "./config-path.ts";
 import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
+import { parseFieldWatchers, type FieldWatcherConfig } from "./field-watchers.ts";
 
 export const defaultHandoffPrompt = "Read the current Pinote task. Summarize your understanding, but don’t start work yet.";
 export const defaultNewSessionPrompt = defaultHandoffPrompt;
@@ -117,7 +118,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, newSessionPrompt?: string, taskOfferPolicy?: string, agentGuidance?: string | null) {
+export function saveFooterConfig(config: FooterConfig, expectedRaw: string | null, handoffPrompt?: string, newSessionPrompt?: string, taskOfferPolicy?: string, agentGuidance?: string | null, fieldWatchers?: FieldWatcherConfig[]) {
   if (taskOfferPolicy !== undefined && !["always", "github-remote", "never"].includes(taskOfferPolicy)) throw new Error("Invalid taskOfferPolicy");
   const checked = parseFooterConfig({ footer: config });
   const prompts = {
@@ -140,6 +141,10 @@ export function saveFooterConfig(config: FooterConfig, expectedRaw: string | nul
     const root = expectedRaw === null ? {} : JSON.parse(expectedRaw);
     if (!object(root)) throw new Error("Invalid pi-note configuration; expected an object.");
     if (agentGuidance === null) delete root.agentGuidance;
+    if (fieldWatchers !== undefined) {
+      root.fieldWatchers = parseFieldWatchers({ fieldWatchers });
+      delete root.fieldHandler;
+    }
     raw = `${JSON.stringify({ ...root, ...prompts, ...(taskOfferPolicy === undefined ? {} : { taskOfferPolicy }), footer: checked }, null, 2)}\n`;
     writeFileSync(temp, raw, { flag: "wx", mode: 0o600 });
     renameSync(temp, path);

package/mcp/FIELD_EVENTS.md

@@ -1,26 +1,40 @@
-# Field-event handler
+# Field watchers
 
-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.
+pi-note **0.40.0+** with **note 0.24.0+** runs independently enabled executables for
+task-field changes on the **HTTP service machine**. No extra daemon or Pi-local
+watcher is installed. The local-only extension and stdio service do not run watchers.
 
 ## Enable
 
-Create a trusted executable with a shebang, then add its absolute path to the
-service's `pi-note.json`, preserving existing settings:
+Open **Settings → Footer fields → Watchers**. The fixed package `watchers/` folder
+is scanned for executable `.mjs` files; discovery never executes or enables them.
+Enable **GitHub PR**, or add a custom absolute executable path on the service
+machine and enable it separately. Every change requires review and confirmation.
+Watchers are trusted code, not sandboxed; enabling authorizes their alerts to
+trigger the owning worker to investigate and fix the task within existing permissions.
+
+The corresponding service `pi-note.json` setting is:
 
 ```json
 {
-  "fieldHandler": "/absolute/path/field-events.mjs"
+  "fieldWatchers": [
+    { "path": "/absolute/path/watcher.mjs", "enabled": true }
+  ]
 }
 ```
 
-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.
+Update/restart the existing HTTP service and `/reload` Pi once after upgrading.
+Subsequent watcher changes apply live. Disable a watcher to stop checks and hide
+its results without changing task fields. Custom entries can also be removed;
+the file is retained. At most 32 watchers may be configured. For overlapping
+results, the first nonempty watcher result in configuration order supplies the
+footer style; alerts remain independent.
+
+`fieldHandler` is replaced, not run alongside the list. An old handler appears
+disabled until explicitly enabled because the previous setting authorized only
+notifications, not automatic worker actions. Saving watchers removes the old key.
 
-The bundled [`examples/field-events.mjs`](../examples/field-events.mjs) handles `PR`
+The bundled [`watchers/github-pr.mjs`](../watchers/github-pr.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
@@ -29,8 +43,8 @@ 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.
+To support another field, add another executable using the contract below. Each
+watcher receives all field events and returns `{}` for fields it does not handle.
 
 ## Script contract
 
@@ -91,6 +105,7 @@ are deduplicated; a resolved condition followed by another failure alerts again.
 - 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`.
+  Watcher cursors, jobs and notices are independent; alert ownership is shared.
   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
@@ -114,23 +129,31 @@ are deduplicated; a resolved condition followed by another failure alerts again.
   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.**
+- Pi triggers a worker turn once per current alert and persists receipts across
+  reload/resume (latest 4,096 IDs per branch). Receipts accompany view reads so
+  bounded 64-alert pages advance past delivered failures even if they persist.
+  Busy workers defer delivery until
+  idle, then refresh to verify ownership, selection and current status. An aborted
+  run does not immediately drain deferred alerts. There is no launch of a closed
+  Pi process; current alerts are delivered when its owning conversation reconnects.
+  Older clients/services retain notification-only behavior until both are updated.
+- Worker messages use fixed instructions plus explicitly untrusted observations;
+  the worker must verify fresh task context and obey existing scope and approvals.
+  Enabling never authorizes task selection/completion, PR merging or bypassing
+  approvals. Current results reach each agent run through fresh task-scoped
+  context; oversized results are omitted with a count, preserving the task first.
 - 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.
+- Newly enabled watchers reconstruct current fields from history independently.
+  Disabling/removing clears their automation state; enabling again checks afresh.
+  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
+human-confirmed Watchers UI can configure executable paths; agent tools cannot. 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.

package/mcp/README.md

@@ -141,12 +141,14 @@ 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.
+## Field watchers
+
+Manage `fieldWatchers` in **Settings → Footer fields → Watchers**. Bundled files
+are discovered disabled; trusted custom executables can be added and enabled.
+Independent checks survive restarts and settings apply live, without another daemon.
+The GitHub PR watcher triggers the owning worker on failed CI/conflicts and strikes
+through merged PRs. Requires note 0.24.0+. Review the
+[watcher contract and safeguards](FIELD_EVENTS.md) before enabling trusted code.
 
 ## Task-completion events