@ours.network/fleet 2.3.1 → 2.3.3

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
-  "version": "2.3.1",
-  "buildId": "2fbb7f11f70a",
-  "commit": "f7b1dda8a2cb911367ce11617ef38759ba78c5e6",
+  "version": "2.3.3",
+  "buildId": "f813635f30d3",
+  "commit": "b0dbf450ed45e131fb34f64d71a16e8eb960b77f",
   "dirty": false,
-  "builtAt": "2026-10-30T19:03:10.573Z",
+  "builtAt": "2026-11-03T12:22:11.870Z",
   "capabilities": [
     "service.refresh-v1",
     "managed-cli.codex-reasoning-effort-v1",

package/dist/rooms-tasks/task-contributions.d.ts

@@ -0,0 +1,50 @@
+import type { TaskRecord } from './types.js';
+export declare const CONTRIBUTION_PAGE_MAX = 100;
+export declare const CONTRIBUTION_CUTOFF_MAX = 200;
+export interface ContributionItem {
+    /** `p:<task>:<entry>` or `r:<task>:<revision>`: a new review revision is a new item. */
+    id: string;
+    kind: 'progress' | 'review';
+    task_id: string;
+    mission_key?: string;
+    task_title: string;
+    task_state: TaskRecord['state'];
+    at: string;
+    excerpt: string;
+    unread: boolean;
+    entry_id?: string;
+    revision?: number;
+}
+/** What one task had when it was listed; the bulk read acknowledges nothing beyond it. */
+export interface ContributionCutoff {
+    task_id: string;
+    progress: number;
+    progress_last: string | null;
+    review: number;
+}
+/**
+ * One page, newest first. The cursor is a position, not an item: it stays valid when the item it
+ * names is read, filtered out or deleted. `cutoff` lists every task with unread items as listed;
+ * `unavailable` counts task records that could not be read.
+ */
+export declare function listTaskContributions(options?: {
+    before?: string;
+    limit?: number;
+    unread?: boolean;
+}): {
+    items: ContributionItem[];
+    next_cursor: string | null;
+    unread_total: number;
+    cutoff: ContributionCutoff[];
+    unavailable: number;
+};
+export type ContributionReadResult = {
+    task_id: string;
+} & ({
+    status: 'read';
+    read: number;
+} | {
+    status: 'changed' | 'gone' | 'deleting' | 'failed';
+});
+/** Read every task of a captured cutoff up to that cutoff, each under its own lock; one task's outcome never blocks another. */
+export declare function readTaskContributions(cutoff: ContributionCutoff[]): ContributionReadResult[];

package/dist/rooms-tasks/task-contributions.js

@@ -0,0 +1,169 @@
+/**
+ * Progress entries and To review revisions of every task as one newest-first notification list,
+ * with the canonical read state of each task record. Nothing is copied: the task records stay the
+ * only read truth, and the per-task routes and the bulk read below change the same markers.
+ *
+ * The projection is retained in this process. Each request lists the task directory and stats each
+ * record; only a record whose inode, size or time changed is read again (every write replaces the
+ * file atomically). Room history and other services are never consulted.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { acknowledgeTaskContributionsThrough, contributionUnread, getTask, reviewRevision, tasksDir, TaskStateError } from './task-state.js';
+import { TaskReviewError } from './task-review.js';
+const TASK_FILE = /^([0-9a-z]{9}[0-9a-f]{8})\.json$/;
+const EXCERPT_MAX = 200;
+export const CONTRIBUTION_PAGE_MAX = 100;
+export const CONTRIBUTION_CUTOFF_MAX = 200;
+let cache;
+function excerpt(text) {
+    const points = [...text.replace(/\s+/g, ' ').trim()];
+    return points.length > EXCERPT_MAX ? points.slice(0, EXCERPT_MAX - 1).join('') + '…' : points.join('');
+}
+function reviewExcerpt(task) {
+    const line = task.review?.markdown.split('\n').map(text => text.replace(/^\s*(?:#{1,6}\s|>\s?|[-*+]\s|\d+\.\s)*/, '').trim()).find(Boolean);
+    if (line)
+        return excerpt(line);
+    const files = task.review?.artifacts.length ?? 0;
+    return files ? `${files} attached ${files === 1 ? 'file' : 'files'}` : 'The review request was cleared.';
+}
+const time = (at) => { const value = Date.parse(at); return Number.isFinite(value) ? value : 0; };
+function project(task, stamp) {
+    const base = {
+        task_id: task.task_id, ...(task.key ? { mission_key: task.key } : {}), task_title: task.title, task_state: task.state,
+    };
+    const reads = task.contribution_reads, seen = new Set(reads?.progress_read);
+    const items = (task.progress ?? []).map(entry => ({
+        ...base, id: `p:${task.task_id}:${entry.id}`, kind: 'progress', at: entry.at, order: time(entry.at),
+        excerpt: excerpt(entry.text), unread: !!reads && !seen.has(entry.id), entry_id: entry.id,
+    }));
+    const unread = contributionUnread(task);
+    if (task.review) {
+        const revision = reviewRevision(task.review);
+        items.push({ ...base, id: `r:${task.task_id}:${revision}`, kind: 'review', at: task.review.updated_at,
+            order: time(task.review.updated_at), excerpt: reviewExcerpt(task), unread: unread.review, revision });
+    }
+    const progress = task.progress ?? [];
+    return { stamp, items, unread: unread.progress + (unread.review ? 1 : 0),
+        ...(unread.progress || unread.review ? { cutoff: { task_id: task.task_id, progress: progress.length,
+                progress_last: progress.at(-1)?.id ?? null, review: reviewRevision(task.review) } } : {}) };
+}
+/** Bring the retained projection up to date with the task directory; returns the tasks not readable now. */
+function refresh() {
+    const dir = tasksDir();
+    if (cache?.dir !== dir)
+        cache = { dir, tasks: new Map() };
+    const current = cache;
+    let names;
+    // No task directory yet means no tasks; any other failure is an error, never an empty list.
+    try {
+        names = readdirSync(dir);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        names = [];
+    }
+    const present = new Set();
+    let unavailable = 0;
+    for (const name of names) {
+        const id = TASK_FILE.exec(name)?.[1];
+        if (!id)
+            continue;
+        try {
+            // Writes replace the record by rename: a new inode, and a change time in nanoseconds.
+            const stat = statSync(join(dir, name), { bigint: true });
+            const stamp = `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+            present.add(id);
+            if (current.tasks.get(id)?.stamp === stamp)
+                continue;
+            const task = getTask(id);
+            current.index = undefined;
+            // A task pending deletion lists nothing and counts nothing.
+            if (task.deletion?.status === 'pending')
+                current.tasks.set(id, { stamp, items: [], unread: 0 });
+            else
+                current.tasks.set(id, project(task, stamp));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT' || (error instanceof TaskStateError && /not found/.test(error.message)))
+                continue;
+            present.add(id);
+            unavailable++;
+            if (current.tasks.delete(id))
+                current.index = undefined;
+        }
+    }
+    for (const id of current.tasks.keys())
+        if (!present.has(id)) {
+            current.tasks.delete(id);
+            current.index = undefined;
+        }
+    return unavailable;
+}
+function index() {
+    return cache.index ??= [...cache.tasks.values()].flatMap(task => task.items)
+        .sort((a, b) => b.order - a.order || (a.id < b.id ? 1 : a.id > b.id ? -1 : 0));
+}
+function encodeCursor(item) {
+    return Buffer.from(JSON.stringify([item.order, item.id])).toString('base64url');
+}
+function decodeCursor(cursor) {
+    try {
+        const [order, id] = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (typeof order === 'number' && Number.isFinite(order) && typeof id === 'string' && id.length <= 200)
+            return { order, id };
+    }
+    catch { /* invalid below */ }
+    throw new TaskReviewError('invalid_request', 'invalid cursor');
+}
+/**
+ * One page, newest first. The cursor is a position, not an item: it stays valid when the item it
+ * names is read, filtered out or deleted. `cutoff` lists every task with unread items as listed;
+ * `unavailable` counts task records that could not be read.
+ */
+export function listTaskContributions(options = {}) {
+    const limit = options.limit ?? 50;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > CONTRIBUTION_PAGE_MAX)
+        throw new TaskReviewError('invalid_request', `limit must be 1-${CONTRIBUTION_PAGE_MAX}`);
+    const after = options.before === undefined ? undefined : decodeCursor(options.before);
+    const unavailable = refresh();
+    const page = [];
+    let more = false;
+    for (const item of index()) {
+        if (after && (item.order > after.order || (item.order === after.order && item.id >= after.id)))
+            continue;
+        if (options.unread && !item.unread)
+            continue;
+        if (page.length === limit) {
+            more = true;
+            break;
+        }
+        page.push(item);
+    }
+    const tasks = [...cache.tasks.values()];
+    return {
+        items: page.map(({ order: _order, ...item }) => item),
+        next_cursor: more ? encodeCursor(page.at(-1)) : null,
+        unread_total: tasks.reduce((sum, task) => sum + task.unread, 0),
+        cutoff: tasks.flatMap(task => task.cutoff ? [task.cutoff] : []),
+        unavailable,
+    };
+}
+/** Read every task of a captured cutoff up to that cutoff, each under its own lock; one task's outcome never blocks another. */
+export function readTaskContributions(cutoff) {
+    return cutoff.map(({ task_id, progress, progress_last, review }) => {
+        try {
+            const read = acknowledgeTaskContributionsThrough(task_id, { progress, progressLast: progress_last, review });
+            return read === 'changed' ? { task_id, status: 'changed' } : { task_id, status: 'read', read };
+        }
+        catch (error) {
+            if (error instanceof TaskStateError && /pending deletion/.test(error.message))
+                return { task_id, status: 'deleting' };
+            if (error instanceof TaskStateError && /not found/.test(error.message))
+                return { task_id, status: 'gone' };
+            // An unreadable or unwritable record fails alone; tasks already read stay read and are reported.
+            return { task_id, status: 'failed' };
+        }
+    });
+}

package/dist/rooms-tasks/task-state.d.ts

@@ -24,6 +24,18 @@ export declare function acknowledgeTaskReview(id: string, revision: number): {
     progress: number;
     review: boolean;
 };
+/**
+ * Bulk read up to a captured cutoff: the first `progress` entries (Progress is append-only, so an
+ * entry appended after the capture has a higher index) and To review up to exactly `review`, never
+ * a newer revision. Both are written in one task change. Returns how many items that were unread
+ * are read now, or `changed` (nothing written) when the task no longer matches the cutoff, including a
+ * review revision the task never had; refuses a task pending deletion.
+ */
+export declare function acknowledgeTaskContributionsThrough(id: string, cutoff: {
+    progress: number;
+    progressLast: string | null;
+    review: number;
+}): number | 'changed';
 /** Atomic snapshots contain the events, including intermediate states between polls. */
 /** `upgraded`: IDs of events queued by an earlier release without a delivery policy. They are sent push-only under the
  * same event ID (state transitions never count as unread); the queued record itself is not rewritten. A service that

package/dist/rooms-tasks/task-state.js

@@ -179,7 +179,7 @@ function writeTask(record, options = {}) {
             const next = status(record), before = previous ? status(previous) : undefined;
             pending.push({ eventId: `task:${record.task_id}:${randomUUID()}`, taskId: record.task_id,
                 title: `Task ${!previous ? 'created' : 'updated'}: ${taskLabel(record)}`.slice(0, 160),
-                body: `Task ${record.task_id}: ${before ? `${before} → ` : 'created in '}${next}.`,
+                body: taskSentence(record, `${before ? `${before} → ` : 'created in '}${next}.`),
                 target: { kind: 'task', taskId: record.task_id }, delivery: 'push-only' });
         }
         pending.push(...contributionEvents(previous, record));
@@ -196,6 +196,11 @@ function writeTask(record, options = {}) {
 }
 /** Human label for notification titles: the mission key, when issued, precedes the title. */
 const taskLabel = (record) => record.key ? `${record.key} · ${record.title}` : record.title;
+/**
+ * Notification body naming the task by its mission key. The opaque task ID stays in routing and
+ * event fields only; a task without a key relies on its title, which the notification title shows.
+ */
+const taskSentence = (record, text) => record.key ? `Task ${record.key}: ${text}` : text[0].toUpperCase() + text.slice(1);
 /** Packages written before revisions existed count as revision 1; their next change becomes 2. No package is 0. */
 export const reviewRevision = (review) => review ? review.revision ?? 1 : 0;
 const contributionsChanged = (previous, record) => (record.progress ?? []).some(entry => !(previous.progress ?? []).some(old => old.id === entry.id))
@@ -214,7 +219,7 @@ function contributionEvents(previous, record) {
     const revision = reviewRevision(record.review);
     if (revision > reviewRevision(previous.review))
         events.push({ eventId: `task:${id}:review:${revision}`, taskId: id, title: `To review updated: ${taskLabel(record)}`.slice(0, 160),
-            body: `Task ${id}: the review package changed.`, target: { kind: 'task', taskId: id }, delivery: 'push-only' });
+            body: taskSentence(record, 'the review package changed.'), target: { kind: 'task', taskId: id }, delivery: 'push-only' });
     return events;
 }
 /** Item-based Progress unread and revision-based To review unread. An absent read state means nothing is unread. */
@@ -261,6 +266,42 @@ export function acknowledgeTaskReview(id, revision) {
         return contributionUnread(task);
     });
 }
+/**
+ * Bulk read up to a captured cutoff: the first `progress` entries (Progress is append-only, so an
+ * entry appended after the capture has a higher index) and To review up to exactly `review`, never
+ * a newer revision. Both are written in one task change. Returns how many items that were unread
+ * are read now, or `changed` (nothing written) when the task no longer matches the cutoff, including a
+ * review revision the task never had; refuses a task pending deletion.
+ */
+export function acknowledgeTaskContributionsThrough(id, cutoff) {
+    assertCanonicalTaskId(id);
+    return withTaskLock(id, () => {
+        const task = readTask(id);
+        assertNoPendingDeletion(task);
+        const { progress, progressLast, review } = cutoff;
+        // The cutoff names its last entry: a different entry at that position reads nothing.
+        const entries = task.progress ?? [];
+        if (!Number.isSafeInteger(progress) || progress < 0 || progress > entries.length
+            || (progress > 0 ? entries[progress - 1].id : null) !== progressLast
+            || !Number.isSafeInteger(review) || review < 0 || review > reviewRevision(task.review))
+            return 'changed';
+        const reads = task.contribution_reads;
+        if (!reads)
+            return 0;
+        const seen = new Set(reads.progress_read);
+        const added = entries.slice(0, progress).map(entry => entry.id).filter(entryId => !seen.has(entryId));
+        const reviewRead = review > reads.review_revision;
+        if (!added.length && !reviewRead)
+            return 0;
+        task.contribution_reads = {
+            progress_read: [...reads.progress_read, ...added],
+            review_revision: reviewRead ? review : reads.review_revision,
+        };
+        writeTask(task);
+        // An older revision moves the marker but leaves the current package unread: it is not counted.
+        return added.length + (reviewRead && review === reviewRevision(task.review) ? 1 : 0);
+    });
+}
 const retiredNotificationsDir = () => join(tasksDir(), '.notification-retired');
 function typedTaskNotification(value, id) {
     if (!value || typeof value !== 'object' || Object.keys(value).some(key => !['eventId', 'title', 'body', 'target', 'taskId', 'delivery'].includes(key)))

package/dist/web/fleet-config-service.d.ts

@@ -50,6 +50,14 @@ export declare class FleetConfigService {
     private validationInputs;
     /** Cached during canonical reads; observer filtering must never parse YAML. */
     resourceValidationInputs(): readonly string[];
+    /**
+     * Record the manifest's external file references before a projection that loads
+     * the configuration, so a reference anywhere (including a task workspace) fences
+     * that capture even before the configuration itself has been read. A manifest that
+     * cannot be read keeps the last recorded inputs; the projection reports its error.
+     */
+    observeValidationInputs(): void;
+    private recordValidationInputs;
     constructor(options?: FleetConfigServiceOptions);
     read(includeDefinitions?: boolean): ConfigReadResult;
     preview(baseRevision: string, input: unknown): Promise<ConfigPreviewResult>;

package/dist/web/fleet-config-service.js

@@ -21,6 +21,28 @@ export class FleetConfigService {
     validationInputs = [];
     /** Cached during canonical reads; observer filtering must never parse YAML. */
     resourceValidationInputs() { return this.validationInputs; }
+    /**
+     * Record the manifest's external file references before a projection that loads
+     * the configuration, so a reference anywhere (including a task workspace) fences
+     * that capture even before the configuration itself has been read. A manifest that
+     * cannot be read keeps the last recorded inputs; the projection reports its error.
+     */
+    observeValidationInputs() {
+        try {
+            this.recordValidationInputs(parse(trustedFile(this.path), { prettyErrors: false }));
+        }
+        catch { /* unchanged */ }
+    }
+    recordValidationInputs(parsed) {
+        const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+        const manifest = record(parsed);
+        const vars = record(manifest.vars);
+        const expand = (value) => value.replace(/\$\{(\w+)\}/g, (match, key) => key in vars ? String(vars[key]) : match);
+        const invite = record(record(manifest.rooms).owner).public_invite_file;
+        const prompts = Object.values(record(manifest.watchdogs)).map(value => record(value).prompt_file);
+        this.validationInputs = [...(typeof invite === 'string' ? [expand(expand(invite))] : []),
+            ...prompts.filter((value) => typeof value === 'string').map(expand)].map(value => resolve(value));
+    }
     constructor(options = {}) {
         this.path = options.configPath ?? defaultConfigPath();
         this.preflight = options.preflight ?? (async () => emptyReport());
@@ -30,16 +52,9 @@ export class FleetConfigService {
         const sources = readSources(this.path);
         let raw;
         try {
-            const manifest = parse(sources.documents.get(basename(sources.manifest)), { prettyErrors: false });
-            const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
-            const vars = record(manifest.vars);
-            const expand = (value) => value.replace(/\$\{(\w+)\}/g, (match, key) => key in vars ? String(vars[key]) : match);
-            const invite = record(record(manifest.rooms).owner).public_invite_file;
-            const prompts = Object.values(record(manifest.watchdogs)).map(value => record(value).prompt_file);
             // Record even invalid/missing references before validation, so repairing an
             // already observed dependency can never retain a certified stale capture.
-            this.validationInputs = [...(typeof invite === 'string' ? [expand(expand(invite))] : []),
-                ...prompts.filter((value) => typeof value === 'string').map(expand)].map(value => resolve(value));
+            this.recordValidationInputs(parse(sources.documents.get(basename(sources.manifest)), { prettyErrors: false }));
             loadConfig(this.path, { yamlMode: 'strict' });
             raw = modelFrom(sources, includeDefinitions);
         }

package/dist/web/resource-views.d.ts

@@ -135,6 +135,8 @@ export declare class FleetResourceViews {
     private coverage;
     /** Certify each view's last projected source; never a position its capture did not read. */
     private cover;
+    /** Whether `path` is, contains or lies within the manifest, its split definitions or another configuration input. */
+    private configurationDependency;
     private affects;
     private schedule;
     private refresh;

package/dist/web/resource-views.js

@@ -364,22 +364,25 @@ export class FleetResourceViews {
             view.qualifiedAt = now;
         } });
     }
+    /** Whether `path` is, contains or lies within the manifest, its split definitions or another configuration input. */
+    configurationDependency(path) {
+        const manifest = resolve(this.scope.configPath ?? defaultConfigPath());
+        const root = resolve(splitRootFor(manifest)), changed = resolve(path);
+        const within = (candidate, parent) => {
+            const local = relative(parent, candidate);
+            return local === '' || (local !== '..' && !local.startsWith('..' + sep));
+        };
+        // Configuration and provenance read the manifest and split definitions;
+        // loadConfig also rejects legacy YAML files in the global fleet.d root.
+        // Ancestor replacement/unknown directory wakes remain conservative.
+        const legacy = resolve(fleetDDir());
+        return within(changed, root) || within(root, changed) || within(manifest, changed)
+            || within(changed, legacy) || within(legacy, changed)
+            || this.configurationInputs().some(input => within(resolve(input), changed));
+    }
     affects(descriptor, path, structural = false) {
-        if (descriptor.resource === 'configuration') {
-            const manifest = resolve(this.scope.configPath ?? defaultConfigPath());
-            const root = resolve(splitRootFor(manifest)), changed = resolve(path);
-            const within = (candidate, parent) => {
-                const local = relative(parent, candidate);
-                return local === '' || (local !== '..' && !local.startsWith('..' + sep));
-            };
-            // Configuration and provenance read the manifest and split definitions;
-            // loadConfig also rejects legacy YAML files in the global fleet.d root.
-            // Ancestor replacement/unknown directory wakes remain conservative.
-            const legacy = resolve(fleetDDir());
-            return within(changed, root) || within(root, changed) || within(manifest, changed)
-                || within(changed, legacy) || within(legacy, changed)
-                || this.configurationInputs().some(input => within(resolve(input), changed));
-        }
+        if (descriptor.resource === 'configuration')
+            return this.configurationDependency(path);
         // An explicitly selected manifest may use any pathname, including one
         // otherwise reserved for an independent task receipt.
         if (this.scope.configPath && resolve(path) === resolve(this.scope.configPath))
@@ -394,6 +397,14 @@ export class FleetResourceViews {
         if (roleProjection && !inRoleRoot && (/^(?:history\.jsonl|models_cache\.json|(?:thread_history|state|logs|queue|goals)_\d+\.sqlite(?:-wal|-shm|-journal)?)$/.test(relative(resolve(homedir(), '.codex'), path))
             || /^(?:workspace-devices\.db(?:-wal|-shm|-journal)?|audit[/\\]audit\.jsonl)$/.test(relative(resolve(stateRoot(), 'web'), path))))
             return false;
+        // Task and room workspaces hold their agents' own execution artifacts (checkouts,
+        // builds, test logs); role projections read nothing there except declared role
+        // roots and configuration (manifest, split definitions), which stay fenced. Working
+        // agents write there continuously, which otherwise fences every directory capture
+        // until it resyncs. The workspace directories themselves and their ancestors remain full wakes.
+        if (roleProjection && !inRoleRoot && /^(?:tasks|rooms)[/\\][^/\\]+[/\\]/.test(relative(resolve(stateRoot(), 'workspaces'), path))
+            && !this.configurationDependency(path))
+            return false;
         // Preview selection reads role config/state and conversation ledgers, never
         // task layout run/operation/brief receipts. A worker may commit several of
         // these while that independent canonical preview read is in flight.

package/dist/web/server.js

@@ -25,6 +25,7 @@ import { FleetEventBus } from './events.js';
 import { ROLE_NAME_RE } from '../config.js';
 import { TaskListError } from '../rooms-tasks/task-lists.js';
 import { acknowledgeTaskProgress, acknowledgeTaskReview, contributionUnread, resolveTaskRef, TaskStateError } from '../rooms-tasks/task-state.js';
+import { CONTRIBUTION_CUTOFF_MAX, CONTRIBUTION_PAGE_MAX, listTaskContributions, readTaskContributions } from '../rooms-tasks/task-contributions.js';
 import { MissionKeyError } from '../rooms-tasks/mission-keys.js';
 import { appendTaskProgress, getTaskReview, taskProgressSnapshot, publicProgressEntry, publicReview, readTaskReviewArtifact, setTaskReviewMarkdown, taskContributionSummary, TaskReviewError, } from '../rooms-tasks/task-review.js';
 import { isProvider } from '../subscriptions/store.js';
@@ -424,6 +425,9 @@ export async function buildWebServer(services, boundary, options = {}) {
     const project = async (descriptor, signal, owner = '') => {
         signal.throwIfAborted();
         services.invalidateResourceCaches?.();
+        // Role projections load the configuration: fence this capture on its external inputs too.
+        if (['directory', 'roles', 'previews'].includes(descriptor.resource))
+            services.configuration?.observeValidationInputs();
         switch (descriptor.resource) {
             case 'task-layout':
                 try {
@@ -683,6 +687,39 @@ export async function buildWebServer(services, boundary, options = {}) {
             reply.code(201);
         return { entry: publicProgressEntry(result.entry), replayed: result.replayed };
     });
+    /**
+     * Progress and To review of every task, newest first, for the notification list. The first page
+     * (no `before`) also carries the cutoff a bulk read may acknowledge up to: each task with unread
+     * items as it was read, one task at a time (per task, not one atomic instant across tasks).
+     */
+    app.get('/api/v1/contributions', async (request) => {
+        auth.authenticate(request);
+        const query = request.query;
+        if (query.unread !== undefined && !['true', 'false'].includes(query.unread))
+            throw new FleetError('invalid_request', 'unread must be true or false');
+        if (query.limit !== undefined && !/^\d{1,3}$/.test(query.limit))
+            throw new FleetError('invalid_request', `limit must be 1-${CONTRIBUTION_PAGE_MAX}`);
+        const page = await reviewApi(() => listTaskContributions({
+            ...(query.before !== undefined ? { before: query.before } : {}),
+            ...(query.limit !== undefined ? { limit: Number(query.limit) } : {}),
+            unread: query.unread === 'true',
+        }));
+        const { cutoff, ...rest } = page;
+        return query.before === undefined ? page : rest;
+    });
+    /** Bulk read up to a captured cutoff, at most `CONTRIBUTION_CUTOFF_MAX` tasks per request, with a result per task. */
+    app.post('/api/v1/contributions/read', async (request) => {
+        auth.authenticate(request, true);
+        const cutoff = request.body?.cutoff;
+        const valid = (item) => !!item && typeof item === 'object' && Object.keys(item).length === 4
+            && typeof item.task_id === 'string' && /^[0-9a-z]{9}[0-9a-f]{8}$/.test(item.task_id) && Number.isSafeInteger(item.progress) && item.progress >= 0
+            && (item.progress_last === null || (typeof item.progress_last === 'string' && item.progress_last.length <= 64))
+            && Number.isSafeInteger(item.review) && item.review >= 0;
+        if (!Array.isArray(cutoff) || cutoff.length > CONTRIBUTION_CUTOFF_MAX || !cutoff.every(valid)
+            || new Set(cutoff.map(item => item.task_id)).size !== cutoff.length)
+            throw new FleetError('invalid_request', `cutoff must list at most ${CONTRIBUTION_CUTOFF_MAX} distinct tasks as captured`);
+        return { results: await reviewApi(() => readTaskContributions(cutoff)) };
+    });
     /** Acknowledge Progress entries the browser actually showed; returns the task's remaining unread. */
     app.post('/api/v1/tasks/:id/progress/read', async (request) => {
         auth.authenticate(request, true);

package/docs/task-progress-review.md

@@ -155,6 +155,8 @@ workspace-device bearer. `GET /api/v1/meta` reports API minor version 1.
 | `GET /tasks/:id/review` | `{review: {revision, markdown, updated_at, updated_by, artifacts: [{id, name, mime, size, sha256, added_at, added_by}]}}` or `{review: null}`. |
 | `PUT /tasks/:id/review` | `{markdown, expectedMarkdown}`; 409 when the Markdown changed meanwhile. |
 | `GET /tasks/:id/review/artifacts/:artifactId` | The retained bytes as `application/octet-stream` attachment with `Content-Security-Policy: default-src 'none'; sandbox`, `nosniff` and `no-store`. Another task's artifact ID is 404. |
+| `GET /contributions?limit=1-100&before=&unread=true` | Every task's Progress entries and current To review revision for the notification list, newest first: `{items: [{id, kind, task_id, mission_key?, task_title, task_state, at, excerpt, unread, entry_id? \| revision?}], next_cursor, unread_total, unavailable}`. The cursor is a position, valid after its item is read or deleted. Tasks pending deletion are left out; `unavailable` counts unreadable task records. The first page also has `cutoff: [{task_id, progress, progress_last, review}]` for every task with unread items, each captured from that task's own read (per task, not one instant across tasks). |
+| `POST /contributions/read` | `{cutoff}` with at most 200 distinct tasks from a first page: reads each task's first `progress` entries and review revision `review`, never later ones, one task change each. `{results: [{task_id, status}]}` in request order, `status` `read` (with `read`: items that were unread and are read now), `changed` (the task no longer matches its cutoff; nothing written), `gone`, `deleting` or `failed`. |
 
 The HTTP API has no upload route: the browser never submits a file path.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet",
-  "version": "2.3.1",
+  "version": "2.3.3",
   "description": "Harness-agnostic fleet of persistent, identity-bound AI agents. Declarative fleet.yaml, managed native/ACP sessions, supervision, and ours.network messaging.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",