@ours.network/fleet 0.19.0-nightly.9 → 1.0.1

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

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { replaceFileAtomically } from '../atomic-file.js';
 import { stateRoot } from '../paths.js';
@@ -43,6 +43,12 @@ export function getRoomRecord(id) {
         return undefined;
     }
 }
+/** Remove a terminal orchestration record from the live room inventory. */
+export function deleteRoomRecord(id) {
+    const path = roomPath(id);
+    if (existsSync(path))
+        rmSync(path);
+}
 export function listRoomRecords(filter) {
     const dir = roomsDir();
     if (!existsSync(dir))
@@ -99,6 +105,48 @@ export function updateMemberSeats(id, seats) {
     writeRoom(r);
     return r;
 }
+export function updateRoomRoleBriefing(id, role, definition) {
+    const r = readRoom(id);
+    r.role_briefings = { ...(r.role_briefings ?? {}), [role]: definition };
+    writeRoom(r);
+    return r;
+}
+export function updateRoomHistoryCursor(id, cursor) {
+    const r = readRoom(id);
+    if (!Number.isSafeInteger(cursor) || cursor < (r.history_cursor ?? 0))
+        throw new RoomStateError(`room ${id} history cursor cannot move backward`);
+    r.history_cursor = cursor;
+    writeRoom(r);
+    return r;
+}
+const LAUNCH_ORDER = [
+    'pending', 'intent', 'launched', 'stopped', 'failed',
+];
+const BRIEFING_ORDER = [
+    'pending', 'relay_queued', 'relay_failed', 'acknowledged',
+];
+export function updateMemberStartup(id, roleName, update) {
+    const r = readRoom(id);
+    const seat = r.member_seats.find(candidate => candidate.role_name === roleName);
+    if (!seat)
+        throw new RoomStateError(`room ${id} has no recorded member ${roleName}`);
+    if (update.launch && seat.launch
+        && LAUNCH_ORDER.indexOf(update.launch.state) < LAUNCH_ORDER.indexOf(seat.launch.state)
+        && !(seat.launch.state === 'stopped' && update.launch.state === 'intent')
+        && !(seat.launch.state === 'failed' && update.launch.state === 'intent')) {
+        throw new RoomStateError(`room ${id} member ${roleName} launch cannot move backward to ${update.launch.state}`);
+    }
+    if (update.briefing && seat.briefing
+        && BRIEFING_ORDER.indexOf(update.briefing.state) < BRIEFING_ORDER.indexOf(seat.briefing.state)) {
+        throw new RoomStateError(`room ${id} member ${roleName} briefing cannot move backward to ${update.briefing.state}`);
+    }
+    if (update.launch)
+        seat.launch = update.launch;
+    if (update.briefing)
+        seat.briefing = update.briefing;
+    writeRoom(r);
+    return r;
+}
 export function activateRoom(id) {
     const r = readRoom(id);
     r.state = 'active';
@@ -114,6 +162,106 @@ export function closeRoom(id) {
         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 !== 'closing' && r.state !== 'closed') || !r.close)
+        throw new RoomStateError(`room ${id} is not closing or awaiting deletion`);
+    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

@@ -1,4 +1,4 @@
-import type { TaskRecord, TaskState, TaskOrigin, TaskTemplateRef, TaskOutcome, TaskMemberRole } from './types.js';
+import type { TaskRecord, TaskState, TaskOrigin, TaskTemplateRef, TaskOutcome, TaskMemberRole, TaskTerminalIntent } from './types.js';
 export declare const tasksDir: () => string;
 export declare class TaskStateError extends Error {
 }
@@ -26,8 +26,19 @@ 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;
+/** Remove a completed task from Fleet's backlog. Missing tasks are an idempotent no-op. */
+export declare function deleteTask(id: string): boolean;

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

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { replaceFileAtomically } from '../atomic-file.js';
@@ -11,8 +11,18 @@ function generateTaskId() {
     const rand = randomUUID().replace(/-/g, '').slice(0, 8);
     return `${ts}${rand}`;
 }
+const TASK_ID_PATTERN = /^[0-9a-z]{9}[0-9a-f]{8}$/;
 export class TaskStateError extends Error {
 }
+function assertCanonicalTaskId(id) {
+    if (!TASK_ID_PATTERN.test(id)) {
+        throw new TaskStateError('invalid task ID: expected the canonical 17-character lowercase ID');
+    }
+}
+function isNotFoundError(error) {
+    return error instanceof Error && 'code' in error
+        && error.code === 'ENOENT';
+}
 function readTask(id) {
     const p = taskPath(id);
     if (!existsSync(p))
@@ -37,6 +47,11 @@ 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);
@@ -85,6 +100,7 @@ export function findByIdempotencyKey(key) {
 }
 export function startTask(id) {
     const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
     assertTransition(t.state, 'provisioning');
     t.state = 'provisioning';
     t.started_at = new Date().toISOString();
@@ -93,6 +109,7 @@ export function startTask(id) {
 }
 export function activateTask(id) {
     const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
     assertTransition(t.state, 'active');
     t.state = 'active';
     delete t.blocked;
@@ -101,6 +118,7 @@ export function activateTask(id) {
 }
 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() };
@@ -109,6 +127,7 @@ export function blockTask(id, reason) {
 }
 export function unblockTask(id) {
     const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
     if (!t.blocked)
         throw new TaskStateError('task is not blocked');
     delete t.blocked;
@@ -117,6 +136,7 @@ export function unblockTask(id) {
 }
 export function reviewTask(id) {
     const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
     assertTransition(t.state, 'review');
     t.state = 'review';
     delete t.blocked;
@@ -125,6 +145,7 @@ export function reviewTask(id) {
 }
 export function completeTask(id, outcome) {
     const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
     assertTransition(t.state, 'done');
     t.state = 'done';
     t.ended_at = new Date().toISOString();
@@ -136,6 +157,7 @@ export function completeTask(id, outcome) {
 }
 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';
@@ -144,8 +166,90 @@ export function cancelTask(id) {
     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();
@@ -156,6 +260,7 @@ export function failTask(id, error) {
 }
 export function updateTaskRoom(id, roomId, roomIdentityCid) {
     const t = readTask(id);
+    assertNoPendingTerminalIntent(t);
     t.room_id = roomId;
     t.room_identity_cid = roomIdentityCid;
     writeTask(t);
@@ -163,18 +268,41 @@ export function updateTaskRoom(id, roomId, roomIdentityCid) {
 }
 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;
 }
+/** Remove a completed task from Fleet's backlog. Missing tasks are an idempotent no-op. */
 export function deleteTask(id) {
+    assertCanonicalTaskId(id);
     const p = taskPath(id);
-    if (existsSync(p))
-        rmSync(p);
+    let task;
+    try {
+        task = JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch (error) {
+        if (isNotFoundError(error))
+            return false;
+        throw error;
+    }
+    if (task.state !== 'done') {
+        throw new TaskStateError(`cannot delete a '${task.state}' task; only 'done' tasks can be deleted`);
+    }
+    try {
+        unlinkSync(p);
+    }
+    catch (error) {
+        if (isNotFoundError(error))
+            return false;
+        throw error;
+    }
+    return true;
 }

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>;
+}
+/** Delete the recorded room, then atomically settle the persisted task intent. */
+export declare function settleTaskTerminalIntent(input: {
+    taskId: string;
+    cowork: Pick<CoworkAdapter, 'closeRoom' | 'deleteRoom'>;
+    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>;

package/dist/rooms-tasks/terminal.js

@@ -0,0 +1,56 @@
+import { join } from 'node:path';
+import { withFileLock } from '../atomic-file.js';
+import { stateRoot } from '../paths.js';
+import { deleteManagedRoom } from './close.js';
+import { beginTaskTerminalIntent, finishTaskTerminalIntent, getTask, setTaskTerminalIntentError, } from './task-state.js';
+import { getRoomRecord } from './room-state.js';
+const TASK_OPERATION_LOCK_STALE_MS = 10 * 60_000;
+function taskOperationLockPath(taskId) {
+    return join(stateRoot(), 'locks', 'task-terminal', encodeURIComponent(taskId));
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Persist first-wins terminal intent before any acknowledgement or close effect. */
+export function acceptTaskTerminalIntent(input) {
+    return withFileLock(taskOperationLockPath(input.taskId), () => {
+        const accepted = beginTaskTerminalIntent(input.taskId, input);
+        if (!input.roomId)
+            return finishTaskTerminalIntent(input.taskId);
+        return accepted;
+    }, {}, TASK_OPERATION_LOCK_STALE_MS);
+}
+/** Delete the recorded room, then atomically settle the persisted task intent. */
+export function settleTaskTerminalIntent(input) {
+    return withFileLock(taskOperationLockPath(input.taskId), async () => {
+        const current = getTask(input.taskId);
+        const intent = current.terminal_intent;
+        if (!intent)
+            throw new Error(`task ${input.taskId} has no accepted terminal intent`);
+        if (intent.status === 'settled')
+            return current;
+        try {
+            if (intent.room_id) {
+                if (getRoomRecord(intent.room_id)) {
+                    const deleted = await deleteManagedRoom({
+                        roomId: intent.room_id,
+                        cowork: input.cowork,
+                        deps: input.deps?.roomClose,
+                    });
+                    if (!deleted.deleted)
+                        throw new Error(`room ${intent.room_id} was not deleted`);
+                }
+                await input.deps?.afterRoomClosed?.();
+            }
+            return finishTaskTerminalIntent(input.taskId);
+        }
+        catch (error) {
+            setTaskTerminalIntentError(input.taskId, errorText(error), `Retry 'ours-fleet task recover ${input.taskId}'.`);
+            throw error;
+        }
+    }, {}, TASK_OPERATION_LOCK_STALE_MS);
+}
+/** Persist failure to launch an external settle worker under the same task lock. */
+export function recordTaskTerminalIntentError(taskId, error, recoveryHint) {
+    return withFileLock(taskOperationLockPath(taskId), () => setTaskTerminalIntentError(taskId, error, recoveryHint), {}, TASK_OPERATION_LOCK_STALE_MS);
+}

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

@@ -31,6 +31,19 @@ export interface TaskOutcome {
     summary: string;
     artifacts?: string[];
 }
+export interface TaskTerminalIntent {
+    kind: 'done' | 'cancelled';
+    status: 'pending' | 'settled';
+    room_id?: string;
+    outcome?: TaskOutcome;
+    accepted_at: string;
+    settled_at?: string;
+    error?: string;
+    error_at?: string;
+    recovery_hint?: string;
+    first_failure?: string;
+    first_recovery_hint?: string;
+}
 export interface TaskRecord {
     task_id: string;
     title: string;
@@ -49,22 +62,112 @@ export interface TaskRecord {
     started_at?: string;
     ended_at?: string;
     outcome?: TaskOutcome;
+    terminal_intent?: TaskTerminalIntent;
 }
 export type RoomOrchestrationState = 'provisioning' | 'active' | 'closing' | 'closed';
-export type SagaPhase = 'persist_intent' | 'create_room' | 'attach_owner' | 'create_members' | 'join_role_groups' | 'wait_seats' | 'launch_work' | 'activate' | 'completed' | 'failed';
+export type SagaPhase = 'persist_intent' | 'create_room' | 'attach_owner' | 'create_members' | 'configure_briefings' | 'join_role_groups' | 'wait_seats' | 'launch_work' | 'wait_briefing_acks' | 'activate' | 'completed' | 'failed';
 export interface SagaCursor {
     phase: SagaPhase;
     step_index: number;
     error?: string;
     recovery_hint?: string;
 }
-export type ProvisioningDetail = 'waiting_cowork' | 'waiting_owner_invite' | 'owner_cid_mismatch' | 'member_failed' | 'waiting_seats' | 'uncertain';
+export type ProvisioningDetail = 'waiting_cowork' | 'waiting_owner_invite' | 'owner_cid_mismatch' | 'member_failed' | 'waiting_seats' | 'waiting_briefing_delivery' | 'waiting_briefing_acks' | 'briefing_delivery_failed' | 'uncertain';
+export interface RoomRoleBriefingDefinition {
+    role: string;
+    text: string;
+    sha256: string;
+    version?: number;
+    state: 'pending' | 'configured' | 'failed';
+    attempts: number;
+    updated_at: string;
+    last_error?: string;
+}
+export interface RoomMemberLaunchState {
+    state: 'pending' | 'intent' | 'launched' | 'stopped' | 'failed';
+    attempt: number;
+    action_id?: string;
+    mission_sha256?: string;
+    launch_id?: string;
+    updated_at: string;
+    error?: string;
+}
+export interface RoomMemberBriefingState {
+    role: string;
+    state: 'pending' | 'relay_queued' | 'relay_failed' | 'acknowledged';
+    message_id?: string;
+    relay_intent_record_id?: string;
+    relay_result_record_id?: string;
+    relay_wire_id?: string;
+    checked_at?: string;
+    acknowledged_at?: string;
+    acknowledgement_message_id?: string;
+    acknowledgement_seq?: number;
+    rejected_ack_count: number;
+    last_rejected_ack_reason?: string;
+    last_rejected_ack_seq?: number;
+    last_processed_seq?: number;
+}
+export type RoomHistoryEvidence = {
+    kind: 'message';
+    seq: number;
+    record_id: string;
+    at: string;
+    message_id: string;
+    category: 'role_briefing' | 'chat';
+    author: {
+        identity: string;
+        display_name: string;
+        role: string;
+    };
+    text: string;
+    recipient_identities: string[];
+    briefing_role?: string;
+    briefing_version?: number;
+} | {
+    kind: 'relay_intent';
+    seq: number;
+    record_id: string;
+    at: string;
+    message_id: string;
+    recipient_identity: string;
+} | {
+    kind: 'relay_result';
+    seq: number;
+    record_id: string;
+    at: string;
+    intent_record_id: string;
+    message_id: string;
+    recipient_identity: string;
+    status: 'queued' | 'send_failed' | 'skipped_removed';
+    wire_id?: string;
+};
+export type MemberRetirementPhase = 'stop_requested' | 'liveness_absent' | 'archive_secured' | 'identity_absent';
+export interface MemberRetirement {
+    phase: MemberRetirementPhase;
+    launch_id: string;
+    updated_at: string;
+    archive_path?: string;
+}
+export type RoomClosePhase = 'retire_members' | 'close_cowork' | 'completed';
+export interface RoomCloseCursor {
+    phase: RoomClosePhase;
+    accepted_at: string;
+    error?: string;
+    error_at?: string;
+    recovery_hint?: string;
+    first_failure?: string;
+    first_recovery_hint?: string;
+}
 export interface RoomMemberSeat {
     role_name: string;
     identity_cid: string;
     slot: string;
     cowork_role: string;
     seat_state: 'pending' | 'active' | 'removed';
+    launch?: RoomMemberLaunchState;
+    briefing?: RoomMemberBriefingState;
+    retirement?: MemberRetirement;
 }
 export interface RoomOrchestrationRecord {
     room_id: string;
@@ -77,11 +180,14 @@ export interface RoomOrchestrationRecord {
     provisioning_detail?: ProvisioningDetail;
     owner_seat_cid?: string;
     owner_invite_fingerprint?: string;
+    role_briefings?: Record<string, RoomRoleBriefingDefinition>;
+    history_cursor?: number;
     member_seats: RoomMemberSeat[];
     state: RoomOrchestrationState;
     created_at: string;
     activated_at?: string;
     closed_at?: string;
+    close?: RoomCloseCursor;
 }
 export interface TemplateMemberSlot {
     slot: string;