@ours.network/fleet 2.3.2 → 2.3.4

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-review.js

@@ -512,6 +512,8 @@ export function insideDirectory(root, path) {
 export function taskWorkspaceRoot(task) {
     if (!task.workspace)
         throw new TaskReviewError('invalid_request', `task ${task.task_id} has no owned workspace`);
+    if (task.workspace_removal)
+        throw new TaskReviewError('invalid_request', `the working files of task ${task.task_id} were removed, so no file can be attached from them`);
     assertWorkspacePresent(task.workspace, 'task', task.task_id);
     return task.workspace.path;
 }

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

@@ -1,5 +1,5 @@
 import type { ArchivedMemberAbsence } from './types.js';
-import type { TaskRecord, TaskState, TaskOrigin, TaskTemplateRef, TaskOutcome, TaskMemberRole, TaskTerminalIntent, TaskDeletionActor, TaskDeletionMemberPhase, TaskNotificationEvent } from './types.js';
+import type { TaskRecord, TaskState, TaskOrigin, TaskTemplateRef, TaskOutcome, TaskMemberRole, TaskTerminalIntent, TaskDeletionActor, TaskDeletionMemberPhase, TaskNotificationEvent, TaskWorkspaceRemoval } from './types.js';
 import { type LabelCandidate } from './member-naming.js';
 import { type TaskNotificationManifest } from './notification-manifest.js';
 export declare const tasksDir: () => string;
@@ -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
@@ -283,4 +295,9 @@ export declare function updateTaskContribution<T>(id: string, change: (task: Tas
     changed: boolean;
 }): T;
 export declare function updateTaskBrief(id: string, brief: string, expectedBrief: string): TaskRecord;
+/**
+ * Record a step of an explicit working-folder removal. Callers hold the task
+ * operation lock; lifecycle state is untouched.
+ */
+export declare function updateTaskWorkspaceRemoval(id: string, change: (removal: TaskWorkspaceRemoval | undefined) => TaskWorkspaceRemoval | undefined): TaskRecord;
 export {};

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

@@ -266,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)))
@@ -482,7 +518,8 @@ export function createTask(input) {
         const fresh = readTask(outcome.taskId);
         if (outcome.kind === 'existing')
             assertNoPendingDeletion(fresh);
-        if (fresh.workspace)
+        // A replayed create never recreates a folder the Owner removed.
+        if (fresh.workspace && !fresh.workspace_removal)
             ensureWorkspace(fresh.workspace);
         return fresh;
     });
@@ -1466,3 +1503,21 @@ export function updateTaskBrief(id, brief, expectedBrief) {
         return task;
     });
 }
+/**
+ * Record a step of an explicit working-folder removal. Callers hold the task
+ * operation lock; lifecycle state is untouched.
+ */
+export function updateTaskWorkspaceRemoval(id, change) {
+    assertCanonicalTaskId(id);
+    return withTaskLock(id, () => {
+        const task = readTask(id);
+        assertNoPendingDeletion(task);
+        const next = change(task.workspace_removal);
+        if (next)
+            task.workspace_removal = next;
+        else
+            delete task.workspace_removal;
+        writeTask(task);
+        return task;
+    });
+}

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

@@ -99,6 +99,21 @@ export interface TaskDeletionIntent {
     first_failure?: string;
     first_recovery_hint?: string;
 }
+/**
+ * Explicit removal of a Done task's owned working folder. The task record,
+ * Progress, To review files and agent archives stay; only the folder goes.
+ * `started_at` without `completed_at` means removal began and has not been
+ * confirmed: it may still be running or have been interrupted.
+ */
+export interface TaskWorkspaceRemoval {
+    started_at: string;
+    actor: TaskDeletionActor;
+    completed_at?: string;
+    /** The recorded folder was already absent when removal first ran. */
+    already_missing?: true;
+    error?: string;
+    error_at?: string;
+}
 export interface TaskLayoutLink {
     name: string;
     /** Deterministic `task-<task_id>` Room Layout run ID. */
@@ -173,6 +188,8 @@ export interface TaskRecord {
     /** Rooms whose notifications belong to this task; only grows. */
     notification_manifest?: import('./notification-manifest.js').TaskNotificationManifest;
     workspace?: import('./workspace.js').OwnedWorkspace;
+    /** Set once the Owner asked to remove the working folder; the record is never recreated from it. */
+    workspace_removal?: TaskWorkspaceRemoval;
     task_id: string;
     /**
      * Immutable human mission key (`MSN-1`), issued once from a durable

package/dist/rooms-tasks/workspace-removal.d.ts

@@ -0,0 +1,85 @@
+import type { TaskDeletionActor, TaskRecord } from './types.js';
+/**
+ * Explicit Owner removal of a Done task's working folder. Only the exact
+ * recorded task-owned folder is removed, through the guarded workspace
+ * deletion (marker, Git registration, symlink and mount fences). The task
+ * record, Progress, To review files (a separate store), agent archives and
+ * rooms' history are never touched. Every precondition is re-read under the
+ * task-operation lock that serializes terminal settlement, deletion and
+ * recovery; anything that cannot be proven idle is refused, never stopped.
+ */
+export type WorkspaceRemovalResult = 'removed' | 'already_removed' | 'already_missing';
+export interface WorkspaceRemovalOutcome {
+    task: TaskRecord;
+    result: WorkspaceRemovalResult;
+    /** Retained text fields that mention the removed folder; those paths no longer resolve. */
+    mentions: string[];
+}
+export interface WorkspaceRemovalDeps {
+    /** Working directories of configured permanent agents; undefined when the configuration is unreadable. */
+    permanentCwds?: readonly (string | undefined)[];
+    /** Test seam: processes whose cwd, root or open files are inside `path`, or cannot be read. */
+    processesUsing?(path: string, context: ProcessCheckContext): ProcessUse;
+}
+/**
+ * Every process whose cwd, root or open file descriptor is inside `path`, or
+ * whose use cannot be excluded. Only Linux exposes this without extra tools;
+ * elsewhere removal is refused. When a process's entries are unreadable (for
+ * example non-dumpable, or in a container), it is excluded only by evidence:
+ * it is a zombie, its mount table cannot reach the folder's filesystem
+ * location, it is the user's service manager (attested by the system manager)
+ * whose own records name nothing in the folder, or it is that manager's PAM
+ * helper started before the folder existed; otherwise it is reported.
+ * Other users' unreadable processes are skipped when a private ancestor
+ * closes the folder to them; a superuser process is outside this check.
+ */
+/** A same-user process whose cwd and descriptors cannot be read. */
+export interface UnverifiedProcess {
+    token: string;
+    description: string;
+}
+export interface ProcessUse {
+    /** Processes proven to use the folder. */
+    users: string[];
+    /** Processes whose use can be neither proven nor excluded. */
+    unverified: UnverifiedProcess[];
+}
+export interface ProcessCheckContext {
+    /** The folder's recorded path; configuration names it, not its tombstone. */
+    original: string;
+    /** When the folder came into existence (ms since the epoch). */
+    createdAt: number;
+}
+export declare function processesUsing(path: string, context: ProcessCheckContext): ProcessUse;
+declare const run: (command: string, args: string[]) => string;
+/**
+ * Whether the user service manager may use the folder, from its own read-only
+ * records: its attested working directory, socket units' paths and every
+ * file descriptor store (systemd 254+). Undefined when none names the folder;
+ * otherwise the reason, including any record that cannot be read.
+ */
+export declare function userManagerUse(uid: number, roots: string[], exec?: typeof run): string | undefined;
+/** True when some mount in the table exposes the filesystem location, or anything under it. */
+export declare function reaches(mountinfo: string, target: {
+    device: string;
+    inside: string;
+}): boolean;
+export declare function assertTaskWorkspaceRemovable(task: TaskRecord, deps: WorkspaceRemovalDeps): void;
+export declare function removeTaskWorkspace(taskId: string, actor: TaskDeletionActor, deps?: WorkspaceRemovalDeps): Promise<WorkspaceRemovalOutcome>;
+export interface WorkingFilesSummary {
+    /** `removing`: removal began and is not confirmed — still running or interrupted; retry resumes it. */
+    state: 'none' | 'present' | 'removing' | 'failed' | 'removed';
+    started_at?: string;
+    removed_at?: string;
+    error?: string;
+}
+/** Record-only readback for task payloads; never touches the filesystem. */
+export declare function workingFilesSummary(task: TaskRecord): WorkingFilesSummary;
+export declare function assertCwdNotInRemovedTaskFolder(cwd: string | undefined): void;
+/**
+ * Launch fence: an agent never starts in, and so never recreates, the folder
+ * of a task whose working files were removed. Creating its state under the
+ * folder's use lock makes it visible to a concurrent removal's scan.
+ */
+export declare function withTaskFolderUseFence<T>(cwd: string | undefined, work: () => T): T;
+export {};