@hachej/boring-files 0.2.0 → 0.2.1

package/README.md

@@ -10,6 +10,12 @@ Opaque resource view IDs are provider-scoped and bound to the actual backing/inc
 
 The provider accepts all-or-nothing create and replace. It refuses working views, per-change requests and deletes (files are removed with the workspace's own tools) before any effect. Logical paths are relative to the workspace root; a path whose real location leaves the root is denied. A single file is replaced atomically by every backend; a multi-file batch only by the SQLite backend, together with its receipt when the journal shares the database. Access control is the host's, at the workspace boundary: there are no per-file permissions inside a workspace, and external revocation fencing is not implemented.
 
+### Agent writes and the change feed
+
+Agent writes are observed, never receipted ([owner ruling 2](../../docs/architecture/FILES-GIT-EXEC.md#one-place-for-files)). `provider.record({ path, before?, after, source: 'agent', conversationId? }, access)` is what the file guard (`@hachej/boring-agent/file-guard`) calls after a Pi `write` or `edit` succeeded: the file's history gains the written revision with `source: 'agent'` (and the replaced revision, `source: 'observed'`, when `before` carries its bytes), and the change feed an `agent` event. It never writes the publication journal and never mints a receipt. It does not enter the provider's queue (the guard already runs inside it), so calling it from queued work cannot deadlock. History entries (`saves`, `catalog.history`) carry `source`: `publish`, `agent` or `observed` (`keep` and replaced revisions).
+
+`provider.changes({ since?, signal }, access)` is one change feed for every file view: an `AsyncIterable` of `{ kind: 'change', path, revision | null, source: 'publish' | 'agent' | 'poll' | 'watch', seq, at }`, ordered by `seq` and replayable from `since` (the last `seq` seen; `changeHead()` is "now"). The provider retains the last `changeBuffer` events (default 1024); a cursor older than that, from another provider lifetime or ahead of this one, and a listener that falls behind get `{ kind: 'resnapshot', seq, at }`: reload everything shown, then continue. Events are invalidation hints; bytes and the journal stay authoritative. Sources: conditional writes (`publish`), `record` (`agent`), `poll` and, while someone listens (and `watchLingerMs` after, default 30 s), the file system's own `watch` (`watch`; a reported directory is `{ revision: null, directory: true }`). The SQLite file system reports writes through its own connection at once and polls every second for other connections. When the file system cannot watch (the virtual and remote environments report `not_supported`), the host calls `provider.poll()` at the end of each agent turn: without paths it hashes every file (not `.git` or `node_modules`); the first call takes the baseline, later ones report changed, new and removed files. A `bash` write gets change events only, never history. After the last listener leaves the watcher lingers and then closes; changes made while no watcher was open are unknown, so the first listener afterwards makes the feed append a `resnapshot` (a client that stays connected is never affected). `changeIncarnation` names the provider lifetime: a cursor sent with another `incarnation` is a `resnapshot` whatever its number. `provider.close()` ends every change stream, closes the watcher and drops the listeners.
+
 Receipts are scoped by workspace identity, principal, scope and initiator. Identical committed retries return the original receipt; changed arguments conflict. Refused operations do not reserve an ID. A receipt from an earlier incarnation of the workspace reads `unknown`. A not-found lookup is not permission to replay an uncertain operation.
 
 `@hachej/boring-files/publication` is browser-safe. It captures request bytes, computes a versioned canonical SHA-256 digest with WebCrypto, and parses result shapes. Digests carry `boring-publication-v1:sha256:` and bind that format identifier in the hashed payload. Consumers must also check operation, target, scope and index association against their own request. This module confers no authorization. The SQLite connection (`openNodeConnection` from `@hachej/boring-files/sqlite`) is a separate server entry point.
@@ -138,7 +144,21 @@ const revisionProvider = await connectRevisionProvider({
 
 The binding discovers identity and workspace incarnation from the authenticated
 server. Reconnect when the selected workspace changes. It exposes `list`,
-filename `search`, retained `history`, `locate`, `read`, `publish` and `lookup`.
+filename `search`, retained `history`, `locate`, `read`, `publish`, `lookup` and
+`changes({ since?, signal })`, the workspace's change feed.
+
+The feed is `GET <endpoint>?op=changes[&since=<seq>&incarnation=<id>]` with the binding header:
+server-sent events (`event: ready` with the current seq and the provider incarnation, then `event: change` or
+`event: resnapshot` with `id:` the seq and the JSON event as `data:`), and a
+comment line every `heartbeatMs` (`createRevisionHandler({ resolve, heartbeatMs })`,
+default 15 s). It is a plain streamed response with no queue (pull-based), so a slow client
+costs the provider's bounded replay buffer and a `resnapshot`, never memory in
+the handler; revocation discards anything unread. It runs on Node and Workers
+alike. The handler holds the workspace lease for the life of the stream and
+releases it when the client disconnects or its access signal aborts; a request
+the host refuses, or whose binding names another workspace or identity, gets no
+event (403 or 409). The client reconnects after the last seq it delivered, with
+backoff, until its `signal` aborts; a refusal ends it with a `RevisionError`.
 All writes use conditional publication; uploading a new file requires absence,
 and replacing one requires its exact resource revision. An unknown result must
 be reconciled by operation ID before another upload to that path.

package/dist/journal.d.ts

@@ -38,7 +38,13 @@ export interface StoredVersion {
     readonly mediaType: string;
     /** When this revision was saved, in milliseconds since the epoch. Kept the first time the revision is retained. */
     readonly savedAt?: number;
+    /**
+     * Who produced the revision: `publish` (a conditional write), `agent` (a Pi `write` or `edit`, recorded by `provider.record`: it
+     * has no receipt) or `observed` (retained as found: `keep`, or the replaced revision of a write). Default `publish`.
+     */
+    readonly source?: HistorySource;
 }
+export type HistorySource = 'publish' | 'agent' | 'observed';
 /**
  * The operation journal plus what a workspace needs beyond receipts: an intent row written before an operation's first effect
  * (an intent without a completion is an operation of unknown outcome), and the last versions of each file when there is no Git.
@@ -68,6 +74,7 @@ export interface WorkspaceJournal extends OperationJournal {
     readonly saves: (scope: string, path: string) => {
         readonly revision: string;
         readonly savedAt: number;
+        readonly source: HistorySource;
     }[];
 }
 export declare function createWorkspaceJournal(db: SqliteConnection, options?: {

package/dist/journal.js

@@ -59,6 +59,7 @@ export function committedChanges(changes, ref) {
         throw new Error('Stored operation has no changes');
     return [first, ...rest];
 }
+const historySource = (value) => value === 'agent' || value === 'observed' ? value : 'publish';
 export function createWorkspaceJournal(db, options = {}) {
     const limit = options.historyLimit ?? 20;
     if (!Number.isSafeInteger(limit) || limit < 1)
@@ -74,18 +75,22 @@ export function createWorkspaceJournal(db, options = {}) {
       ) STRICT;
       CREATE TABLE IF NOT EXISTS boring_history (
         scope TEXT NOT NULL, path TEXT NOT NULL, revision TEXT NOT NULL, sequence INTEGER NOT NULL,
-        bytes BLOB NOT NULL, media_type TEXT NOT NULL, saved_at INTEGER NOT NULL DEFAULT 0,
+        bytes BLOB NOT NULL, media_type TEXT NOT NULL, saved_at INTEGER NOT NULL DEFAULT 0, source TEXT NOT NULL DEFAULT 'publish',
         PRIMARY KEY (scope, path, revision)
       ) STRICT;
     `);
         // A journal created before save times were recorded gets the column; its old rows read as unknown (0).
         if (!db.all("SELECT name FROM pragma_table_info('boring_history')").some(column => column.name === 'saved_at'))
             db.exec('ALTER TABLE boring_history ADD COLUMN saved_at INTEGER NOT NULL DEFAULT 0');
+        // A journal created before history recorded who wrote each revision: its old rows were all conditional writes.
+        if (!db.all("SELECT name FROM pragma_table_info('boring_history')").some(column => column.name === 'source'))
+            db.exec("ALTER TABLE boring_history ADD COLUMN source TEXT NOT NULL DEFAULT 'publish'");
     });
     const remember = (scope, path, version) => {
         const last = db.get('SELECT COALESCE(MAX(sequence), 0) AS last FROM boring_history WHERE scope = ? AND path = ?', scope, path);
         const sequence = Number(last?.last ?? 0) + 1;
-        db.run('INSERT INTO boring_history (scope, path, revision, sequence, bytes, media_type, saved_at) VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(scope, path, revision) DO UPDATE SET sequence = excluded.sequence, bytes = excluded.bytes, media_type = excluded.media_type, saved_at = CASE WHEN boring_history.saved_at = 0 THEN excluded.saved_at ELSE boring_history.saved_at END', scope, path, version.revision, sequence, version.bytes, version.mediaType, version.savedAt ?? 0);
+        // A revision found again (`observed`) keeps the writer it was first recorded with; a new write of the same bytes names its writer.
+        db.run("INSERT INTO boring_history (scope, path, revision, sequence, bytes, media_type, saved_at, source) VALUES (?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(scope, path, revision) DO UPDATE SET sequence = excluded.sequence, bytes = excluded.bytes, media_type = excluded.media_type, saved_at = CASE WHEN boring_history.saved_at = 0 THEN excluded.saved_at ELSE boring_history.saved_at END, source = CASE WHEN excluded.source = 'observed' THEN boring_history.source ELSE excluded.source END", scope, path, version.revision, sequence, version.bytes, version.mediaType, version.savedAt ?? 0, historySource(version.source));
         db.run('DELETE FROM boring_history WHERE scope = ? AND path = ? AND revision NOT IN (SELECT revision FROM boring_history WHERE scope = ? AND path = ? ORDER BY sequence DESC LIMIT ?)', scope, path, scope, path, limit);
     };
     const journal = {
@@ -112,7 +117,7 @@ export function createWorkspaceJournal(db, options = {}) {
             return { revision, bytes: Uint8Array.from(row.bytes), mediaType: text(row.media_type) };
         },
         revisions: (scope, path) => db.all('SELECT revision FROM boring_history WHERE scope = ? AND path = ? ORDER BY sequence DESC', scope, path).map(row => text(row.revision)),
-        saves: (scope, path) => db.all('SELECT revision, saved_at FROM boring_history WHERE scope = ? AND path = ? ORDER BY sequence DESC', scope, path).map(row => ({ revision: text(row.revision), savedAt: Number(row.saved_at) })),
+        saves: (scope, path) => db.all('SELECT revision, saved_at, source FROM boring_history WHERE scope = ? AND path = ? ORDER BY sequence DESC', scope, path).map(row => ({ revision: text(row.revision), savedAt: Number(row.saved_at), source: historySource(row.source) })),
     };
     registerJournalConnection(journal, db);
     return journal;

package/dist/revision-contracts.d.ts

@@ -24,6 +24,41 @@ export interface FileSearchRequest {
 export interface SavedRevision {
     readonly revision: string;
     readonly savedAt: number;
+    /** Who wrote it: `publish` (a conditional write), `agent` (a Pi `write` or `edit`: observed, never receipted) or `observed` (retained as found). */
+    readonly source?: 'publish' | 'agent' | 'observed';
+}
+/**
+ * One entry of a workspace's change feed (ruling 2 of 2026-10-10): an invalidation hint, never content or a receipt. Bytes and
+ * the publication journal stay authoritative; a viewer that receives one reads again.
+ *
+ * - `change`: something at `path` changed. `revision` is the Git blob id now there, or `null` when the path is absent or is a
+ *   directory (`directory: true`: something below it may have changed). `source`: `publish` (a conditional write), `agent` (a Pi
+ *   `write` or `edit`), `poll` (found by hashing, for example after a `bash` command) or `watch` (reported by the file system).
+ * - `resnapshot`: events were lost (the cursor is older than the retained window, from another provider lifetime, or the watcher
+ *   overflowed or restarted). Reload everything shown, then continue after this `seq`.
+ *
+ * `seq` increases strictly within one provider lifetime; `at` is milliseconds since the epoch.
+ */
+export type WorkspaceChangeEvent = {
+    readonly kind: 'change';
+    readonly path: string;
+    readonly revision: string | null;
+    readonly source: 'publish' | 'agent' | 'poll' | 'watch';
+    readonly seq: number;
+    readonly at: number;
+    readonly directory?: true;
+    readonly conversationId?: string;
+} | {
+    readonly kind: 'resnapshot';
+    readonly seq: number;
+    readonly at: number;
+};
+export interface ChangeFeedRequest {
+    /** The last `seq` already seen: only later events are delivered (a gap is a `resnapshot`). Absent: live events only. */
+    readonly since?: number | undefined;
+    /** The provider lifetime `since` came from (`ready` event). A cursor from another lifetime is a `resnapshot`, whatever its number. */
+    readonly incarnation?: string | undefined;
+    readonly signal?: AbortSignal | undefined;
 }
 export interface WorkspaceCatalog {
     readonly list: (request: FileListRequest, access: ResourceAccess) => Promise<FilePage>;
@@ -44,5 +79,11 @@ export interface RevisionProvider extends ResourceClient {
     readonly list: (request: FileListRequest, signal?: AbortSignal) => Promise<FilePage>;
     readonly search: (request: FileSearchRequest, signal?: AbortSignal) => Promise<FilePage>;
     readonly history: (path: string, signal?: AbortSignal) => Promise<readonly SavedRevision[]>;
+    /**
+     * The workspace's change feed (`GET ?op=changes`, server-sent events), reconnecting after the last `seq` seen until `signal`
+     * aborts; a refused binding (another workspace, revoked access) ends it with a `RevisionError`. Optional: a hand-built provider
+     * may have none, and a viewer then refreshes on its own schedule.
+     */
+    readonly changes?: (request?: ChangeFeedRequest) => AsyncIterable<WorkspaceChangeEvent>;
 }
 //# sourceMappingURL=revision-contracts.d.ts.map

package/dist/revision-handler.d.ts

@@ -1,11 +1,14 @@
 import type { ResourceAccess } from './contracts.js';
 import type { WorkspaceResourceProvider } from './workspace.js';
 export interface RevisionHandlerOptions {
+    /** The host's authentication and workspace selection, once per request. For the change feed the lease is held until the stream ends. */
     readonly resolve: (request: Request) => Promise<null | {
         readonly provider: WorkspaceResourceProvider;
         readonly access: ResourceAccess;
         readonly release?: () => void | Promise<void>;
     }>;
+    /** How often the change feed sends a comment line so proxies keep it open, in milliseconds (default 15 000). */
+    readonly heartbeatMs?: number;
 }
 export declare function createRevisionHandler(options: RevisionHandlerOptions): (request: Request) => Promise<Response>;
 //# sourceMappingURL=revision-handler.d.ts.map

package/dist/revision-handler.js

@@ -3,6 +3,90 @@ import { binding, bindingHeader, bindingValue, catalogHeader, filePage, record,
 import { guardStatus, readJsonBody, RequestGuardError } from './request-guard.js';
 import { accessSnapshot, identifier } from './publication-input.js';
 import { RevisionError } from './revision-contracts.js';
+const encoder = new TextEncoder();
+/**
+ * `GET ?op=changes[&since=<seq>&incarnation=<id>]`: the workspace's change feed as server-sent events (`event: change | resnapshot`,
+ * `id:` the seq, `data:` the JSON event), after an `event: ready` naming the current seq and the provider's incarnation, with a
+ * comment every `heartbeatMs` while idle. Plain streamed responses, so it runs on Node and on Workers alike.
+ *
+ * The stream is pull-based with no queue (`highWaterMark: 0`): the provider is read only while the client is reading, so a slow
+ * client costs the provider's bounded replay buffer (and a `resnapshot` when it falls behind), never unbounded memory here. The
+ * stream ends when the person disconnects or their access is revoked, discarding anything not yet read, and the workspace lease is
+ * released then.
+ */
+function changeStream(provider, access, request, heartbeatMs, release) {
+    const stop = new AbortController();
+    const signal = AbortSignal.any([access.signal, stop.signal, provider.lifetime]);
+    let iterator;
+    let pending;
+    let ready = false, ended = false;
+    const finish = () => {
+        if (ended)
+            return;
+        ended = true;
+        stop.abort();
+        void iterator?.return?.().catch(() => { });
+        void release();
+    };
+    const body = new ReadableStream({
+        start: controller => {
+            const close = () => { finish(); try {
+                controller.close();
+            }
+            catch { /* already closed or cancelled */ } };
+            signal.addEventListener('abort', close, { once: true });
+            if (signal.aborted)
+                close();
+        },
+        pull: async (controller) => {
+            if (ended)
+                return;
+            const send = (text) => { try {
+                controller.enqueue(encoder.encode(text));
+            }
+            catch {
+                finish();
+            } };
+            const end = () => { finish(); try {
+                controller.close();
+            }
+            catch { /* already closed */ } };
+            try {
+                if (!ready) {
+                    ready = true;
+                    // Without a cursor the feed starts at the current seq, which the client learns first and resumes from after a disconnect.
+                    const start = request.since ?? provider.changeHead();
+                    iterator = provider.changes({ since: start, ...(request.incarnation === undefined ? {} : { incarnation: request.incarnation }), signal }, { ...access, signal })[Symbol.asyncIterator]();
+                    // An async iterator runs its body only on the first pull, so prime it here: the watcher then starts before `ready`, and a
+                    // write the client makes after reading `ready` is not missed.
+                    pending = iterator.next();
+                    pending.catch(() => { });
+                    send(`event: ready\ndata: ${JSON.stringify({ seq: start, incarnation: provider.changeIncarnation })}\n\n`);
+                    return;
+                }
+                pending ??= iterator.next();
+                pending.catch(() => { });
+                let timer;
+                const beat = new Promise(resolve => { timer = setTimeout(() => resolve('beat'), heartbeatMs); });
+                const outcome = await Promise.race([pending, beat]).finally(() => clearTimeout(timer));
+                if (signal.aborted)
+                    return end();
+                if (outcome === 'beat')
+                    return send(': heartbeat\n\n');
+                pending = undefined;
+                if (outcome.done)
+                    return end();
+                const event = outcome.value;
+                send(`id: ${event.seq}\nevent: ${event.kind}\ndata: ${JSON.stringify(event)}\n\n`);
+            }
+            catch {
+                end(); /* the client reconnects from its last seq */
+            }
+        },
+        cancel: () => { finish(); },
+    }, { highWaterMark: 0 });
+    return new Response(body, { headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-store', 'x-accel-buffering': 'no' } });
+}
 function listRequest(value) {
     const data = record(value);
     if ((data.directory !== undefined && typeof data.directory !== 'string') || (data.cursor !== undefined && typeof data.cursor !== 'string') || (data.limit !== undefined && typeof data.limit !== 'number'))
@@ -10,6 +94,9 @@ function listRequest(value) {
     return { ...(typeof data.directory === 'string' ? { directory: data.directory } : {}), ...(typeof data.cursor === 'string' ? { cursor: data.cursor } : {}), ...(typeof data.limit === 'number' ? { limit: data.limit } : {}) };
 }
 export function createRevisionHandler(options) {
+    const heartbeatMs = options.heartbeatMs ?? 15_000;
+    if (!Number.isSafeInteger(heartbeatMs) || heartbeatMs < 1)
+        throw new RangeError('The heartbeat interval must be a positive integer');
     return async (request) => {
         let release;
         const operations = new Set();
@@ -34,7 +121,8 @@ export function createRevisionHandler(options) {
                 return refuse(403);
             const association = binding({ identity: captured, workspace: selected.provider.identity });
             const respond = (value) => Response.json(value, { headers: { 'cache-control': 'no-store' } });
-            if (request.method === 'GET')
+            const op = new URL(request.url).searchParams.get('op');
+            if (request.method === 'GET' && op === null)
                 return respond(association);
             const header = request.headers.get(bindingHeader);
             if (!header || header.length > 16384)
@@ -49,6 +137,26 @@ export function createRevisionHandler(options) {
             if (requested !== bindingValue(association))
                 return refuse(409);
             const provider = selected.provider;
+            if (request.method === 'GET') {
+                if (op !== 'changes')
+                    return refuse(400);
+                const cursor = new URL(request.url).searchParams.get('since');
+                if (cursor !== null && !/^\d{1,16}$/.test(cursor))
+                    return refuse(400);
+                const since = cursor === null ? undefined : Number(cursor);
+                const incarnation = new URL(request.url).searchParams.get('incarnation') ?? undefined;
+                if (incarnation !== undefined && !/^[\w-]{1,64}$/.test(incarnation))
+                    return refuse(400);
+                if (since !== undefined && !Number.isSafeInteger(since))
+                    return refuse(400);
+                // The stream owns the lease from here: it is released when the stream ends, not when this function returns.
+                const lease = release;
+                release = undefined;
+                return changeStream(provider, access, { since, incarnation }, heartbeatMs, async () => { try {
+                    await lease?.();
+                }
+                catch { /* the stream already ended */ } });
+            }
             if (!request.headers.has(catalogHeader))
                 return await createResourceHandler({
                     authenticate: async () => access,

package/dist/revision-protocol.d.ts

@@ -1,6 +1,6 @@
 import type { ResourceIdentity } from './remote-protocol.js';
 import type { WorkspaceKey } from './workspace.js';
-import type { FilePage, SavedRevision } from './revision-contracts.js';
+import type { FilePage, SavedRevision, WorkspaceChangeEvent } from './revision-contracts.js';
 export declare const bindingHeader = "x-boring-workspace";
 export declare const catalogHeader = "x-boring-catalog";
 export interface RevisionBinding {
@@ -12,4 +12,11 @@ export declare function binding(value: unknown): RevisionBinding;
 export declare const bindingValue: (value: RevisionBinding) => string;
 export declare function filePage(value: unknown): FilePage;
 export declare function savedRevisions(value: unknown): readonly SavedRevision[];
+/** One change-feed event as the server sent it, checked field by field (`data:` of `event: change | resnapshot`). */
+export declare function changeEvent(value: unknown): WorkspaceChangeEvent;
+/** Server-sent events from a response body: `{ event, data }` per message, comments skipped, a line longer than `limit` refused. */
+export declare function serverEvents(body: ReadableStream<Uint8Array>, limit?: number): AsyncGenerator<{
+    readonly event: string;
+    readonly data: string;
+}>;
 //# sourceMappingURL=revision-protocol.d.ts.map

package/dist/revision-protocol.js

@@ -37,6 +37,70 @@ export function savedRevisions(value) {
         const entry = record(item);
         if (typeof entry.savedAt !== 'number' || !Number.isSafeInteger(entry.savedAt) || entry.savedAt < 0)
             throw new RevisionError('invalid', 'Invalid save timestamp');
-        return { revision: identifier(entry.revision), savedAt: entry.savedAt };
+        const source = entry.source === 'publish' || entry.source === 'agent' || entry.source === 'observed' ? entry.source : undefined;
+        return { revision: identifier(entry.revision), savedAt: entry.savedAt, ...(source ? { source } : {}) };
     });
 }
+const sources = new Set(['publish', 'agent', 'poll', 'watch']);
+const sequence = (value, what) => {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        throw new RevisionError('invalid', `Invalid ${what}`);
+    return value;
+};
+/** One change-feed event as the server sent it, checked field by field (`data:` of `event: change | resnapshot`). */
+export function changeEvent(value) {
+    const data = record(value);
+    const seq = sequence(data.seq, 'change sequence'), at = sequence(data.at, 'change time');
+    if (data.kind === 'resnapshot')
+        return { kind: 'resnapshot', seq, at };
+    if (data.kind !== 'change' || typeof data.path !== 'string' || typeof data.source !== 'string' || !sources.has(data.source))
+        throw new RevisionError('invalid', 'Invalid change event');
+    if (data.directory !== undefined && data.directory !== true)
+        throw new RevisionError('invalid', 'Invalid change event');
+    const path = data.path === '' && data.directory === true ? '' : catalogPath(data.path);
+    const revision = data.revision === null ? null : identifier(data.revision);
+    return {
+        kind: 'change', path, revision, source: data.source, seq, at,
+        ...(data.directory === true ? { directory: true } : {}),
+        ...(data.conversationId !== undefined ? { conversationId: identifier(data.conversationId) } : {}),
+    };
+}
+/** Server-sent events from a response body: `{ event, data }` per message, comments skipped, a line longer than `limit` refused. */
+export async function* serverEvents(body, limit = 1_048_576) {
+    const reader = body.getReader(), decoder = new TextDecoder();
+    let pending = '', event = 'message', data = [];
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                return;
+            pending += decoder.decode(value, { stream: true });
+            let newline;
+            while ((newline = pending.search(/\r?\n/)) !== -1) {
+                const line = pending.slice(0, newline);
+                pending = pending.slice(pending[newline] === '\r' ? newline + 2 : newline + 1);
+                if (line === '') {
+                    if (data.length)
+                        yield { event, data: data.join('\n') };
+                    event = 'message';
+                    data = [];
+                    continue;
+                }
+                if (line.startsWith(':'))
+                    continue;
+                const colon = line.indexOf(':');
+                const field = colon === -1 ? line : line.slice(0, colon);
+                const content = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '');
+                if (field === 'event')
+                    event = content;
+                else if (field === 'data')
+                    data.push(content);
+            }
+            if (pending.length > limit)
+                throw new RevisionError('invalid', 'Change feed line exceeds the limit');
+        }
+    }
+    finally {
+        void reader.cancel().catch(() => { });
+    }
+}

package/dist/revision.js

@@ -1,5 +1,5 @@
 import { createResourceClient } from './remote.js';
-import { binding, bindingHeader, bindingValue, catalogHeader, filePage, record, savedRevisions } from './revision-protocol.js';
+import { binding, bindingHeader, bindingValue, catalogHeader, changeEvent, filePage, record, savedRevisions, serverEvents } from './revision-protocol.js';
 import { readJsonBody } from './request-guard.js';
 import { RevisionError } from './revision-contracts.js';
 import { observe } from './remote-protocol.js';
@@ -45,6 +45,93 @@ export async function connectRevisionProvider(options) {
             throw new RevisionError('denied', 'The response belongs to another workspace');
         return result.value;
     }
+    /** One feed across reconnections: each resumes after the last seq delivered; a refused binding ends it. */
+    async function* changes(request = {}) {
+        const signal = request.signal;
+        let cursor = request.since, incarnation = request.incarnation, staged, delay = 500;
+        const pause = () => new Promise(resolve => {
+            const timer = setTimeout(done, delay);
+            function done() { clearTimeout(timer); signal?.removeEventListener('abort', done); resolve(); }
+            signal?.addEventListener('abort', done, { once: true });
+            delay = Math.min(delay * 2, 30_000);
+        });
+        while (!signal?.aborted) {
+            const url = new URL(endpoint);
+            url.searchParams.set('op', 'changes');
+            if (cursor !== undefined) {
+                url.searchParams.set('since', String(cursor));
+                if (incarnation !== undefined)
+                    url.searchParams.set('incarnation', incarnation);
+            }
+            const connection = new AbortController();
+            const stop = () => connection.abort();
+            signal?.addEventListener('abort', stop, { once: true });
+            try {
+                let response;
+                try {
+                    response = await fetch(new Request(url, { method: 'GET', redirect: 'error', headers: { accept: 'text/event-stream', [bindingHeader]: bound }, signal: connection.signal }));
+                }
+                catch {
+                    if (signal?.aborted)
+                        return;
+                    await pause();
+                    continue;
+                }
+                if (response.redirected || !response.ok || !response.body) {
+                    void response.body?.cancel().catch(() => { });
+                    if (response.status === 403 || response.status === 409)
+                        throw new RevisionError('denied', 'The selected workspace is unavailable or no longer authorized');
+                    if (response.status === 400)
+                        throw new RevisionError('invalid', 'The change feed request was refused');
+                    await pause();
+                    continue;
+                }
+                try {
+                    for await (const message of serverEvents(response.body)) {
+                        if (message.event === 'ready') {
+                            const ready = record(JSON.parse(message.data)), seq = ready.seq;
+                            // A new provider lifetime is adopted with its resnapshot, not with `ready`: a disconnect in between must reconnect with the
+                            // old cursor and incarnation, which the server answers with a resnapshot again.
+                            if (typeof ready.incarnation === 'string') {
+                                if (cursor === undefined || incarnation === undefined)
+                                    incarnation = ready.incarnation;
+                                else
+                                    staged = ready.incarnation;
+                            }
+                            if (cursor === undefined && typeof seq === 'number' && Number.isSafeInteger(seq))
+                                cursor = seq;
+                            delay = 500;
+                            continue;
+                        }
+                        if (message.event !== 'change' && message.event !== 'resnapshot')
+                            continue;
+                        const event = changeEvent(JSON.parse(message.data));
+                        if (event.kind === 'change' && cursor !== undefined && event.seq <= cursor)
+                            continue;
+                        if (event.kind === 'resnapshot' && staged !== undefined) {
+                            incarnation = staged;
+                            staged = undefined;
+                        }
+                        cursor = event.seq;
+                        yield event;
+                    }
+                }
+                catch (error) {
+                    if (signal?.aborted)
+                        return;
+                    if (error instanceof RevisionError && error.kind === 'invalid')
+                        throw error;
+                }
+            }
+            finally {
+                signal?.removeEventListener('abort', stop);
+                connection.abort();
+            }
+            if (signal?.aborted)
+                return;
+            await pause();
+        }
+    }
     if (!client.publish || !client.lookup)
         throw new Error('Publishing client lacks reconciliation');
     return {
@@ -53,5 +140,6 @@ export async function connectRevisionProvider(options) {
         list: async (request, signal) => filePage(await invoke('list', request, signal)),
         search: async (request, signal) => filePage(await invoke('search', request, signal)),
         history: async (path, signal) => savedRevisions(await invoke('history', path, signal)),
+        changes: request => changes(request),
     };
 }

package/dist/sqlite-filesystem.js

@@ -20,7 +20,10 @@ const within = (base, path) => path === base || path.startsWith(base === '/' ? '
 // system answers exactly like Pi's environments.
 const fileError = (code, message, path) => new FileError(code, message, path);
 const isFileError = (error) => error instanceof FileError;
-/** How often a watcher compares snapshots: SQLite reports no changes, so the watcher polls (`mode: 'polling'`). */
+/**
+ * How often a watcher compares snapshots. A write through this file system (this connection) is compared at once, right after
+ * its transaction; polling remains for writes through another connection to the same database (`mode: 'polling'`).
+ */
 const WATCH_INTERVAL_MS = 1000;
 /** A FileError whose message starts with the POSIX code, as shells and Git read it. */
 const failure = (code, errno, path, what) => fileError(code, `${errno}: ${what}, '${path}'`, path);
@@ -65,6 +68,8 @@ export function openSqliteFileSystem(options) {
         if (found.kind !== 'directory')
             throw failure('not_directory', 'ENOTDIR', path, 'not a directory');
     }
+    /** Paths written, renamed or removed by this file system since the last comparison: reported as changed even when size and time look alike. */
+    const touched = new Set();
     function bytes(path) {
         if (existing(path).kind === 'directory')
             throw failure('is_directory', 'EISDIR', path, 'illegal operation on a directory');
@@ -74,6 +79,7 @@ export function openSqliteFileSystem(options) {
         return Uint8Array.from(found.bytes);
     }
     function put(path, kind, content) {
+        touched.add(path);
         db.run('INSERT INTO boring_workspace_files (workspace, path, parent, kind, bytes, mtime_ms) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT(workspace, path) DO UPDATE SET kind = excluded.kind, bytes = excluded.bytes, mtime_ms = excluded.mtime_ms', workspace, path, dirname(path), kind, content, now());
     }
     function write(path, content) {
@@ -125,13 +131,31 @@ export function openSqliteFileSystem(options) {
     const incarnation = db.get('SELECT incarnation FROM boring_workspaces WHERE workspace = ?', workspace)?.incarnation;
     if (typeof incarnation !== 'string')
         throw new Error('The workspace has no incarnation');
+    /** Each open watcher's comparison, run right after a write through this file system commits. */
+    const watchers = new Set();
+    let notifying = false;
+    function notify() {
+        if (watchers.size === 0) {
+            touched.clear();
+            return;
+        }
+        if (notifying)
+            return;
+        notifying = true;
+        // After the current synchronous work: a batch write inside a caller's transaction is compared once it has committed.
+        queueMicrotask(() => { notifying = false; const paths = [...touched]; touched.clear(); for (const check of [...watchers])
+            check(paths); });
+    }
     async function run(path, context, mode, work) {
         if (context.abortSignal?.aborted)
             return err(fileError('aborted', 'Operation aborted', path));
         if (typeof path !== 'string' || path.includes('\0'))
             return err(fileError('invalid', 'Invalid path', String(path)));
         try {
-            return ok(db.transaction(mode, () => work(normalize(path.startsWith('/') ? path : `${fs.cwd}/${path}`))));
+            const value = db.transaction(mode, () => work(normalize(path.startsWith('/') ? path : `${fs.cwd}/${path}`)));
+            if (mode === 'write')
+                notify();
+            return ok(value);
         }
         catch (error) {
             return err(isFileError(error) ? error : fileError('unknown', error instanceof Error ? error.message : String(error), path));
@@ -264,6 +288,8 @@ export function openSqliteFileSystem(options) {
             const moved = existing(from);
             if (from === to)
                 return;
+            touched.add(from);
+            touched.add(to);
             if (from === '/' || within(from, to))
                 throw failure('invalid', 'EINVAL', to, 'cannot move a directory into itself');
             const target = row(to);
@@ -306,8 +332,9 @@ export function openSqliteFileSystem(options) {
             };
             return reader;
         }),
-        // SQLite reports no changes, so the watcher compares snapshots of the watched rows. The first snapshot is taken before the
-        // watcher is returned, so a change made after `watch` resolves is always seen.
+        // SQLite reports no changes, so the watcher compares snapshots of the watched rows: at once after each write through this file
+        // system, and every second for other connections. The first snapshot is taken before the watcher is returned, so a change made
+        // after `watch` resolves is always seen.
         watch: async (targets, onChange, context) => {
             if (context.abortSignal?.aborted)
                 return err(fileError('aborted', 'Operation aborted'));
@@ -326,7 +353,18 @@ export function openSqliteFileSystem(options) {
                     onChange(change);
                 }
                 catch { /* the host's callback cannot stop the watcher */ } };
-            const timer = setInterval(() => {
+            const hidden = (name, target) => (target.exclude?.hidden && name.startsWith('.')) || target.exclude?.names?.includes(name);
+            /** Whether a path this file system just wrote lies under a watched target, as the snapshot would have listed it. */
+            const covered = (path) => targets.some(target => {
+                const root = normalize(target.path.startsWith('/') ? target.path : `${fs.cwd}/${target.path}`);
+                if (path === root)
+                    return true;
+                if (!within(root, path))
+                    return false;
+                const names = path.slice(root.length + (root === '/' ? 0 : 1)).split('/');
+                return (target.recursive || names.length === 1) && !names.some(name => hidden(name, target));
+            });
+            const check = (direct = []) => {
                 if (stopped)
                     return;
                 let next;
@@ -335,16 +373,19 @@ export function openSqliteFileSystem(options) {
                 }
                 catch (error) {
                     report({ error: isFileError(error) ? error : fileError('unknown', String(error)) });
-                    stopped = true;
-                    clearInterval(timer);
+                    stop();
                     return;
                 }
-                const changed = [...new Set([...previous.keys(), ...next.keys()])].filter(path => previous.get(path) !== next.get(path));
+                const written = new Set(direct.filter(covered));
+                const changed = [...new Set([...previous.keys(), ...next.keys(), ...written])].filter(path => written.has(path) || previous.get(path) !== next.get(path));
                 previous = next;
                 if (changed.length)
                     report({ paths: changed });
-            }, WATCH_INTERVAL_MS);
-            const watcher = { mode: 'polling', close: async () => { stopped = true; clearInterval(timer); } };
+            };
+            const timer = setInterval(() => check(), WATCH_INTERVAL_MS);
+            const stop = () => { stopped = true; clearInterval(timer); watchers.delete(check); };
+            watchers.add(check);
+            const watcher = { mode: 'polling', close: async () => { stop(); } };
             return ok(watcher);
         },
         canonicalPath: (path, context) => run(path, context, 'read', absolute => { existing(absolute); return absolute; }),
@@ -366,6 +407,7 @@ export function openSqliteFileSystem(options) {
                 throw failure('permission_denied', 'EPERM', absolute, 'the workspace root cannot be removed');
             if (found.kind === 'directory' && !options?.recursive && children(absolute).length)
                 throw failure('invalid', 'ENOTEMPTY', absolute, 'directory not empty');
+            touched.add(absolute);
             db.run(`DELETE FROM boring_workspace_files WHERE ${subtree(absolute)}`, ...subtreeArgs(absolute));
         }),
         createTempDir: (prefix, context) => temporary(prefix ?? 'tmp-', '', 'directory', context),
@@ -375,7 +417,7 @@ export function openSqliteFileSystem(options) {
     registerSqliteBatch(fs, {
         connection: db,
         bytes: path => { const found = row(normalize(path)); return !found ? null : found.kind === 'directory' ? undefined : bytes(normalize(path)); },
-        write: (path, content) => { const absolute = normalize(path); makeDirectory(dirname(absolute), true); write(absolute, content); },
+        write: (path, content) => { const absolute = normalize(path); makeDirectory(dirname(absolute), true); write(absolute, content); notify(); },
     });
     return fs;
 }

package/dist/workspace.d.ts

@@ -1,16 +1,32 @@
 import type { FileSystem } from '@earendil-works/pi-durable/env';
 import type { PublicationLookupResult, PublicationResult, ReadResult, ResourceAccess, ResourceProvider } from './contracts.js';
 import type { WorkspaceCatalogOptions } from './workspace-catalog.js';
-import type { WorkspaceCatalog } from './revision-contracts.js';
+import type { ChangeFeedRequest, WorkspaceCatalog, WorkspaceChangeEvent } from './revision-contracts.js';
+export type { ChangeFeedRequest, WorkspaceChangeEvent } from './revision-contracts.js';
 export type { WorkspaceCatalogOptions } from './workspace-catalog.js';
-import type { WorkspaceJournal } from './journal.js';
+import type { HistorySource, WorkspaceJournal } from './journal.js';
 import type { WorkspaceKey } from './workspace-identity.js';
 export type { WorkspaceKey } from './workspace-identity.js';
 export interface WorkspaceChange {
     readonly path: string;
-    /** `null` when the file is absent. */
+    /** `null` when the file is absent (or, from a watcher, when the path is a directory). */
     readonly revision: string | null;
-    readonly source: 'provider' | 'poll';
+    /** `publish`: a conditional write. `agent`: `record` (a Pi `write` or `edit`). `poll`: found by hashing. `watch`: the file system reported it. */
+    readonly source: 'publish' | 'agent' | 'poll' | 'watch';
+}
+/** What `record` is told about an agent write (ruling 2: observed, never receipted). */
+export interface AgentWrite {
+    readonly path: string;
+    /** The file before the write, when it existed: its revision and the bytes of that revision (kept in history as the replaced version). */
+    readonly before?: {
+        readonly revision: string;
+        readonly bytes: Uint8Array;
+    } | null | undefined;
+    /** The revision the write produced, as the caller observed it right after. */
+    readonly after: string;
+    readonly source: 'agent';
+    /** The Pi conversation that wrote it, carried on the change event. */
+    readonly conversationId?: string | undefined;
 }
 /** Runs one piece of work at a time, in order. A failed piece does not stop the ones behind it. */
 export interface WorkspaceQueue {
@@ -27,25 +43,62 @@ export interface WorkspaceResourceProvider extends ResourceProvider {
     };
     /** The workspace's mutation queue. Native tool calls that must not interleave with a conditional write run through it. */
     readonly queue: WorkspaceQueue;
+    /**
+     * Record a write the agent already made through the native tools (Pi `write`/`edit`, called by the file guard right after the
+     * tool succeeded): the file's history gains the written revision (source `agent`, and the replaced one when `before` carries its
+     * bytes) and the change feed an `agent` event. It writes history rows only: no publish, no receipt, no operation or intent rows,
+     * so agent writes are observed, not published. It does not enter `queue` (the guard already runs inside it), so it is safe to call from queued work.
+     * When the bytes there no longer have the `after` revision (a shell wrote in between), only the change event is recorded.
+     */
+    readonly record: (write: AgentWrite, access: ResourceAccess) => Promise<void>;
+    /**
+     * The change feed: every write this provider makes or records, every change `poll` finds and, while someone is listening, every
+     * change the file system's `watch` reports (the SQLite file system reports its own connection's writes at once). Ordered by
+     * `seq` and replayable from `since` within a bounded window; a gap yields a `resnapshot` event. The iterator ends when
+     * `request.signal` or `access.signal` aborts, or the provider closes. Events are invalidation hints: read the bytes again.
+     *
+     * After the last listener leaves, the watcher stays open for `watchLingerMs` and then closes. Changes made while no watcher was
+     * open are unknown, so the first listener afterwards makes the feed append a `resnapshot`: a client that reconnects after a
+     * longer absence reloads everything once, and one that stays connected is never affected.
+     */
+    readonly changes: (request: ChangeFeedRequest, access: ResourceAccess) => AsyncIterable<WorkspaceChangeEvent>;
+    /** The seq of the newest change event (the cursor of "now" for `changes({ since })`). */
+    readonly changeHead: () => number;
+    /** Names this provider's lifetime; a cursor from another one (`ChangeFeedRequest.incarnation`) is answered with a `resnapshot`. */
+    readonly changeIncarnation: string;
+    /** Ends every change stream, closes the file watcher and drops the change listeners. Idempotent; the provider still reads and publishes. */
+    readonly close: () => void;
+    /** Aborts when the provider closes, so a change stream nobody is reading still ends and releases its lease. */
+    readonly lifetime: AbortSignal;
     /** Revisions still retained for a file, newest first. */
     readonly history: (path: string) => string[];
     /** The same revisions with the time each was saved (milliseconds since the epoch; 0 when unknown), newest first. */
     readonly saves: (path: string) => {
         readonly revision: string;
         readonly savedAt: number;
+        readonly source: HistorySource;
     }[];
     /** Read the file as it is now and retain that revision in its history (what `present` shows). Serialised with writes. */
     readonly keep: (path: string, access: ResourceAccess) => Promise<ReadResult>;
     /** Provider writes and polled detections. The listener must not throw. */
     readonly onChange: (listener: (change: WorkspaceChange) => void) => () => void;
-    /** Hash each path now and report those that differ from the last revision this provider wrote or polled. Finds shell writes. */
-    readonly poll: (paths: readonly string[], signal?: AbortSignal) => Promise<WorkspaceChange[]>;
+    /**
+     * Hash each path now and report those that differ from the last revision this provider wrote or polled. Finds shell writes.
+     * Without `paths`, every file of the workspace (except `.git` and `node_modules`): the first such call takes the baseline and
+     * reports nothing; later calls also report new and removed files. A host whose file system cannot `watch` calls it at the end of
+     * each agent turn (after `bash`), so the change feed still sees shell writes.
+     */
+    readonly poll: (paths?: readonly string[], signal?: AbortSignal) => Promise<WorkspaceChange[]>;
 }
 export interface WorkspaceProviderOptions {
     readonly identity: WorkspaceKey;
     readonly fs: FileSystem;
     readonly journal: WorkspaceJournal;
     readonly catalog?: WorkspaceCatalogOptions;
+    /** How many change events the feed retains for replay (default 1024). An older cursor gets a `resnapshot`. */
+    readonly changeBuffer?: number;
+    /** How long the watcher stays open after the last change-feed listener leaves, in milliseconds (default 30 000). */
+    readonly watchLingerMs?: number;
 }
 /** The Git blob id of `bytes` (`sha1("blob <length>\0" + bytes)`), computed without Git. */
 export declare function blobRevision(bytes: Uint8Array): Promise<string>;

package/dist/workspace.js

@@ -71,14 +71,38 @@ export function createWorkspaceProvider(options) {
         principal: access.principalId, initiator: access.initiatorId, operation: operationId,
     });
     const ownEvidence = (evidence) => evidence.startsWith(`${key.incarnation}:`);
-    function emit(change) {
-        known.set(change.path, change.revision);
+    // ---- The change feed: a bounded, seq-ordered buffer of invalidation hints ----------------------------------------------------
+    const bufferLimit = options.changeBuffer ?? 1024;
+    if (!Number.isSafeInteger(bufferLimit) || bufferLimit < 1)
+        throw new RangeError('The change buffer must be a positive integer');
+    const lingerMs = options.watchLingerMs ?? 30_000;
+    // Sequence numbers start from the clock (microseconds), so a cursor from an earlier provider lifetime is older than this one's
+    // first event and reads as a gap, never as a position in this lifetime.
+    const firstSeq = Date.now() * 1000;
+    let head = firstSeq;
+    // Names this provider lifetime. A cursor from another lifetime is refused by this, not only by the clock: the clock may go back.
+    const incarnationOfFeed = randomUUID();
+    const lifetime = new AbortController();
+    const buffer = [];
+    const waiting = new Set();
+    function append(event) {
+        head += 1;
+        buffer.push(Object.freeze({ ...event, seq: head, at: Date.now() }));
+        if (buffer.length > bufferLimit)
+            buffer.shift();
+        for (const wake of [...waiting])
+            wake();
+    }
+    function emit(change, extra = {}) {
+        if (!extra.directory)
+            known.set(change.path, change.revision);
         for (const listener of [...listeners]) {
             try {
                 listener(change);
             }
             catch { /* a listener failure cannot undo a write */ }
         }
+        append({ kind: 'change', ...change, ...extra });
     }
     const dirname = (path) => path.slice(0, path.lastIndexOf('/')) || '/';
     const inside = (base, path) => path === base || path.startsWith(base === '/' ? '/' : `${base}/`);
@@ -182,7 +206,7 @@ export function createWorkspaceProvider(options) {
         const result = await read({ target: { resource: { providerId, path }, view: { kind: 'published' } }, revision: { kind: 'latest' } }, access);
         if (result.kind === 'available') {
             const path = result.snapshot.ref.resource.path;
-            journal.remember(historyScope, path, { revision: result.snapshot.ref.revision, bytes: result.snapshot.bytes, mediaType: result.snapshot.mediaType, savedAt: await savedAtOf(path) });
+            journal.remember(historyScope, path, { revision: result.snapshot.ref.revision, bytes: result.snapshot.bytes, mediaType: result.snapshot.mediaType, savedAt: await savedAtOf(path), source: 'observed' });
         }
         return result;
     });
@@ -276,11 +300,11 @@ export function createWorkspaceProvider(options) {
                 }
                 const evidence = `${key.incarnation}:${randomUUID()}`;
                 const versions = plans.flatMap(({ change, path, before, after, unchanged, beforeSavedAt }) => {
-                    const kept = (revision, bytes, mediaType, savedAt) => ({ scope: historyScope, path, version: { revision, bytes, mediaType, savedAt } });
+                    const kept = (revision, bytes, mediaType, savedAt, source) => ({ scope: historyScope, path, version: { revision, bytes, mediaType, savedAt, source } });
                     return unchanged ? [] : [
                         ...(change.kind === 'replace' && before?.kind === 'file'
-                            ? [kept(before.revision, before.bytes, journal.version(historyScope, path, before.revision)?.mediaType ?? mediaTypeOf(path), beforeSavedAt)] : []),
-                        kept(after, change.bytes, change.mediaType, Date.now()),
+                            ? [kept(before.revision, before.bytes, journal.version(historyScope, path, before.revision)?.mediaType ?? mediaTypeOf(path), beforeSavedAt, 'observed')] : []),
+                        kept(after, change.bytes, change.mediaType, Date.now(), 'publish'),
                     ];
                 });
                 const record = {
@@ -343,7 +367,7 @@ export function createWorkspaceProvider(options) {
                 }
                 for (const { path, after, unchanged } of plans)
                     if (!unchanged)
-                        emit({ path, revision: after, source: 'provider' });
+                        emit({ path, revision: after, source: 'publish' });
                 return { kind: 'committed', receipt: receipt(request.operationId, access, record) };
             }
             catch (error) {
@@ -369,20 +393,63 @@ export function createWorkspaceProvider(options) {
             ? { kind: 'unknown', operationId: id, reason: 'The operation began and has no recorded outcome' }
             : { kind: 'not-found' };
     };
+    /** Every file of the workspace, relative to the root (not `.git`, `node_modules` or the provider's temporary files). */
+    async function everyFile(signal) {
+        const found = [];
+        let scanned = 0;
+        const walk = async (directory) => {
+            const listing = await fs.listDir(directory ? absolute(directory) : root, fsContext(signal));
+            if (!listing.ok)
+                return true;
+            for (const entry of listing.value) {
+                if (++scanned > 100_000)
+                    return false;
+                const path = directory ? `${directory}/${entry.name}` : entry.name;
+                if (entry.kind === 'directory') {
+                    if (entry.name !== '.git' && entry.name !== 'node_modules' && !await walk(path))
+                        return false;
+                }
+                else if (entry.kind === 'file' && !isTemporary(path))
+                    found.push(path);
+            }
+            return true;
+        };
+        return await walk('') ? found : undefined;
+    }
+    let baselined = false;
     const poll = async (paths, signal) => {
         const changed = [];
         await sweep();
-        for (const input of paths) {
+        let inputs;
+        let report = (path) => known.has(path);
+        if (paths === undefined) {
+            const files = await everyFile(signal);
+            // Too many files to hash on each turn: say so to every listener instead of reporting a partial picture.
+            if (files === undefined) {
+                append({ kind: 'resnapshot' });
+                return changed;
+            }
+            const present = new Set(files);
+            const removed = [...known].filter(([path, revision]) => revision !== null && !present.has(path)).map(([path]) => path);
+            inputs = [...files, ...removed];
+            if (baselined)
+                report = () => true;
+            baselined = true;
+        }
+        else
+            inputs = paths;
+        for (const input of inputs) {
             const path = locator({ resource: { providerId, path: input }, view: { kind: 'published' } }).resource.path;
             const now = await observe(path, signal);
             if (now.kind === 'error' || now.kind === 'outside' || isTemporary(path))
                 continue;
             const revision = now.kind === 'file' ? now.revision : null;
-            const first = !known.has(path);
-            if (!first && known.get(path) === revision)
+            if (known.has(path) && known.get(path) === revision)
+                continue;
+            if (!known.has(path) && revision === null && paths === undefined)
                 continue;
             const change = { path, revision, source: 'poll' };
-            if (first)
+            if (!report(path))
                 known.set(path, revision);
             else {
                 emit(change);
@@ -391,10 +458,181 @@ export function createWorkspaceProvider(options) {
         }
         return changed;
     };
+    const record = async (write, context) => {
+        const access = accessSnapshot(context);
+        if (write.source !== 'agent')
+            throw new TypeError('Only agent writes are recorded');
+        const path = locator({ resource: { providerId, path: write.path }, view: { kind: 'published' } }).resource.path;
+        const after = identifier(write.after);
+        const conversationId = write.conversationId === undefined ? undefined : identifier(write.conversationId);
+        // Known before the await: a watcher event for this same write, handled meanwhile, then finds nothing new and emits nothing twice.
+        if (!isTemporary(path))
+            known.set(path, after);
+        // Deliberately not `queue.run`: the file guard calls this from inside the queue, and the queue runs one piece at a time.
+        const now = await observe(path, access.signal);
+        if (now.kind === 'outside' || now.kind === 'error')
+            return;
+        if (now.kind === 'file' && now.revision === after) {
+            const mediaType = journal.version(historyScope, path, after)?.mediaType ?? mediaTypeOf(path);
+            const before = write.before ?? undefined;
+            // The replaced bytes are kept only when they really are that revision.
+            if (before && before.revision !== after && before.bytes instanceof Uint8Array && await blobRevision(before.bytes) === identifier(before.revision)) {
+                journal.remember(historyScope, path, { revision: before.revision, bytes: Uint8Array.from(before.bytes), mediaType: journal.version(historyScope, path, before.revision)?.mediaType ?? mediaType, savedAt: 0, source: 'observed' });
+            }
+            journal.remember(historyScope, path, { revision: after, bytes: now.bytes, mediaType, savedAt: Date.now(), source: 'agent' });
+        }
+        emit({ path, revision: now.kind === 'file' ? now.revision : null, source: 'agent' }, conversationId === undefined ? {} : { conversationId });
+    };
+    // ---- The watcher: open while someone listens to the feed (and `lingerMs` after), when the file system can watch ----------------
+    let listening = 0;
+    let watcher;
+    let watchUnsupported = false, watchedBefore = false;
+    let linger;
+    let watchWork = Promise.resolve();
+    const relativeTo = (absolutePath, base) => {
+        base = base.replace(/\/+$/, '') || '/';
+        if (absolutePath === base)
+            return '';
+        const prefix = base === '/' ? '/' : `${base}/`;
+        return absolutePath.startsWith(prefix) ? absolutePath.slice(prefix.length) : undefined;
+    };
+    async function watched(input) {
+        // The watcher may name the root as given or as resolved (a symbolic link on the way to the workspace).
+        const real = await realRoot();
+        const path = relativeTo(input, root) ?? (real === undefined ? undefined : relativeTo(input, real));
+        if (path === undefined || isTemporary(path) || path.split('/').some(name => name === '.git' || name === 'node_modules'))
+            return;
+        if (path === '') {
+            emit({ path, revision: null, source: 'watch' }, { directory: true });
+            return;
+        }
+        const info = await fs.fileInfo(absolute(path), fsContext());
+        if (info.ok && info.value.kind === 'directory') {
+            emit({ path, revision: null, source: 'watch' }, { directory: true });
+            return;
+        }
+        const now = await observe(path);
+        if (now.kind === 'error' || now.kind === 'outside')
+            return;
+        const revision = now.kind === 'file' ? now.revision : null;
+        if (known.has(path) && known.get(path) === revision)
+            return;
+        emit({ path, revision, source: 'watch' });
+    }
+    function onWatch(change) {
+        if ('paths' in change) {
+            const paths = [...change.paths];
+            watchWork = watchWork.then(async () => { for (const path of paths)
+                await watched(path).catch(() => undefined); });
+            return;
+        }
+        // Overflow or a failed watcher: what changed is unknown, so every listener reloads. A failed watcher is not reopened (it would
+        // fail again, for example on a tree past the environment's limit); the host's `poll()` at turn end remains.
+        if ('error' in change) {
+            watcher = undefined;
+            watchUnsupported = true;
+        }
+        append({ kind: 'resnapshot' });
+    }
+    function startWatching() {
+        if (lifetime.signal.aborted)
+            return;
+        if (linger !== undefined) {
+            clearTimeout(linger);
+            linger = undefined;
+        }
+        if (watcher || watchUnsupported)
+            return;
+        // Changes made while nobody watched were not seen: a listener resuming from before that reloads.
+        if (watchedBefore)
+            append({ kind: 'resnapshot' });
+        watchedBefore = true;
+        watcher = fs.watch([{ path: root, recursive: true, exclude: { names: ['.git', 'node_modules'] } }], onWatch, fsContext()).then(result => {
+            if (result.ok)
+                return result.value;
+            watchUnsupported = true;
+            return undefined;
+        }, () => { watchUnsupported = true; return undefined; });
+    }
+    function stopWatching() {
+        const current = watcher;
+        watcher = undefined;
+        void current?.then(value => value?.close(fsContext()));
+    }
+    async function* changes(request, context) {
+        const access = accessSnapshot(context);
+        identifier(access.scopeId);
+        const since = request.since;
+        if (since !== undefined && (!Number.isSafeInteger(since) || since < 0))
+            throw new TypeError('Invalid change cursor');
+        if (lifetime.signal.aborted)
+            return;
+        const signals = [request.signal, access.signal, lifetime.signal].filter((value) => value !== undefined);
+        const signal = signals.length ? AbortSignal.any(signals) : new AbortController().signal;
+        listening += 1;
+        startWatching();
+        try {
+            let cursor = head;
+            if (since !== undefined) {
+                const oldest = buffer[0]?.seq ?? head + 1;
+                const foreign = request.incarnation !== undefined && request.incarnation !== incarnationOfFeed;
+                if (foreign || since > head || since < firstSeq || since < oldest - 1)
+                    yield { kind: 'resnapshot', seq: head, at: Date.now() };
+                else
+                    cursor = since;
+            }
+            while (!signal.aborted) {
+                const oldest = buffer[0];
+                // This listener fell behind the retained window: it reloads, then continues with what is retained.
+                if (oldest && oldest.seq > cursor + 1) {
+                    cursor = oldest.seq - 1;
+                    yield { kind: 'resnapshot', seq: cursor, at: Date.now() };
+                    continue;
+                }
+                const next = buffer.find(event => event.seq > cursor);
+                if (next) {
+                    cursor = next.seq;
+                    // The access projection: nothing after revocation, never the provider's temporary files.
+                    if (signal.aborted)
+                        return;
+                    if (next.kind === 'change' && isTemporary(next.path))
+                        continue;
+                    yield next;
+                    continue;
+                }
+                await new Promise(resolve => {
+                    const wake = () => { waiting.delete(wake); signal.removeEventListener('abort', wake); resolve(); };
+                    waiting.add(wake);
+                    signal.addEventListener('abort', wake, { once: true });
+                });
+            }
+        }
+        finally {
+            listening -= 1;
+            if (listening === 0 && watcher && !lifetime.signal.aborted) {
+                linger = setTimeout(() => { linger = undefined; if (listening === 0)
+                    stopWatching(); }, lingerMs);
+                linger.unref?.();
+            }
+        }
+    }
     return {
         providerId, read, queue, keep, identity: Object.freeze(key),
         catalog: createWorkspaceCatalog({ fs, ...(options.catalog ? { config: options.catalog } : {}), saves: path => journal.saves(historyScope, path) }),
-        publication: { publish }, reconciliation: { lookup }, poll,
+        publication: { publish }, reconciliation: { lookup }, poll, record, changes, changeHead: () => head, changeIncarnation: incarnationOfFeed,
+        lifetime: lifetime.signal,
+        close: () => {
+            // Every change stream ends, the watcher closes and the listeners are dropped: nothing of this provider keeps running.
+            lifetime.abort();
+            if (linger !== undefined) {
+                clearTimeout(linger);
+                linger = undefined;
+            }
+            stopWatching();
+            listeners.clear();
+            for (const wake of [...waiting])
+                wake();
+        },
         history: path => journal.revisions(historyScope, locator({ resource: { providerId, path }, view: { kind: 'published' } }).resource.path),
         saves: path => journal.saves(historyScope, locator({ resource: { providerId, path }, view: { kind: 'published' } }).resource.path),
         onChange: listener => { listeners.add(listener); return () => { listeners.delete(listener); }; },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-files",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "MIT",
   "private": false,
   "type": "module",