@ours.network/fleet 0.18.1 → 0.19.0-nightly.10

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

@@ -0,0 +1,221 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { replaceFileAtomically } from '../atomic-file.js';
+import { stateRoot } from '../paths.js';
+export const roomsDir = () => join(stateRoot(), 'rooms');
+function roomPath(id) { return join(roomsDir(), `${id}.json`); }
+export class RoomStateError extends Error {
+}
+function readRoom(id) {
+    const p = roomPath(id);
+    if (!existsSync(p))
+        throw new RoomStateError(`room not found: ${id}`);
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+function writeRoom(record) {
+    mkdirSync(roomsDir(), { recursive: true });
+    replaceFileAtomically(roomPath(record.room_id), JSON.stringify(record, null, 2) + '\n');
+}
+export function createRoomRecord(input) {
+    const existing = getRoomRecord(input.room_id);
+    if (existing)
+        return existing;
+    const record = {
+        room_id: input.room_id,
+        room_name: input.room_name,
+        goal: input.goal,
+        room_identity_cid: input.room_identity_cid,
+        task_id: input.task_id,
+        template_snapshot: input.template_snapshot,
+        saga: { phase: 'persist_intent', step_index: 0 },
+        member_seats: [],
+        state: 'provisioning',
+        created_at: new Date().toISOString(),
+    };
+    writeRoom(record);
+    return record;
+}
+export function getRoomRecord(id) {
+    try {
+        return readRoom(id);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function listRoomRecords(filter) {
+    const dir = roomsDir();
+    if (!existsSync(dir))
+        return [];
+    const states = filter?.state
+        ? (Array.isArray(filter.state) ? filter.state : [filter.state])
+        : undefined;
+    const rooms = [];
+    for (const f of readdirSync(dir).filter(f => f.endsWith('.json'))) {
+        try {
+            const r = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+            if (!states || states.includes(r.state))
+                rooms.push(r);
+        }
+        catch { /* skip corrupt */ }
+    }
+    return rooms.sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+export function advanceSaga(id, phase, stepIndex, detail) {
+    const r = readRoom(id);
+    r.saga = { phase, step_index: stepIndex ?? 0 };
+    if (detail)
+        r.provisioning_detail = detail;
+    else
+        delete r.provisioning_detail;
+    writeRoom(r);
+    return r;
+}
+export function setSagaError(id, error, hint, detail) {
+    const r = readRoom(id);
+    r.saga.error = error;
+    r.saga.recovery_hint = hint;
+    if (detail)
+        r.provisioning_detail = detail;
+    writeRoom(r);
+    return r;
+}
+export function setRoomIdentity(id, roomIdentityCid) {
+    const r = readRoom(id);
+    r.room_identity_cid = roomIdentityCid;
+    writeRoom(r);
+    return r;
+}
+export function setOwnerSeat(id, ownerSeatCid, inviteFingerprint) {
+    const r = readRoom(id);
+    r.owner_seat_cid = ownerSeatCid;
+    r.owner_invite_fingerprint = inviteFingerprint;
+    writeRoom(r);
+    return r;
+}
+export function updateMemberSeats(id, seats) {
+    const r = readRoom(id);
+    r.member_seats = seats;
+    writeRoom(r);
+    return r;
+}
+export function activateRoom(id) {
+    const r = readRoom(id);
+    r.state = 'active';
+    r.saga = { phase: 'completed', step_index: 0 };
+    delete r.provisioning_detail;
+    r.activated_at = new Date().toISOString();
+    writeRoom(r);
+    return r;
+}
+export function closeRoom(id) {
+    const r = readRoom(id);
+    if (r.state === 'closed')
+        return r;
+    r.state = 'closed';
+    r.closed_at = new Date().toISOString();
+    r.close = {
+        phase: 'completed',
+        accepted_at: r.close?.accepted_at ?? r.closed_at,
+        ...(r.close?.first_failure ? { first_failure: r.close.first_failure } : {}),
+        ...(r.close?.first_recovery_hint
+            ? { first_recovery_hint: r.close.first_recovery_hint }
+            : {}),
+    };
+    writeRoom(r);
+    return r;
+}
+export function beginRoomClose(id) {
+    const r = readRoom(id);
+    if (r.state === 'closed')
+        return r;
+    const acceptedAt = r.close?.accepted_at ?? new Date().toISOString();
+    r.state = 'closing';
+    r.close = {
+        phase: r.close?.phase ?? 'retire_members',
+        accepted_at: acceptedAt,
+        ...(r.close?.error ? { error: r.close.error } : {}),
+        ...(r.close?.error_at ? { error_at: r.close.error_at } : {}),
+        ...(r.close?.recovery_hint ? { recovery_hint: r.close.recovery_hint } : {}),
+        ...(r.close?.first_failure ? { first_failure: r.close.first_failure } : {}),
+        ...(r.close?.first_recovery_hint
+            ? { first_recovery_hint: r.close.first_recovery_hint }
+            : {}),
+    };
+    writeRoom(r);
+    return r;
+}
+const RETIREMENT_ORDER = [
+    'stop_requested', 'liveness_absent', 'archive_secured', 'identity_absent',
+];
+export function advanceMemberRetirement(id, roleName, phase, launchId, archivePath) {
+    const r = readRoom(id);
+    if (r.state !== 'closing')
+        throw new RoomStateError(`room ${id} is not closing`);
+    const seat = r.member_seats.find(candidate => candidate.role_name === roleName);
+    if (!seat)
+        throw new RoomStateError(`room ${id} has no recorded member ${roleName}`);
+    const previous = seat.retirement;
+    if (previous && previous.launch_id !== launchId) {
+        throw new RoomStateError(`room ${id} member ${roleName} launch changed from ${previous.launch_id} to ${launchId}`);
+    }
+    const nextIndex = RETIREMENT_ORDER.indexOf(phase);
+    const previousIndex = previous ? RETIREMENT_ORDER.indexOf(previous.phase) : -1;
+    if (nextIndex < previousIndex) {
+        throw new RoomStateError(`room ${id} member ${roleName} retirement cannot move backward to ${phase}`);
+    }
+    seat.retirement = {
+        phase,
+        launch_id: launchId,
+        updated_at: new Date().toISOString(),
+        ...(archivePath ?? previous?.archive_path
+            ? { archive_path: archivePath ?? previous?.archive_path }
+            : {}),
+    };
+    if (phase === 'identity_absent')
+        seat.seat_state = 'removed';
+    writeRoom(r);
+    return r;
+}
+export function advanceRoomClose(id, phase) {
+    const r = readRoom(id);
+    if (r.state === 'closed')
+        return r;
+    if (r.state !== 'closing' || !r.close)
+        throw new RoomStateError(`room ${id} is not closing`);
+    const order = ['retire_members', 'close_cowork', 'completed'];
+    if (order.indexOf(phase) < order.indexOf(r.close.phase)) {
+        throw new RoomStateError(`room ${id} close cannot move backward to ${phase}`);
+    }
+    const progressed = order.indexOf(phase) > order.indexOf(r.close.phase);
+    r.close = {
+        phase,
+        accepted_at: r.close.accepted_at,
+        ...(!progressed && r.close.error ? { error: r.close.error } : {}),
+        ...(!progressed && r.close.error_at ? { error_at: r.close.error_at } : {}),
+        ...(!progressed && r.close.recovery_hint
+            ? { recovery_hint: r.close.recovery_hint }
+            : {}),
+        ...(r.close.first_failure ? { first_failure: r.close.first_failure } : {}),
+        ...(r.close.first_recovery_hint
+            ? { first_recovery_hint: r.close.first_recovery_hint }
+            : {}),
+    };
+    writeRoom(r);
+    return r;
+}
+export function setRoomCloseError(id, error, recoveryHint) {
+    const r = readRoom(id);
+    if (r.state === 'closed')
+        return r;
+    if (r.state !== 'closing' || !r.close)
+        throw new RoomStateError(`room ${id} is not closing`);
+    r.close.first_failure ??= error;
+    r.close.first_recovery_hint ??= recoveryHint;
+    r.close.error = error;
+    const previousErrorAt = Date.parse(r.close.error_at ?? '');
+    r.close.error_at = new Date(Math.max(Date.now(), Number.isFinite(previousErrorAt) ? previousErrorAt + 1 : 0)).toISOString();
+    r.close.recovery_hint = recoveryHint;
+    writeRoom(r);
+    return r;
+}

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

@@ -0,0 +1,43 @@
+import type { TaskRecord, TaskState, TaskOrigin, TaskTemplateRef, TaskOutcome, TaskMemberRole, TaskTerminalIntent } from './types.js';
+export declare const tasksDir: () => string;
+export declare class TaskStateError extends Error {
+}
+export interface CreateTaskInput {
+    title: string;
+    brief?: string;
+    brief_file?: string;
+    template?: TaskTemplateRef;
+    origin: TaskOrigin;
+    idempotency_key?: string;
+    start?: boolean;
+    no_room?: boolean;
+    room_id?: string;
+}
+export declare function createTask(input: CreateTaskInput): TaskRecord;
+export declare function getTask(id: string): TaskRecord;
+export declare function listTasks(filter?: {
+    state?: TaskState | TaskState[];
+}): TaskRecord[];
+export declare function findByIdempotencyKey(key: string): TaskRecord | undefined;
+export declare function startTask(id: string): TaskRecord;
+export declare function activateTask(id: string): TaskRecord;
+export declare function blockTask(id: string, reason: string): TaskRecord;
+export declare function unblockTask(id: string): TaskRecord;
+export declare function reviewTask(id: string): TaskRecord;
+export declare function completeTask(id: string, outcome?: TaskOutcome): TaskRecord;
+export declare function cancelTask(id: string): TaskRecord;
+/** Persist the first terminal request. Callers serialize this with the task-operation lock. */
+export declare function beginTaskTerminalIntent(id: string, input: {
+    kind: TaskTerminalIntent['kind'];
+    roomId?: string;
+    outcome?: TaskOutcome;
+}): TaskRecord;
+/** Record an actionable failure without claiming the requested terminal state. */
+export declare function setTaskTerminalIntentError(id: string, error: string, recoveryHint: string): TaskRecord;
+/** Atomically publish the task terminal state and settled audit cursor. */
+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;
+export declare function updateTaskTemplate(id: string, template: TaskTemplateRef): TaskRecord;
+export declare function updateTaskMembers(id: string, members: TaskMemberRole[]): TaskRecord;
+export declare function deleteTask(id: string): void;

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

@@ -0,0 +1,277 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { replaceFileAtomically } from '../atomic-file.js';
+import { stateRoot } from '../paths.js';
+import { TASK_TERMINAL_STATES, TASK_CANCELLABLE_STATES } from './types.js';
+export const tasksDir = () => join(stateRoot(), 'tasks');
+function taskPath(id) { return join(tasksDir(), `${id}.json`); }
+function generateTaskId() {
+    const ts = Date.now().toString(36).padStart(9, '0');
+    const rand = randomUUID().replace(/-/g, '').slice(0, 8);
+    return `${ts}${rand}`;
+}
+export class TaskStateError extends Error {
+}
+function readTask(id) {
+    const p = taskPath(id);
+    if (!existsSync(p))
+        throw new TaskStateError(`task not found: ${id}`);
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+function writeTask(record) {
+    mkdirSync(tasksDir(), { recursive: true });
+    replaceFileAtomically(taskPath(record.task_id), JSON.stringify(record, null, 2) + '\n');
+}
+// ── Lifecycle transitions ───────────────────────────────────────────────
+const VALID_TRANSITIONS = {
+    backlog: ['provisioning', 'cancelled'],
+    provisioning: ['active', 'failed', 'cancelled'],
+    active: ['review', 'failed', 'cancelled'],
+    review: ['done', 'failed', 'cancelled'],
+    done: [],
+    cancelled: [],
+    failed: [],
+};
+function assertTransition(from, to) {
+    if (!VALID_TRANSITIONS[from].includes(to))
+        throw new TaskStateError(`cannot transition from '${from}' to '${to}'`);
+}
+function assertNoPendingTerminalIntent(task) {
+    if (task.terminal_intent?.status === 'pending') {
+        throw new TaskStateError(`task ${task.task_id} has a pending '${task.terminal_intent.kind}' terminal intent`);
+    }
+}
+export function createTask(input) {
+    const key = input.idempotency_key ?? randomUUID();
+    const existing = findByIdempotencyKey(key);
+    if (existing)
+        return existing;
+    const state = input.start === false ? 'backlog' : 'provisioning';
+    const record = {
+        task_id: generateTaskId(),
+        title: input.title,
+        brief: input.brief,
+        brief_file: input.brief_file,
+        state,
+        template: input.template,
+        no_room: input.no_room || undefined,
+        room_id: input.room_id,
+        member_roles: [],
+        origin: input.origin,
+        idempotency_key: key,
+        created_at: new Date().toISOString(),
+        started_at: state === 'provisioning' ? new Date().toISOString() : undefined,
+    };
+    writeTask(record);
+    return record;
+}
+export function getTask(id) { return readTask(id); }
+export function listTasks(filter) {
+    const dir = tasksDir();
+    if (!existsSync(dir))
+        return [];
+    const states = filter?.state
+        ? (Array.isArray(filter.state) ? filter.state : [filter.state])
+        : undefined;
+    const tasks = [];
+    for (const f of readdirSync(dir).filter(f => f.endsWith('.json'))) {
+        try {
+            const t = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+            if (!states || states.includes(t.state))
+                tasks.push(t);
+        }
+        catch { /* corrupt file, skip */ }
+    }
+    return tasks.sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+export function findByIdempotencyKey(key) {
+    return listTasks().find(t => t.idempotency_key === key);
+}
+export function startTask(id) {
+    const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
+    assertTransition(t.state, 'provisioning');
+    t.state = 'provisioning';
+    t.started_at = new Date().toISOString();
+    writeTask(t);
+    return t;
+}
+export function activateTask(id) {
+    const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
+    assertTransition(t.state, 'active');
+    t.state = 'active';
+    delete t.blocked;
+    writeTask(t);
+    return t;
+}
+export function blockTask(id, reason) {
+    const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
+    if (TASK_TERMINAL_STATES.includes(t.state))
+        throw new TaskStateError(`cannot block a '${t.state}' task`);
+    t.blocked = { reason, at: new Date().toISOString() };
+    writeTask(t);
+    return t;
+}
+export function unblockTask(id) {
+    const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
+    if (!t.blocked)
+        throw new TaskStateError('task is not blocked');
+    delete t.blocked;
+    writeTask(t);
+    return t;
+}
+export function reviewTask(id) {
+    const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
+    assertTransition(t.state, 'review');
+    t.state = 'review';
+    delete t.blocked;
+    writeTask(t);
+    return t;
+}
+export function completeTask(id, outcome) {
+    const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
+    assertTransition(t.state, 'done');
+    t.state = 'done';
+    t.ended_at = new Date().toISOString();
+    delete t.blocked;
+    if (outcome)
+        t.outcome = outcome;
+    writeTask(t);
+    return t;
+}
+export function cancelTask(id) {
+    const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
+    if (!TASK_CANCELLABLE_STATES.includes(t.state))
+        throw new TaskStateError(`cannot cancel a '${t.state}' task`);
+    t.state = 'cancelled';
+    t.ended_at = new Date().toISOString();
+    delete t.blocked;
+    writeTask(t);
+    return t;
+}
+function sameOutcome(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+/** Persist the first terminal request. Callers serialize this with the task-operation lock. */
+export function beginTaskTerminalIntent(id, input) {
+    const t = readTask(id);
+    const existing = t.terminal_intent;
+    if (existing) {
+        if (existing.kind !== input.kind || existing.room_id !== input.roomId
+            || !sameOutcome(existing.outcome, input.outcome)) {
+            throw new TaskStateError(`task ${id} already has a conflicting '${existing.kind}' terminal intent`);
+        }
+        return t;
+    }
+    if (TASK_TERMINAL_STATES.includes(t.state)) {
+        throw new TaskStateError(`task ${id} is already in terminal state '${t.state}'`);
+    }
+    if (input.kind === 'done' && t.state !== 'review') {
+        throw new TaskStateError(`cannot transition from '${t.state}' to 'done'`);
+    }
+    if (input.kind === 'cancelled' && !TASK_CANCELLABLE_STATES.includes(t.state)) {
+        throw new TaskStateError(`cannot cancel a '${t.state}' task`);
+    }
+    if (input.roomId !== undefined && t.room_id !== input.roomId) {
+        throw new TaskStateError(`task ${id} is not tied to room ${input.roomId}`);
+    }
+    t.terminal_intent = {
+        kind: input.kind,
+        status: 'pending',
+        room_id: input.roomId,
+        outcome: input.outcome,
+        accepted_at: new Date().toISOString(),
+    };
+    writeTask(t);
+    return t;
+}
+/** Record an actionable failure without claiming the requested terminal state. */
+export function setTaskTerminalIntentError(id, error, recoveryHint) {
+    const t = readTask(id);
+    if (!t.terminal_intent)
+        throw new TaskStateError(`task ${id} has no terminal intent`);
+    if (t.terminal_intent.status === 'settled')
+        return t;
+    t.terminal_intent.first_failure ??= error;
+    t.terminal_intent.first_recovery_hint ??= recoveryHint;
+    t.terminal_intent.error = error;
+    const previousErrorAt = Date.parse(t.terminal_intent.error_at ?? '');
+    t.terminal_intent.error_at = new Date(Math.max(Date.now(), Number.isFinite(previousErrorAt) ? previousErrorAt + 1 : 0)).toISOString();
+    t.terminal_intent.recovery_hint = recoveryHint;
+    writeTask(t);
+    return t;
+}
+/** Atomically publish the task terminal state and settled audit cursor. */
+export function finishTaskTerminalIntent(id) {
+    const t = readTask(id);
+    const intent = t.terminal_intent;
+    if (!intent)
+        throw new TaskStateError(`task ${id} has no terminal intent`);
+    if (intent.status === 'settled')
+        return t;
+    if (TASK_TERMINAL_STATES.includes(t.state)) {
+        throw new TaskStateError(`task ${id} reached terminal state '${t.state}' outside its intent`);
+    }
+    if (intent.kind === 'done')
+        assertTransition(t.state, 'done');
+    else if (!TASK_CANCELLABLE_STATES.includes(t.state)) {
+        throw new TaskStateError(`cannot cancel a '${t.state}' task`);
+    }
+    t.state = intent.kind;
+    t.ended_at = new Date().toISOString();
+    delete t.blocked;
+    if (intent.outcome)
+        t.outcome = intent.outcome;
+    intent.status = 'settled';
+    intent.settled_at = t.ended_at;
+    delete intent.error;
+    delete intent.error_at;
+    delete intent.recovery_hint;
+    writeTask(t);
+    return t;
+}
+export function failTask(id, error) {
+    const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
+    assertTransition(t.state, 'failed');
+    t.state = 'failed';
+    t.ended_at = new Date().toISOString();
+    t.outcome = { summary: error };
+    delete t.blocked;
+    writeTask(t);
+    return t;
+}
+export function updateTaskRoom(id, roomId, roomIdentityCid) {
+    const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
+    t.room_id = roomId;
+    t.room_identity_cid = roomIdentityCid;
+    writeTask(t);
+    return t;
+}
+export function updateTaskTemplate(id, template) {
+    const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
+    t.template = template;
+    writeTask(t);
+    return t;
+}
+export function updateTaskMembers(id, members) {
+    const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
+    t.member_roles = members;
+    writeTask(t);
+    return t;
+}
+export function deleteTask(id) {
+    const p = taskPath(id);
+    if (existsSync(p))
+        rmSync(p);
+}

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

@@ -0,0 +1,6 @@
+import type { TemplateDefinition, TemplateSnapshot } from './types.js';
+export declare const BUILTIN_TEMPLATES: readonly TemplateDefinition[];
+export declare function hashTemplate(t: TemplateDefinition): string;
+export declare function snapshotTemplate(t: TemplateDefinition): TemplateSnapshot;
+export declare function resolveTemplate(name: string, customTemplates: Record<string, TemplateDefinition>): TemplateDefinition | undefined;
+export declare function listTemplates(customTemplates: Record<string, TemplateDefinition>): TemplateDefinition[];

package/dist/rooms-tasks/templates.js

@@ -0,0 +1,94 @@
+import { createHash } from 'node:crypto';
+const TEAM = {
+    name: 'team',
+    version: 1,
+    builtin: true,
+    description: 'Phased task pipeline: Architect specifies, Developer implements, Tester verifies',
+    room: { quiet_membership: false, anonymous: false },
+    contract: [
+        'Architect produces a spec and posts it to the room. Work pauses for owner approval.',
+        'Developer implements per approved spec.',
+        'Tester verifies spec conformance and test coverage.',
+        'Completion requires tester sign-off.',
+    ].join('\n'),
+    members: [
+        { slot: 'architect', role: 'Architect', count: 1, role_ref: 'Architect' },
+        { slot: 'developer', role: 'Developer', count: 1, role_ref: 'Developer' },
+        { slot: 'tester', role: 'Tester', count: 1, role_ref: 'Tester' },
+    ],
+};
+const PAIR = {
+    name: 'pair',
+    version: 1,
+    builtin: true,
+    description: 'Deliberation pair: Secretary writes code, Critic reviews — every decision deliberated together',
+    room: { quiet_membership: false, anonymous: false },
+    contract: [
+        'Secretary and Critic deliberate every decision together before acting.',
+        'Secretary writes code; Critic reviews and challenges.',
+        'No material change lands without both agreeing.',
+        'Completion requires joint sign-off.',
+    ].join('\n'),
+    members: [
+        { slot: 'secretary', role: 'Secretary', count: 1, role_ref: 'Secretary' },
+        { slot: 'critic', role: 'Critic', count: 1, role_ref: 'Critic' },
+    ],
+};
+const SINGLE = {
+    name: 'single',
+    version: 1,
+    builtin: true,
+    description: 'Solo agent: one general-purpose agent works the task with owner oversight',
+    room: { quiet_membership: false, anonymous: false },
+    contract: [
+        'Agent works the task autonomously, consulting the owner when blocked.',
+        'Owner reviews and approves completion.',
+    ].join('\n'),
+    members: [
+        { slot: 'agent', role: 'Agent', count: 1, role_ref: 'Agent' },
+    ],
+};
+export const BUILTIN_TEMPLATES = [TEAM, PAIR, SINGLE];
+export function hashTemplate(t) {
+    const canonical = JSON.stringify({
+        name: t.name, version: t.version, description: t.description,
+        room: t.room, contract: t.contract, members: t.members,
+    });
+    return createHash('sha256').update(canonical).digest('hex');
+}
+export function snapshotTemplate(t) {
+    return { ...t, content_hash: hashTemplate(t) };
+}
+export function resolveTemplate(name, customTemplates) {
+    const atIdx = name.lastIndexOf('@');
+    const baseName = atIdx > 0 ? name.slice(0, atIdx) : name;
+    const versionStr = atIdx > 0 ? name.slice(atIdx + 1) : undefined;
+    const version = versionStr ? parseInt(versionStr, 10) : undefined;
+    const custom = customTemplates[baseName];
+    if (custom) {
+        if (version !== undefined && custom.version !== version)
+            return undefined;
+        return custom;
+    }
+    const builtin = BUILTIN_TEMPLATES.find(b => b.name === baseName);
+    if (builtin) {
+        if (version !== undefined && builtin.version !== version)
+            return undefined;
+        return builtin;
+    }
+    return undefined;
+}
+export function listTemplates(customTemplates) {
+    const result = [];
+    const overridden = new Set();
+    for (const [name, t] of Object.entries(customTemplates)) {
+        result.push({ ...t, name });
+        if (BUILTIN_TEMPLATES.some(b => b.name === name))
+            overridden.add(name);
+    }
+    for (const b of BUILTIN_TEMPLATES) {
+        if (!overridden.has(b.name))
+            result.push(b);
+    }
+    return result.sort((a, b) => a.name.localeCompare(b.name));
+}

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

@@ -0,0 +1,23 @@
+import { type RoomCloseDeps } from './close.js';
+import type { CoworkAdapter } from './cowork-adapter.js';
+import type { TaskOutcome, TaskRecord, TaskTerminalIntent } from './types.js';
+export interface TaskTerminalInput {
+    taskId: string;
+    kind: TaskTerminalIntent['kind'];
+    roomId?: string;
+    outcome?: TaskOutcome;
+}
+/** Persist first-wins terminal intent before any acknowledgement or close effect. */
+export declare function acceptTaskTerminalIntent(input: TaskTerminalInput): Promise<TaskRecord>;
+export interface SettleTaskTerminalDeps {
+    roomClose?: RoomCloseDeps;
+    afterRoomClosed?(): void | Promise<void>;
+}
+/** Close the recorded room, then atomically settle the persisted task intent. */
+export declare function settleTaskTerminalIntent(input: {
+    taskId: string;
+    cowork: Pick<CoworkAdapter, 'closeRoom'>;
+    deps?: SettleTaskTerminalDeps;
+}): Promise<TaskRecord>;
+/** Persist failure to launch an external settle worker under the same task lock. */
+export declare function recordTaskTerminalIntentError(taskId: string, error: string, recoveryHint: string): Promise<TaskRecord>;