@ours.network/fleet 2.1.1 → 2.2.0

package/dist/notifications/mission-ownership.js

@@ -0,0 +1,148 @@
+import { mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { replaceFileAtomically } from '../atomic-file.js';
+import { stateRoot } from '../paths.js';
+import { canonicalCid, pendingMissionCleanups, settleMissionCleanup, unavailableMissionCleanups, validRoomCid } from '../rooms-tasks/notification-manifest.js';
+import { advanceNotificationRevision, notificationRoomCids, recordNotificationRooms } from '../rooms-tasks/task-state.js';
+import { producerConfig } from './outbox.js';
+/** The service predates mission ownership: it has no such route. Work is retained, never reported as done. */
+export class MissionOwnershipUnsupported extends Error {
+}
+export class MissionOwnershipUnavailable extends Error {
+}
+export async function missionRequest(config, path, body, request = fetch) {
+    let response;
+    try {
+        response = await request(config.origin + path, {
+            method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10_000),
+            headers: { ...(config.gatewayCredential
+                    ? { 'X-Ours-Api-Token': config.gatewayCredential, 'X-Ours-Notifications-Producer': config.token }
+                    : { Authorization: `Bearer ${config.token}` }), 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    catch {
+        throw new MissionOwnershipUnavailable('notification service unreachable');
+    }
+    const data = await response.json().catch(() => undefined);
+    if (response.status === 404)
+        throw new MissionOwnershipUnsupported('notification service does not support mission ownership');
+    return { status: response.status, data };
+}
+/**
+ * Register the task's current manifest. Only a 2xx response whose `contactIds` include every requested room proves
+ * coverage. A 409 (mission deleted, stale or conflicting revision) proves nothing about these rooms: the local revision
+ * is moved past the refused one, so a later retry registers the full union under a newer revision, and this attempt fails.
+ */
+async function registerMission(config, taskId, manifest, request) {
+    const { status, data } = await missionRequest(config, '/api/v1/missions/associate', { taskId, revision: manifest.revision, contactIds: manifest.room_cids }, request);
+    if (status >= 200 && status < 300) {
+        const registered = Array.isArray(data?.contactIds) ? new Set(data.contactIds.filter(validRoomCid).map(canonicalCid)) : undefined;
+        if (registered && manifest.room_cids.every(cid => registered.has(cid)))
+            return;
+        throw new MissionOwnershipUnavailable('notification service did not confirm every mission room');
+    }
+    if (status === 409)
+        advanceNotificationRevision(taskId, manifest.revision);
+    throw new MissionOwnershipUnavailable(`notification service refused room registration (HTTP ${status})`);
+}
+/**
+ * Register a room as this task's before the Owner can join it: with own-room messages off, the service must know
+ * the room before the room can message the Owner. Unreachable service or unconfirmed coverage → throws, so room
+ * activation waits and retries. No producer configured → nothing to gate. An older service without the route →
+ * admitted with a warning (it cannot suppress own-room messages either).
+ */
+export async function associateRoomNotifications(taskId, roomCid, options = {}) {
+    const manifest = recordNotificationRooms(taskId, [roomCid]);
+    const config = 'config' in options ? options.config : producerConfig();
+    if (!config)
+        return;
+    try {
+        await registerMission(config, taskId, manifest, options.request);
+    }
+    catch (error) {
+        if (error instanceof MissionOwnershipUnsupported) {
+            options.warn?.('Notification service does not support mission rooms; own-room message preferences are unavailable');
+            return;
+        }
+        if (error instanceof MissionOwnershipUnavailable)
+            throw new Error('Waiting for notification service to register the mission room');
+        throw error;
+    }
+}
+/** Retire every queued deleted task's notifications; an intent is removed only after the service acknowledged it. */
+export async function drainMissionCleanup(config, warn, request = fetch) {
+    let pending = false;
+    for (const intent of pendingMissionCleanups().slice(0, 32)) {
+        try {
+            const { status } = await missionRequest(config, '/api/v1/missions/delete', { taskId: intent.taskId, contactIds: intent.contactIds }, request);
+            if (status >= 200 && status < 300) {
+                if (!settleMissionCleanup(intent))
+                    pending = true;
+                continue;
+            }
+            warn(`Mission notification cleanup pending (HTTP ${status}); intent retained`);
+        }
+        catch (error) {
+            warn(error instanceof MissionOwnershipUnsupported
+                ? 'Notification service does not support mission cleanup; cleanup pending'
+                : 'Mission notification cleanup pending; intent retained');
+        }
+        return true;
+    }
+    // An unreadable intent stays pending (and its file retained): overall cleanup is never reported done around it.
+    const unavailable = unavailableMissionCleanups();
+    if (unavailable.length)
+        warn(`Mission notification cleanup unavailable for ${unavailable.length} unreadable intent(s); files retained`);
+    return pending || unavailable.length > 0 || pendingMissionCleanups().length > 32;
+}
+const bootstrapFile = () => join(stateRoot(), 'notifications', 'mission-bootstrap.json');
+/** Only a missing file starts at 0. Unreadable, corrupt or out-of-range state is refused and its bytes are kept. */
+function nextGeneration() {
+    let text;
+    try {
+        text = readFileSync(bootstrapFile(), 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw new MissionOwnershipUnavailable('mission bootstrap state unreadable');
+    }
+    let generation = 0;
+    if (text !== undefined) {
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            throw new MissionOwnershipUnavailable('mission bootstrap state corrupt; file retained');
+        }
+        const stored = value && typeof value === 'object' && !Array.isArray(value) ? value.generation : undefined;
+        if (typeof stored !== 'number' || !Number.isSafeInteger(stored) || stored < 0)
+            throw new MissionOwnershipUnavailable('mission bootstrap state invalid; file retained');
+        generation = stored;
+    }
+    if (!Number.isSafeInteger(generation + 1))
+        throw new MissionOwnershipUnavailable('mission bootstrap generation exhausted');
+    mkdirSync(dirname(bootstrapFile()), { recursive: true, mode: 0o700 });
+    replaceFileAtomically(bootstrapFile(), JSON.stringify({ generation: generation + 1 }) + '\n', 0o600);
+    return generation + 1;
+}
+/**
+ * Register every existing task's rooms under one numbered run, then mark the run complete. Until a run completes
+ * the service refuses own-room OFF, so no room that existed before this release can escape the preference.
+ * The inventory is read in full before the run starts: an unreadable task or layout throws, and the run never
+ * completes on partial evidence. Every task must be confirmed by the service before completion.
+ */
+export async function bootstrapMissionRooms(config, tasks, layoutRooms, request = fetch) {
+    const inventory = tasks().filter(task => task.deletion?.status !== 'pending')
+        .map(task => ({ task, cids: [...notificationRoomCids(task), ...layoutRooms(task)] })).filter(entry => entry.cids.length);
+    const generation = nextGeneration();
+    const begin = await missionRequest(config, '/api/v1/missions/bootstrap', { generation, complete: false }, request);
+    if (begin.status < 200 || begin.status >= 300)
+        throw new MissionOwnershipUnavailable(`bootstrap refused (HTTP ${begin.status})`);
+    for (const { task, cids } of inventory)
+        await registerMission(config, task.task_id, recordNotificationRooms(task.task_id, cids), request);
+    const done = await missionRequest(config, '/api/v1/missions/bootstrap', { generation, complete: true }, request);
+    if (done.status < 200 || done.status >= 300)
+        throw new MissionOwnershipUnavailable(`bootstrap completion refused (HTTP ${done.status})`);
+}

package/dist/notifications/outbox.d.ts

@@ -44,12 +44,22 @@ export declare class NotificationOutbox {
     checkpoint?: unknown;
     private running?;
     private retired;
+    private again;
+    private failed;
+    private closed;
     private timer;
     constructor(file: string, config: ProducerConfig, project: (value: unknown, id: string) => Promise<NotificationInput>, warn?: (message: string) => void);
     private persist;
     advance(cursor: number): void;
     saveCheckpoint(checkpoint: unknown): void;
     enqueue(id: string, value: unknown, cursor?: number | undefined): boolean;
+    /**
+     * Deliver soon after a durable enqueue instead of at the next recovery tick. A request
+     * during a pass (which iterates its own snapshot) runs one follow-up pass after it;
+     * after a failed pass only the recovery timer retries, so arrivals during an outage
+     * add no attempts.
+     */
+    prompt(): void;
     drain(): Promise<void>;
     private drainOnce;
     /** Wait for the current send before clearing queued sends and retiring its target. */

package/dist/notifications/outbox.js

@@ -99,6 +99,9 @@ export class NotificationOutbox {
     checkpoint;
     running;
     retired = false;
+    again = false;
+    failed = false;
+    closed = false;
     timer;
     constructor(file, config, project, warn = () => { }) {
         this.file = file;
@@ -152,12 +155,34 @@ export class NotificationOutbox {
         this.persist([...this.entries, { id, value, targetVersion: 1 }], cursor);
         return true;
     }
+    /**
+     * Deliver soon after a durable enqueue instead of at the next recovery tick. A request
+     * during a pass (which iterates its own snapshot) runs one follow-up pass after it;
+     * after a failed pass only the recovery timer retries, so arrivals during an outage
+     * add no attempts.
+     */
+    prompt() {
+        if (this.closed || this.retired || this.failed)
+            return;
+        if (this.running) {
+            this.again = true;
+            return;
+        }
+        void this.drain();
+    }
     drain() {
         if (this.retired)
             return Promise.resolve();
-        return this.running ??= this.drainOnce().finally(() => { this.running = undefined; });
+        return this.running ??= this.drainOnce().finally(() => {
+            this.running = undefined;
+            if (this.again) {
+                this.again = false;
+                this.prompt();
+            }
+        });
     }
     async drainOnce() {
+        this.failed = false;
         let attempts = 0;
         for (const entry of [...this.entries]) {
             if (!supported(entry))
@@ -188,6 +213,7 @@ export class NotificationOutbox {
                 this.persist(this.entries.filter(e => !same(entry.id)(e)));
             }
             catch {
+                this.failed = true;
                 this.warn('Notification producer delivery pending; retrying from durable outbox');
                 break;
             }
@@ -195,5 +221,5 @@ export class NotificationOutbox {
     }
     /** Wait for the current send before clearing queued sends and retiring its target. */
     async retire() { this.retired = true; clearInterval(this.timer); await this.running; this.persist(this.entries.filter(entry => !supported(entry))); }
-    async close() { clearInterval(this.timer); await this.running; }
+    async close() { this.closed = true; clearInterval(this.timer); await this.running; }
 }

package/dist/notifications/task-producer.d.ts

@@ -1,3 +1,4 @@
+import type { TaskRecord } from '../rooms-tasks/types.js';
 import type { ProducerConfig } from './outbox.js';
 /** The Fleet manager owns this sender even when the web console is stopped.
  * Events are already durable in their owning task commit, so no second outbox
@@ -6,13 +7,22 @@ export declare class TaskNotificationProducer {
     private readonly config;
     private readonly warn;
     private readonly request;
+    /** Existing tasks and their layout room CIDs, registered once per start before own-room OFF can be chosen. */
+    private readonly missions?;
     private timer?;
     private dirty;
     private running?;
     private offset;
     private stopped;
     private readonly shutdown;
-    constructor(config: ProducerConfig, warn?: (line: string) => void, request?: typeof fetch);
+    private bootstrapped;
+    private bootstrapAt;
+    constructor(config: ProducerConfig, warn?: (line: string) => void, request?: typeof fetch, 
+    /** Existing tasks and their layout room CIDs, registered once per start before own-room OFF can be chosen. */
+    missions?: {
+        tasks: () => TaskRecord[];
+        layoutRooms: (task: TaskRecord) => string[];
+    } | undefined);
     drain(): Promise<void>;
     private retry;
     private drainOnce;

package/dist/notifications/task-producer.js

@@ -1,6 +1,7 @@
 import { observeFleetResources } from '../application/resource-observer.js';
 import { tasksDir } from '../rooms-tasks/task-state.js';
-import { acknowledgeTaskNotification, pendingTaskNotifications } from '../rooms-tasks/task-state.js';
+import { acknowledgeTaskNotification, convertRetiredTaskNotifications, pendingTaskNotifications } from '../rooms-tasks/task-state.js';
+import { bootstrapMissionRooms, drainMissionCleanup } from './mission-ownership.js';
 /** The Fleet manager owns this sender even when the web console is stopped.
  * Events are already durable in their owning task commit, so no second outbox
  * admission/crash window is needed. A failed task does not block other tasks. */
@@ -8,16 +9,22 @@ export class TaskNotificationProducer {
     config;
     warn;
     request;
+    missions;
     timer;
     dirty = false;
     running;
     offset = 0;
     stopped = false;
     shutdown = new AbortController();
-    constructor(config, warn = () => { }, request = fetch) {
+    bootstrapped = false;
+    bootstrapAt = 0;
+    constructor(config, warn = () => { }, request = fetch, 
+    /** Existing tasks and their layout room CIDs, registered once per start before own-room OFF can be chosen. */
+    missions) {
         this.config = config;
         this.warn = warn;
         this.request = request;
+        this.missions = missions;
         // Subscribe before startup replay: a commit while fetch is pending needs a second pass.
         observeFleetResources({ retryWatchFailures: true, paths: [tasksDir()], roots: [] }, state => {
             if (state.health !== 'healthy')
@@ -49,15 +56,35 @@ export class TaskNotificationProducer {
         });
         return this.running;
     }
-    retry() {
+    retry(delay = 3000) {
         if (this.stopped || this.timer)
             return;
-        this.timer = setTimeout(() => { this.timer = undefined; void this.drain(); }, 3000);
+        this.timer = setTimeout(() => { this.timer = undefined; void this.drain(); }, delay);
         this.timer.unref();
     }
     async drainOnce() {
         if (this.stopped)
             return;
+        // Deletion first: a retired task's notifications go before any other delivery work in this pass.
+        if (convertRetiredTaskNotifications() || await drainMissionCleanup(this.config, this.warn, this.request))
+            this.retry();
+        if (this.missions && !this.bootstrapped && !this.stopped) {
+            // A failed run waits 30s: unavailable inventory or a refused registration needs repair, not a tight loop.
+            const wait = this.bootstrapAt - Date.now();
+            if (wait > 0)
+                this.retry(wait);
+            else {
+                try {
+                    await bootstrapMissionRooms(this.config, this.missions.tasks, this.missions.layoutRooms, this.request);
+                    this.bootstrapped = true;
+                }
+                catch {
+                    this.warn('Mission room registration pending; own-room message preference stays unavailable');
+                    this.bootstrapAt = Date.now() + 30_000;
+                    this.retry(30_000);
+                }
+            }
+        }
         const pending = pendingTaskNotifications(this.warn);
         if (!pending.length)
             return;
@@ -83,7 +110,9 @@ export class TaskNotificationProducer {
                         });
                         await response.body?.cancel();
                         if (!response.ok) {
-                            this.warn(`Task notification delivery pending (HTTP ${response.status}); committed event retained`);
+                            this.warn(response.status === 400 && event.delivery
+                                ? 'Notification service does not support push-only task events; committed events retained'
+                                : `Task notification delivery pending (HTTP ${response.status}); committed event retained`);
                             break;
                         }
                         acknowledgeTaskNotification(task.taskId, event.eventId);

package/dist/rooms-tasks/layout-service.d.ts

@@ -30,6 +30,8 @@ export declare class RoomLayoutService {
     supervisor(id?: string, templates?: Record<string, AgentTemplateDefinition>): NativeLayoutSupervisor;
     private owner;
     private engine;
+    /** A task's layout rooms are registered with the notification service before the Owner can join them. */
+    private beforeOwner;
     open(id: string, cleanup?: boolean): RoomLayout;
     /** `scope` lets an owner (e.g. a Task) snapshot an adjusted definition and pin agent working directories. */
     create(name: string, bindings?: Record<string, LayoutInstance>, id?: string, scope?: {

package/dist/rooms-tasks/layout-service.js

@@ -178,11 +178,16 @@ export class RoomLayoutService {
         const path = layoutRunPath(id);
         if (existsSync(path))
             assertLayoutFile(path);
-        return new RoomLayout(path, () => createCoworkAdapter(), this.supervisor(id), cleanup ? undefined : this.owner());
+        return new RoomLayout(path, () => createCoworkAdapter(), this.supervisor(id), cleanup ? undefined : this.owner(), this.beforeOwner(id));
+    }
+    /** A task's layout rooms are registered with the notification service before the Owner can join them. */
+    beforeOwner(id) {
+        const taskId = /^task-([0-9a-z]{9}[0-9a-f]{8})$/.exec(id)?.[1];
+        return taskId ? async (roomCid) => (await import('../notifications/mission-ownership.js')).associateRoomNotifications(taskId, roomCid) : undefined;
     }
     open(id, cleanup = false) {
         const initial = this.engine(id, cleanup), snapshot = initial.snapshot();
-        return new RoomLayout(layoutRunPath(id), () => createCoworkAdapter(), this.supervisor(id, snapshot.agent_templates ?? {}), cleanup ? undefined : this.owner());
+        return new RoomLayout(layoutRunPath(id), () => createCoworkAdapter(), this.supervisor(id, snapshot.agent_templates ?? {}), cleanup ? undefined : this.owner(), this.beforeOwner(id));
     }
     /** `scope` lets an owner (e.g. a Task) snapshot an adjusted definition and pin agent working directories. */
     async create(name, bindings = {}, id = `run-${randomUUID()}`, scope = {}) {

package/dist/rooms-tasks/layout.d.ts

@@ -104,9 +104,13 @@ export declare class RoomLayout {
     private file;
     private supervisor;
     private owner?;
+    /** Runs before the Owner may join each room; a failure stops here and the next pass retries it. */
+    private beforeOwner?;
     private coworkAdapter?;
     private readonly coworkFactory;
-    constructor(file: string, cowork: CoworkAdapter | (() => CoworkAdapter), supervisor: LayoutSupervisor, owner?: LayoutOwner | undefined);
+    constructor(file: string, cowork: CoworkAdapter | (() => CoworkAdapter), supervisor: LayoutSupervisor, owner?: LayoutOwner | undefined, 
+    /** Runs before the Owner may join each room; a failure stops here and the next pass retries it. */
+    beforeOwner?: ((roomCid: string) => Promise<void>) | undefined);
     private get cowork();
     snapshot(): RoomLayoutState;
     private save;

package/dist/rooms-tasks/layout.js

@@ -39,12 +39,16 @@ export class RoomLayout {
     file;
     supervisor;
     owner;
+    beforeOwner;
     coworkAdapter;
     coworkFactory;
-    constructor(file, cowork, supervisor, owner) {
+    constructor(file, cowork, supervisor, owner, 
+    /** Runs before the Owner may join each room; a failure stops here and the next pass retries it. */
+    beforeOwner) {
         this.file = file;
         this.supervisor = supervisor;
         this.owner = owner;
+        this.beforeOwner = beforeOwner;
         this.coworkFactory = typeof cowork === 'function' ? cowork : () => cowork;
     }
     get cowork() { return this.coworkAdapter ??= this.coworkFactory(); }
@@ -161,6 +165,8 @@ export class RoomLayout {
                 activation_requirements: !spec.members.length && s.owner ? [{ role: s.owner.role, count: 1 }]
                     : [...new Set(spec.members.map(roleFor))].map(role => ({ role, count: spec.members.filter(m => roleFor(m) === role).length })),
             }), native => { room.native = native; s.order.push(key); });
+        if (s.owner && !room.owner_ready && this.beforeOwner)
+            await this.beforeOwner(room.native.identity_cid);
         if (s.owner && !room.owner_ready)
             await this.mutation(s, `owner:${key}`, async () => {
                 await this.cowork.acceptInvite(room.native.room_id, this.owner.invite, { role: s.owner.role, expected_cid: s.owner.cid });

package/dist/rooms-tasks/notification-manifest.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Notification ownership of a task's rooms. Room identity CIDs are recorded when Fleet records the room, and are
+ * never removed (a room erased early stays attributable), so deleting the task can retire its rooms' notifications
+ * even after room records are gone.
+ */
+export interface TaskNotificationManifest {
+    revision: number;
+    room_cids: string[];
+}
+export declare const canonicalCid: (cid: string) => string;
+export declare function validRoomCid(cid: unknown): cid is string;
+/** Union of rooms; the revision advances only when a room is added. */
+export declare function withManifestRooms(manifest: TaskNotificationManifest | undefined, cids: string[]): TaskNotificationManifest;
+/** Durable intent to retire a deleted task's notifications; written at deletion acceptance, merged, removed on service acknowledgement. */
+export interface MissionCleanupIntent {
+    schema: 1;
+    taskId: string;
+    contactIds: string[];
+}
+export declare const missionCleanupDir: () => string;
+/** Merge rooms into the task's intent. An existing intent that cannot be read is never replaced: this throws and the
+ * file keeps its bytes, so a later writer with only some rooms cannot erase coverage recorded earlier. */
+export declare function queueMissionCleanup(taskId: string, contactIds: string[], dir?: string): void;
+/** Readable intents, in directory order. Unreadable ones are reported by `unavailableMissionCleanups`, never dropped. */
+export declare function pendingMissionCleanups(dir?: string): MissionCleanupIntent[];
+/** Task IDs whose intent file exists but cannot be read. Their bytes are kept; they block nothing else but stay pending. */
+export declare function unavailableMissionCleanups(dir?: string): string[];
+/** Remove only the exact intent the service acknowledged; a merge since then, or an unreadable file, keeps it for another pass. */
+export declare function settleMissionCleanup(intent: MissionCleanupIntent, dir?: string): boolean;

package/dist/rooms-tasks/notification-manifest.js

@@ -0,0 +1,65 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { replaceFileAtomically } from '../atomic-file.js';
+import { stateRoot } from '../paths.js';
+const CID = /^[A-Za-z0-9_-]{1,512}$/;
+export const canonicalCid = (cid) => /^[a-f0-9]{64}$/i.test(cid) ? cid.toUpperCase() : cid;
+export function validRoomCid(cid) { return typeof cid === 'string' && CID.test(cid); }
+/** Union of rooms; the revision advances only when a room is added. */
+export function withManifestRooms(manifest, cids) {
+    const current = manifest ?? { revision: 0, room_cids: [] };
+    const added = cids.filter(validRoomCid).map(canonicalCid).filter(cid => !current.room_cids.includes(cid));
+    return added.length ? { revision: current.revision + 1, room_cids: [...current.room_cids, ...new Set(added)] } : current;
+}
+export const missionCleanupDir = () => join(stateRoot(), 'notifications', 'mission-cleanup');
+const TASK_ID = /^[0-9a-z]{9}[0-9a-f]{8}$/;
+/** Merge rooms into the task's intent. An existing intent that cannot be read is never replaced: this throws and the
+ * file keeps its bytes, so a later writer with only some rooms cannot erase coverage recorded earlier. */
+export function queueMissionCleanup(taskId, contactIds, dir = missionCleanupDir()) {
+    if (!TASK_ID.test(taskId))
+        throw new Error('invalid task ID');
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, `${taskId}.json`), previous = readMissionCleanup(path, taskId);
+    if (previous === 'unavailable')
+        throw new Error(`mission cleanup intent for ${taskId} is unreadable; file retained`);
+    const known = previous === 'absent' ? [] : previous.contactIds;
+    const merged = [...new Set([...known, ...contactIds.filter(validRoomCid).map(canonicalCid)])];
+    if (previous !== 'absent' && merged.length === known.length)
+        return;
+    replaceFileAtomically(path, JSON.stringify({ schema: 1, taskId, contactIds: merged }) + '\n', 0o600);
+}
+/** Only a missing file is absent. Unreadable, malformed or mismatched content is unavailable, never "no intent". */
+function readMissionCleanup(path, taskId) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        return error.code === 'ENOENT' ? 'absent' : 'unavailable';
+    }
+    try {
+        const value = JSON.parse(text);
+        if (value?.schema === 1 && value.taskId === taskId && Array.isArray(value.contactIds) && value.contactIds.every(validRoomCid))
+            return value;
+    }
+    catch { /* malformed */ }
+    return 'unavailable';
+}
+const intentFiles = (dir) => existsSync(dir) ? readdirSync(dir).filter(name => /^[0-9a-z]{9}[0-9a-f]{8}\.json$/.test(name)) : [];
+/** Readable intents, in directory order. Unreadable ones are reported by `unavailableMissionCleanups`, never dropped. */
+export function pendingMissionCleanups(dir = missionCleanupDir()) {
+    return intentFiles(dir).map(name => readMissionCleanup(join(dir, name), name.slice(0, -5)))
+        .filter((intent) => typeof intent === 'object');
+}
+/** Task IDs whose intent file exists but cannot be read. Their bytes are kept; they block nothing else but stay pending. */
+export function unavailableMissionCleanups(dir = missionCleanupDir()) {
+    return intentFiles(dir).filter(name => readMissionCleanup(join(dir, name), name.slice(0, -5)) === 'unavailable').map(name => name.slice(0, -5));
+}
+/** Remove only the exact intent the service acknowledged; a merge since then, or an unreadable file, keeps it for another pass. */
+export function settleMissionCleanup(intent, dir = missionCleanupDir()) {
+    const path = join(dir, `${intent.taskId}.json`), current = readMissionCleanup(path, intent.taskId);
+    if (typeof current !== 'object' || current.contactIds.length !== intent.contactIds.length)
+        return false;
+    rmSync(path, { force: true });
+    return true;
+}

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

@@ -103,6 +103,8 @@ export declare function publicReview(review: TaskReview): TaskReview;
 /** Compact summary for list and detail payloads; bodies are fetched separately. */
 export declare function taskContributionSummary(task: TaskRecord): {
     progress_count: number;
+    progress_unread: number;
+    review_unread: boolean;
     review: {
         has_markdown: boolean;
         artifact_count: number;

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

@@ -12,7 +12,7 @@ import { open } from 'node:fs/promises';
 import { basename, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { stateRoot } from '../paths.js';
 import { MAX_FILE_BYTES, openDirectory } from '../file-delivery/reader.js';
-import { getTask, TaskStateError, updateTaskContribution } from './task-state.js';
+import { contributionUnread, getTask, reviewRevision, TaskStateError, updateTaskContribution } from './task-state.js';
 import { assertWorkspacePresent } from './workspace.js';
 export const PROGRESS_TEXT_MAX = 4_000;
 export const PROGRESS_MAX_ENTRIES = 200;
@@ -109,7 +109,7 @@ export function appendTaskProgress(taskId, input) {
 // ── Review Markdown ────────────────────────────────────────────────────
 /** Every change to the package gets the next revision, so readers can tell any two states apart. */
 function nextRevision(review) {
-    return (review?.revision ?? 0) + 1;
+    return reviewRevision(review) + 1;
 }
 export function getTaskReview(taskId) {
     assertTaskId(taskId);
@@ -544,17 +544,19 @@ export function publicProgressEntry(entry) {
     return rest;
 }
 export function publicReview(review) {
-    return { ...review, revision: review.revision ?? 1, artifacts: review.artifacts.map(({ request_key: _key, ...rest }) => rest) };
+    return { ...review, revision: reviewRevision(review), artifacts: review.artifacts.map(({ request_key: _key, ...rest }) => rest) };
 }
 /** Compact summary for list and detail payloads; bodies are fetched separately. */
 export function taskContributionSummary(task) {
+    const unread = contributionUnread(task);
     return {
         progress_count: task.progress?.length ?? 0,
+        progress_unread: unread.progress,
+        review_unread: unread.review,
         review: {
             has_markdown: !!task.review?.markdown.trim(),
             artifact_count: task.review?.artifacts.length ?? 0,
-            // Packages written before revisions existed count as revision 1 until their next change.
-            revision: task.review ? task.review.revision ?? 1 : 0,
+            revision: reviewRevision(task.review),
             ...(task.review ? { updated_at: task.review.updated_at } : {}),
         },
     };

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

@@ -1,13 +1,41 @@
 import type { ArchivedMemberAbsence } from './types.js';
 import type { TaskRecord, TaskState, TaskOrigin, TaskTemplateRef, TaskOutcome, TaskMemberRole, TaskTerminalIntent, TaskDeletionActor, TaskDeletionMemberPhase, TaskNotificationEvent } from './types.js';
+import { type TaskNotificationManifest } from './notification-manifest.js';
 export declare const tasksDir: () => string;
 export declare class TaskStateError extends Error {
 }
+/** Packages written before revisions existed count as revision 1; their next change becomes 2. No package is 0. */
+export declare const reviewRevision: (review: {
+    revision?: number;
+} | undefined) => number;
+/** Item-based Progress unread and revision-based To review unread. An absent read state means nothing is unread. */
+export declare function contributionUnread(task: Pick<TaskRecord, 'progress' | 'review' | 'contribution_reads'>): {
+    progress: number;
+    review: boolean;
+};
+/** Acknowledge Progress entries the user actually viewed; unknown IDs are ignored and the set only grows. */
+export declare function acknowledgeTaskProgress(id: string, ids: string[]): {
+    progress: number;
+    review: boolean;
+};
+/** Acknowledge the To review revision the user saw. Only moves forward; a revision newer than current is refused. */
+export declare function acknowledgeTaskReview(id: string, revision: number): {
+    progress: number;
+    review: boolean;
+};
 /** 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
+ * already admitted one as an inbox row repairs that row to push-only itself, so the retry matches; any refusal keeps the
+ * event queued. */
 export declare function pendingTaskNotifications(warn?: (line: string) => void): Array<{
     taskId: string;
     events: TaskNotificationEvent[];
+    upgraded: string[];
 }>;
+/** Earlier releases kept a deleted task's queued events in `.notification-retired`. They are obsolete: each
+ * becomes a cleanup intent for its task and is never delivered. Returns the number converted. */
+export declare function convertRetiredTaskNotifications(): number;
 /** Service event-id dedupe covers acceptance followed by a crash before this acknowledgement. */
 export declare function acknowledgeTaskNotification(id: string, eventId: string): void;
 /**
@@ -62,6 +90,13 @@ export declare function setTaskTerminalIntentError(id: string, error: string, re
 export declare function finishTaskTerminalIntent(id: string): TaskRecord;
 export declare function failTask(id: string, error: string): TaskRecord;
 export declare function updateTaskRoom(id: string, roomId: string, roomIdentityCid: string): TaskRecord;
+/** Record room CIDs as this task's notification-owned rooms (union only). Returns the manifest to register. */
+export declare function recordNotificationRooms(id: string, cids: string[]): TaskNotificationManifest;
+/** After a refused registration (409), move the manifest revision past the refused one; rooms are unchanged. A retry
+ * then registers the full union under a newer revision. Nothing happens if the manifest already moved on. */
+export declare function advanceNotificationRevision(id: string, refused: number): void;
+/** Every room this task ever recorded, including the current one from records written before manifests existed. */
+export declare function notificationRoomCids(task: Pick<TaskRecord, 'notification_manifest' | 'room_identity_cid'>): string[];
 export declare function updateTaskTemplate(id: string, template: TaskTemplateRef): TaskRecord;
 export declare function updateTaskMembers(id: string, members: TaskMemberRole[]): TaskRecord;
 /**