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

package/dist/rooms-tasks/cli.js

@@ -0,0 +1,1102 @@
+import { readFileSync } from 'node:fs';
+import { loadConfig, ConfigError } from '../config.js';
+import { provisionMembers, getBinPath } from './provision.js';
+import { acceptManagedRoomClose, closeManagedRoom, recordManagedRoomCloseError, } from './close.js';
+import { acceptTaskTerminalIntent, recordTaskTerminalIntentError, settleTaskTerminalIntent, } from './terminal.js';
+import { launchFleetWorker } from './external-worker.js';
+import { resolveTemplate, listTemplates, snapshotTemplate, hashTemplate, } from './templates.js';
+import { createTask, getTask, listTasks, startTask, activateTask, blockTask, unblockTask, reviewTask, updateTaskRoom, updateTaskTemplate, TaskStateError, } from './task-state.js';
+import { createRoomRecord, getRoomRecord, listRoomRecords, advanceSaga, setOwnerSeat, setSagaError, activateRoom, RoomStateError, } from './room-state.js';
+import { createCoworkAdapter, CoworkProtocolError, CoworkUnavailableError } from './cowork-adapter.js';
+import { TASK_CANCELLABLE_STATES, TASK_TERMINAL_STATES } from './types.js';
+function die(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    process.stderr.write(`error: ${msg}\n`);
+    process.exit(1);
+}
+const PUBLIC_SETTLE_WAIT_MS = 60_000;
+const PUBLIC_SETTLE_POLL_MS = 100;
+const sleep = (ms) => new Promise(resolve => { setTimeout(resolve, ms); });
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function launchTaskSettleWorker(taskId, configPath) {
+    const previousErrorAt = getTask(taskId).terminal_intent?.error_at;
+    try {
+        await launchFleetWorker(['task', '_settle', taskId], `task-settle-${taskId}`, configPath);
+    }
+    catch (error) {
+        await recordTaskTerminalIntentError(taskId, errorText(error), `External settle worker failed to start. Retry task recover ${taskId}.`);
+        throw error;
+    }
+    const deadline = Date.now() + PUBLIC_SETTLE_WAIT_MS;
+    while (Date.now() < deadline) {
+        const task = getTask(taskId);
+        if (task.terminal_intent?.status === 'settled')
+            return { task, timedOut: false };
+        if (task.terminal_intent?.error_at !== previousErrorAt && task.terminal_intent?.error) {
+            throw new TaskStateError(task.terminal_intent.error);
+        }
+        await sleep(PUBLIC_SETTLE_POLL_MS);
+    }
+    return { task: getTask(taskId), timedOut: true };
+}
+async function launchRoomCloseWorker(roomId, configPath) {
+    const previousErrorAt = getRoomRecord(roomId)?.close?.error_at;
+    try {
+        await launchFleetWorker(['room', '_close', roomId], `room-close-${roomId}`, configPath);
+    }
+    catch (error) {
+        await recordManagedRoomCloseError(roomId, errorText(error), `External close worker failed to start. Retry room recover ${roomId}.`);
+        throw error;
+    }
+    const deadline = Date.now() + PUBLIC_SETTLE_WAIT_MS;
+    while (Date.now() < deadline) {
+        const room = getRoomRecord(roomId);
+        if (room.state === 'closed')
+            return { room, timedOut: false };
+        if (room.close?.error_at !== previousErrorAt && room.close?.error) {
+            throw new RoomStateError(room.close.error);
+        }
+        await sleep(PUBLIC_SETTLE_POLL_MS);
+    }
+    return { room: getRoomRecord(roomId), timedOut: true };
+}
+function loadCfg(opts) {
+    return loadConfig(opts.configuration);
+}
+function allTemplates(cfg) {
+    return cfg.roomTemplates ?? {};
+}
+function coworkFor(cfg) {
+    if (!cfg.rooms)
+        throw new ConfigError('rooms: configuration is required before creating or querying rooms');
+    return createCoworkAdapter({ configPath: cfg.rooms.cowork?.config });
+}
+function resolveRoomTemplate(cfg, name) {
+    if (!name)
+        return undefined;
+    const template = resolveTemplate(name, allTemplates(cfg));
+    if (!template)
+        throw new Error(`template not found: ${name}`);
+    return snapshotTemplate(template);
+}
+async function provisionRoom(cfg, input) {
+    const rooms = cfg.rooms;
+    if (!rooms)
+        throw new ConfigError('rooms: configuration is required');
+    const attachOwner = rooms.defaults?.attach_owner !== false;
+    if (attachOwner && !cfg.ownerInvite)
+        throw new ConfigError('rooms.owner: public_invite or public_invite_file is required when attach_owner is enabled');
+    const cowork = coworkFor(cfg);
+    const goal = input.goal?.trim() || input.name;
+    const briefing = input.brief?.trim() || input.template?.contract?.trim() || goal;
+    const created = await cowork.createRoom({
+        room_name: input.name,
+        goal,
+        briefing,
+        quiet_membership: input.template?.room?.quiet_membership,
+        anonymous: input.template?.room?.anonymous,
+    });
+    let record = createRoomRecord({
+        room_id: created.room_id,
+        room_name: input.name,
+        room_identity_cid: created.identity_cid,
+        task_id: input.taskId,
+        template_snapshot: input.template,
+    });
+    input.onCreated?.(record);
+    record = advanceSaga(record.room_id, 'create_room', 1);
+    if (attachOwner) {
+        try {
+            record = advanceSaga(record.room_id, 'attach_owner', 2);
+            const accepted = await cowork.acceptInvite(record.room_id, cfg.ownerInvite, {
+                role: rooms.owner.role,
+                expected_cid: rooms.owner.expected_cid,
+            });
+            record = setOwnerSeat(record.room_id, accepted.seat_cid, cfg.ownerInviteFingerprint ?? '');
+        }
+        catch (error) {
+            const mismatch = error instanceof CoworkProtocolError && /CID|expected/i.test(error.message);
+            setSagaError(record.room_id, error instanceof Error ? error.message : String(error), mismatch
+                ? 'Verify rooms.owner.expected_cid and rotate the configured invite if necessary.'
+                : 'Rotate rooms.owner.public_invite or public_invite_file, then run room recover.', mismatch ? 'owner_cid_mismatch' : 'waiting_owner_invite');
+            throw error;
+        }
+    }
+    record = advanceSaga(record.room_id, 'create_members', 3);
+    if (input.template && input.template.members.length > 0) {
+        record = await provisionMembers({
+            cfg,
+            cowork,
+            roomId: record.room_id,
+            taskId: input.taskId,
+            template: input.template,
+            binPath: getBinPath(),
+            brief: input.brief,
+            goal: input.goal,
+        });
+    }
+    else {
+        record = activateRoom(record.room_id);
+        if (input.taskId)
+            activateTask(input.taskId);
+    }
+    return record;
+}
+export function registerTemplateCommands(parent, cOpt) {
+    const templateCmd = parent.command('template').description('room template operations');
+    cOpt(templateCmd.command('list'))
+        .description('list available room templates')
+        .option('--json', 'JSON output')
+        .action((opts) => {
+        try {
+            const cfg = loadCfg(opts);
+            const templates = listTemplates(allTemplates(cfg));
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, templates }, null, 2));
+                return;
+            }
+            if (!templates.length) {
+                console.log('No templates configured.');
+                return;
+            }
+            for (const t of templates) {
+                const tag = t.builtin ? ' (built-in)' : '';
+                console.log(`${t.name}@${t.version}${tag}  ${t.description}`);
+            }
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(templateCmd.command('show <name>'))
+        .description('show template details')
+        .option('--json', 'JSON output')
+        .action((name, opts) => {
+        try {
+            const cfg = loadCfg(opts);
+            const t = resolveTemplate(name, allTemplates(cfg));
+            if (!t)
+                die(new Error(`template not found: ${name}`));
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, template: { ...t, content_hash: hashTemplate(t) } }, null, 2));
+                return;
+            }
+            console.log(`${t.name}@${t.version}  ${t.description}`);
+            if (t.contract)
+                console.log(`\nContract:\n${t.contract}`);
+            console.log(`\nMembers:`);
+            for (const m of t.members)
+                console.log(`  ${m.slot}: ${m.count}× ${m.role} (ref: ${m.role_ref})`);
+            console.log(`\nContent hash: ${hashTemplate(t)}`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(templateCmd.command('validate'))
+        .description('validate all room templates')
+        .option('--json', 'JSON output')
+        .action((opts) => {
+        try {
+            const cfg = loadCfg(opts);
+            const templates = listTemplates(allTemplates(cfg));
+            const problems = [];
+            for (const t of templates) {
+                const issues = [];
+                for (const m of t.members) {
+                    if (!cfg.roles.some(r => r.name === m.role_ref))
+                        issues.push(`member ${m.slot}: role_ref '${m.role_ref}' not found in fleet roles`);
+                }
+                if (issues.length)
+                    problems.push({ template: `${t.name}@${t.version}`, issues });
+            }
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, valid: !problems.length, problems }, null, 2));
+                return;
+            }
+            if (!problems.length) {
+                console.log('All templates valid.');
+                return;
+            }
+            for (const p of problems) {
+                console.log(`${p.template}:`);
+                for (const i of p.issues)
+                    console.log(`  - ${i}`);
+            }
+            process.exit(1);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+}
+export function registerTaskCommands(parent, cOpt) {
+    const taskCmd = parent.command('task').description('task lifecycle operations');
+    cOpt(taskCmd.command('create'))
+        .description('create a new task')
+        .requiredOption('--title <title>', 'task title')
+        .option('--template <name>', 'room template')
+        .option('--brief <text>', 'task brief')
+        .option('--brief-file <path>', 'task brief from file')
+        .option('--backlog', 'create in backlog (do not start immediately)')
+        .option('--no-room', 'create task without a room')
+        .option('--idempotency-key <key>', 'idempotency key')
+        .option('--json', 'JSON output')
+        .action(async (opts) => {
+        try {
+            const cfg = loadCfg(opts);
+            let templateRef;
+            if (opts.template) {
+                const t = resolveTemplate(opts.template, allTemplates(cfg));
+                if (!t)
+                    die(new Error(`template not found: ${opts.template}`));
+                const snap = snapshotTemplate(t);
+                templateRef = { name: snap.name, version: snap.version, content_hash: snap.content_hash };
+            }
+            else if (opts.room !== false) {
+                const defaultTpl = cfg.tasks?.default_room_template ?? cfg.rooms?.defaults?.template ?? 'team';
+                const t = resolveTemplate(defaultTpl, allTemplates(cfg));
+                if (t) {
+                    const snap = snapshotTemplate(t);
+                    templateRef = { name: snap.name, version: snap.version, content_hash: snap.content_hash };
+                }
+            }
+            let brief = opts.brief;
+            if (opts.briefFile) {
+                brief = readFileSync(opts.briefFile, 'utf8');
+            }
+            const origin = { type: 'cli' };
+            let record = createTask({
+                title: opts.title,
+                brief,
+                brief_file: opts.briefFile,
+                template: templateRef,
+                origin,
+                idempotency_key: opts.idempotencyKey,
+                start: !opts.backlog,
+            });
+            if (!opts.backlog && opts.room !== false && templateRef && !record.room_id) {
+                const template = resolveRoomTemplate(cfg, templateRef.name);
+                try {
+                    await provisionRoom(cfg, {
+                        name: opts.title,
+                        goal: opts.title,
+                        brief,
+                        template,
+                        taskId: record.task_id,
+                        onCreated: room => {
+                            record = updateTaskRoom(record.task_id, room.room_id, room.room_identity_cid);
+                        },
+                    });
+                    record = getTask(record.task_id);
+                }
+                catch (error) {
+                    if (error instanceof CoworkUnavailableError) {
+                        blockTask(record.task_id, 'Cowork management socket is unavailable');
+                    }
+                    throw error;
+                }
+            }
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, task: record }, null, 2));
+                return;
+            }
+            console.log(`Task ${record.task_id} created · ${record.state}`);
+            if (templateRef)
+                console.log(`Template: ${templateRef.name}@${templateRef.version}`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(taskCmd.command('list'))
+        .description('list tasks')
+        .option('--state <state>', 'filter by state (backlog|active|provisioning|review|done|cancelled|failed|all)')
+        .option('--json', 'JSON output')
+        .action((opts) => {
+        try {
+            let stateFilter;
+            if (opts.state && opts.state !== 'all') {
+                stateFilter = opts.state;
+            }
+            const tasks = listTasks(stateFilter ? { state: stateFilter } : undefined);
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, tasks }, null, 2));
+                return;
+            }
+            if (!tasks.length) {
+                console.log('No tasks.');
+                return;
+            }
+            for (const t of tasks) {
+                const blocked = t.blocked ? ` [BLOCKED: ${t.blocked.reason}]` : '';
+                console.log(`${t.task_id}  ${t.state}${blocked}  ${t.title}`);
+            }
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    taskCmd.command('show <id>')
+        .description('show task details')
+        .option('--json', 'JSON output')
+        .action((id, opts) => {
+        try {
+            const t = getTask(id);
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, task: t }, null, 2));
+                return;
+            }
+            console.log(`Task: ${t.task_id}`);
+            console.log(`Title: ${t.title}`);
+            console.log(`State: ${t.state}${t.blocked ? ` [BLOCKED: ${t.blocked.reason}]` : ''}`);
+            if (t.template)
+                console.log(`Template: ${t.template.name}@${t.template.version}`);
+            if (t.room_id)
+                console.log(`Room: ${t.room_id}`);
+            if (t.room_identity_cid)
+                console.log(`Room CID: ${t.room_identity_cid}`);
+            if (t.member_roles.length) {
+                console.log('Members:');
+                for (const m of t.member_roles)
+                    console.log(`  ${m.name} (${m.cowork_role}) ${m.identity_cid}`);
+            }
+            console.log(`Origin: ${t.origin.type}`);
+            console.log(`Created: ${t.created_at}`);
+            if (t.started_at)
+                console.log(`Started: ${t.started_at}`);
+            if (t.ended_at)
+                console.log(`Ended: ${t.ended_at}`);
+            if (t.outcome)
+                console.log(`Outcome: ${t.outcome.summary}`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(taskCmd.command('start <id>'))
+        .description('start a backlog task')
+        .option('--json', 'JSON output')
+        .action(async (id, opts) => {
+        try {
+            const cfg = loadCfg(opts);
+            let t = startTask(id);
+            if (t.template && !t.room_id) {
+                const template = resolveRoomTemplate(cfg, t.template.name);
+                if (!template || template.content_hash !== t.template.content_hash)
+                    throw new Error(`task template snapshot no longer matches ${t.template.name}@${t.template.version}`);
+                await provisionRoom(cfg, {
+                    name: t.title,
+                    goal: t.title,
+                    brief: t.brief,
+                    template,
+                    taskId: t.task_id,
+                    onCreated: room => {
+                        t = updateTaskRoom(t.task_id, room.room_id, room.room_identity_cid);
+                    },
+                });
+                t = getTask(t.task_id);
+            }
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, task: t }, null, 2));
+                return;
+            }
+            console.log(`Task ${t.task_id} · provisioning`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    taskCmd.command('block <id>')
+        .description('mark a task as blocked')
+        .requiredOption('--reason <reason>', 'blocking reason')
+        .option('--json', 'JSON output')
+        .action((id, opts) => {
+        try {
+            const t = blockTask(id, opts.reason);
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, task: t }, null, 2));
+                return;
+            }
+            console.log(`Task ${t.task_id} · blocked: ${opts.reason}`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    taskCmd.command('unblock <id>')
+        .description('unblock a task')
+        .option('--json', 'JSON output')
+        .action((id, opts) => {
+        try {
+            const t = unblockTask(id);
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, task: t }, null, 2));
+                return;
+            }
+            console.log(`Task ${t.task_id} · unblocked`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    taskCmd.command('review <id>')
+        .description('move a task to review')
+        .option('--json', 'JSON output')
+        .action((id, opts) => {
+        try {
+            const t = reviewTask(id);
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, task: t }, null, 2));
+                return;
+            }
+            console.log(`Task ${t.task_id} · review`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(taskCmd.command('done <id>'))
+        .description('complete a task')
+        .option('--summary <text>', 'completion summary')
+        .option('--summary-file <path>', 'completion summary from file')
+        .option('--json', 'JSON output')
+        .action(async (id, opts) => {
+        try {
+            let summary = opts.summary;
+            if (opts.summaryFile)
+                summary = readFileSync(opts.summaryFile, 'utf8');
+            const outcome = summary ? { summary } : undefined;
+            const current = getTask(id);
+            if (TASK_TERMINAL_STATES.includes(current.state))
+                throw new TaskStateError(`task ${id} is already in terminal state '${current.state}'`);
+            if (current.state !== 'review')
+                throw new TaskStateError(`cannot transition from '${current.state}' to 'done'`);
+            let roomId;
+            let cfg;
+            if (current.room_id) {
+                cfg = loadCfg(opts);
+                const shouldClose = cfg.tasks?.close_room_on_done
+                    ?? cfg.rooms?.defaults?.close_when_task_done
+                    ?? false;
+                if (shouldClose)
+                    roomId = current.room_id;
+            }
+            await acceptTaskTerminalIntent({ taskId: id, kind: 'done', roomId, outcome });
+            const settled = roomId
+                ? await launchTaskSettleWorker(id, opts.configuration)
+                : { task: getTask(id), timedOut: false };
+            const t = settled.task;
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, task: t }, null, 2));
+                return;
+            }
+            if (settled.timedOut) {
+                console.log(`Task ${t.task_id} · ${t.state} (terminal intent accepted/pending; run task recover ${id})`);
+                return;
+            }
+            console.log(`Task ${t.task_id} · done`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(taskCmd.command('cancel <id> <confirm-id>'))
+        .description('cancel a task (requires ID twice for confirmation)')
+        .option('--json', 'JSON output')
+        .action(async (id, confirmId, opts) => {
+        try {
+            if (id !== confirmId)
+                die(new Error('confirmation ID must match task ID'));
+            const current = getTask(id);
+            if (!TASK_CANCELLABLE_STATES.includes(current.state))
+                throw new TaskStateError(`cannot cancel a '${current.state}' task`);
+            if (current.room_id)
+                loadCfg(opts);
+            await acceptTaskTerminalIntent({
+                taskId: id, kind: 'cancelled', roomId: current.room_id,
+            });
+            const settled = current.room_id
+                ? await launchTaskSettleWorker(id, opts.configuration)
+                : { task: getTask(id), timedOut: false };
+            const t = settled.task;
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, task: t }, null, 2));
+                return;
+            }
+            if (settled.timedOut) {
+                console.log(`Task ${t.task_id} · ${t.state} (terminal intent accepted/pending; run task recover ${id})`);
+                return;
+            }
+            console.log(`Task ${t.task_id} · cancelled`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(taskCmd.command('recover <id>'))
+        .description('attempt to recover a stuck task')
+        .option('--json', 'JSON output')
+        .action(async (id, opts) => {
+        try {
+            const cfg = loadCfg(opts);
+            let t = getTask(id);
+            let terminalTimedOut = false;
+            if (t.terminal_intent?.status === 'pending') {
+                const settled = await launchTaskSettleWorker(id, opts.configuration);
+                t = settled.task;
+                terminalTimedOut = settled.timedOut;
+            }
+            const room = t.room_id ? getRoomRecord(t.room_id) : undefined;
+            const result = {
+                task: t,
+                room: room ?? null,
+                recovery_actions: [],
+            };
+            if (terminalTimedOut) {
+                result.recovery_actions.push(`Terminal intent remains pending — retry task recover ${id}`);
+            }
+            if (t.state === 'provisioning' && room) {
+                if (room.provisioning_detail === 'waiting_cowork')
+                    result.recovery_actions.push('Cowork management socket unreachable — check ours-cowork service');
+                if (room.provisioning_detail === 'waiting_owner_invite')
+                    result.recovery_actions.push('Owner invite invalid or expired — rotate rooms.owner.public_invite in config');
+                if (room.provisioning_detail === 'owner_cid_mismatch')
+                    result.recovery_actions.push('Owner CID mismatch — verify rooms.owner.expected_cid matches Messenger identity');
+                if (room.provisioning_detail === 'member_failed')
+                    result.recovery_actions.push(`Member creation failed at saga step ${room.saga.step_index} — inspect and retry`);
+                const resumable = ['create_members', 'join_role_groups', 'wait_seats', 'launch_work', 'activate'];
+                if (resumable.includes(room.saga.phase)) {
+                    const template = t.template ? resolveRoomTemplate(cfg, t.template.name) : undefined;
+                    if (template) {
+                        try {
+                            await provisionMembers({
+                                cfg,
+                                cowork: coworkFor(cfg),
+                                roomId: room.room_id,
+                                taskId: t.task_id,
+                                template,
+                                binPath: getBinPath(),
+                                brief: t.brief,
+                                goal: t.title,
+                            });
+                            result.recovery_actions.push('Provisioning resumed successfully');
+                        }
+                        catch (error) {
+                            result.recovery_actions.push(`Resume failed: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                }
+            }
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, ...result }, null, 2));
+                return;
+            }
+            console.log(`Task ${t.task_id} · ${t.state}`);
+            if (room)
+                console.log(`Room ${room.room_id} · ${room.state} · saga: ${room.saga.phase}`);
+            if (result.recovery_actions.length) {
+                console.log('Recovery actions:');
+                for (const a of result.recovery_actions)
+                    console.log(`  - ${a}`);
+            }
+            else {
+                console.log('No automated recovery actions available.');
+            }
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(taskCmd.command('_settle <id>', { hidden: true }))
+        .description('internal: settle a previously accepted task terminal intent')
+        .option('--json', 'JSON output')
+        .action(async (id, opts) => {
+        try {
+            const cfg = loadCfg(opts);
+            const t = await settleTaskTerminalIntent({ taskId: id, cowork: coworkFor(cfg) });
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, task: t }, null, 2));
+                return;
+            }
+            console.log(`Task ${t.task_id} · ${t.state}`);
+        }
+        catch (e) {
+            await recordTaskTerminalIntentError(id, errorText(e), `External settle worker failed. Retry task recover ${id}.`).catch(() => { });
+            die(e);
+        }
+    });
+    cOpt(taskCmd.command('work <id>'))
+        .description('ensure a task has a room and agents running')
+        .option('--template <name>', 'room template')
+        .option('--json', 'JSON output')
+        .action(async (id, opts) => {
+        try {
+            const cfg = loadCfg(opts);
+            let t = getTask(id);
+            if (TASK_TERMINAL_STATES.includes(t.state))
+                die(new Error(`task ${id} is in terminal state '${t.state}'`));
+            if (t.state === 'active' && t.room_id) {
+                // An explicit --template must agree with the room the task already
+                // runs in; a conflicting override is an error, not a silent no-op.
+                if (opts.template) {
+                    const override = resolveTemplate(opts.template, allTemplates(cfg));
+                    if (!override)
+                        die(new Error(`template not found: ${opts.template}`));
+                    const overrideSnap = snapshotTemplate(override);
+                    const roomSnap = getRoomRecord(t.room_id)?.template_snapshot ?? t.template;
+                    if (roomSnap && (roomSnap.name !== overrideSnap.name || roomSnap.content_hash !== overrideSnap.content_hash))
+                        die(new Error(`template ${overrideSnap.name}@${overrideSnap.version} does not match room ${t.room_id}'s provisioned template ${roomSnap.name}@${roomSnap.version}`));
+                }
+                if (opts.json) {
+                    console.log(JSON.stringify({ schema_version: 1, task: t, status: 'already_active' }, null, 2));
+                    return;
+                }
+                console.log('Task already has an active room');
+                return;
+            }
+            // Select and validate the template snapshot before any state change or
+            // provisioning. An explicit --template re-pins the task; a stored ref
+            // must still match its snapshot (same contract as `task start`).
+            const templateName = opts.template
+                ?? t.template?.name
+                ?? cfg.tasks?.default_room_template
+                ?? cfg.rooms?.defaults?.template
+                ?? 'single';
+            const resolved = resolveTemplate(templateName, allTemplates(cfg));
+            if (!resolved)
+                die(new Error(`template not found: ${templateName}`));
+            const snap = snapshotTemplate(resolved);
+            if (!opts.template && t.template && snap.content_hash !== t.template.content_hash)
+                die(new Error(`task template snapshot no longer matches ${t.template.name}@${t.template.version}`));
+            // A provisioned room is pinned to its snapshot: never resume or re-pin
+            // an existing room under a different template.
+            if (t.room_id) {
+                const roomSnap = getRoomRecord(t.room_id)?.template_snapshot ?? t.template;
+                if (roomSnap && (roomSnap.name !== snap.name || roomSnap.content_hash !== snap.content_hash))
+                    die(new Error(`template ${snap.name}@${snap.version} does not match room ${t.room_id}'s provisioned template ${roomSnap.name}@${roomSnap.version}`));
+            }
+            let templateRef = t.template;
+            if (!templateRef || templateRef.name !== snap.name || templateRef.content_hash !== snap.content_hash) {
+                templateRef = { name: snap.name, version: snap.version, content_hash: snap.content_hash };
+                t = updateTaskTemplate(t.task_id, templateRef);
+            }
+            if (t.state === 'backlog') {
+                t = startTask(id);
+            }
+            if (!t.room_id) {
+                try {
+                    await provisionRoom(cfg, {
+                        name: t.title,
+                        goal: t.title,
+                        brief: t.brief,
+                        template: snap,
+                        taskId: t.task_id,
+                        onCreated: room => {
+                            t = updateTaskRoom(t.task_id, room.room_id, room.room_identity_cid);
+                        },
+                    });
+                    t = getTask(t.task_id);
+                }
+                catch (error) {
+                    if (error instanceof CoworkUnavailableError) {
+                        blockTask(t.task_id, 'Cowork management socket is unavailable');
+                    }
+                    throw error;
+                }
+            }
+            else if (t.state === 'provisioning') {
+                // The task already has a room mid-provisioning (e.g. seats were still
+                // pending on the last run). Resume it exactly as `task recover` does.
+                const room = getRoomRecord(t.room_id);
+                const resumable = ['create_members', 'join_role_groups', 'wait_seats', 'launch_work', 'activate'];
+                if (room && resumable.includes(room.saga.phase)) {
+                    try {
+                        await provisionMembers({
+                            cfg,
+                            cowork: coworkFor(cfg),
+                            roomId: room.room_id,
+                            taskId: t.task_id,
+                            template: snap,
+                            binPath: getBinPath(),
+                            brief: t.brief,
+                            goal: t.title,
+                        });
+                    }
+                    catch (error) {
+                        if (error instanceof CoworkUnavailableError) {
+                            blockTask(t.task_id, 'Cowork management socket is unavailable');
+                        }
+                        throw error;
+                    }
+                    t = getTask(t.task_id);
+                }
+                else {
+                    die(new Error(`task ${id} has room ${t.room_id} in a non-resumable state — run 'task recover ${id}'`));
+                }
+            }
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, task: t }, null, 2));
+                return;
+            }
+            console.log(`Task ${t.task_id} · ${t.state}`);
+            if (templateRef)
+                console.log(`Template: ${templateRef.name}@${templateRef.version}`);
+            if (t.room_id)
+                console.log(`Room: ${t.room_id}`);
+            if (t.member_roles.length) {
+                console.log('Agents:');
+                for (const m of t.member_roles)
+                    console.log(`  ${m.name} (${m.cowork_role})`);
+            }
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(taskCmd.command('finish <id>'))
+        .description('finish a task: transition to done and close its room')
+        .option('--summary <text>', 'completion summary')
+        .option('--summary-file <path>', 'completion summary from file')
+        .option('--json', 'JSON output')
+        .action(async (id, opts) => {
+        try {
+            let summary = opts.summary;
+            if (opts.summaryFile)
+                summary = readFileSync(opts.summaryFile, 'utf8');
+            const outcome = summary ? { summary } : undefined;
+            let t = getTask(id);
+            if (TASK_TERMINAL_STATES.includes(t.state))
+                die(new Error(`task ${id} is already in terminal state '${t.state}'`));
+            if (t.state === 'active') {
+                reviewTask(id);
+            }
+            if (t.room_id)
+                loadCfg(opts); // validate configuration before durable acceptance
+            await acceptTaskTerminalIntent({ taskId: id, kind: 'done', roomId: t.room_id, outcome });
+            const settled = t.room_id
+                ? await launchTaskSettleWorker(id, opts.configuration)
+                : { task: getTask(id), timedOut: false };
+            t = settled.task;
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, task: t }, null, 2));
+                return;
+            }
+            if (settled.timedOut) {
+                console.log(`Task ${t.task_id} · ${t.state} (terminal intent accepted/pending; run task recover ${id})`);
+                return;
+            }
+            console.log(`Task ${t.task_id} · done`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+}
+export function registerRoomCommands(parent, cOpt) {
+    const roomCmd = parent.command('room').description('room orchestration operations');
+    cOpt(roomCmd.command('create'))
+        .description('create a standalone room')
+        .requiredOption('--name <name>', 'room name')
+        .option('--template <name>', 'room template')
+        .option('--goal <text>', 'room goal')
+        .option('--brief <text>', 'room briefing')
+        .option('--brief-file <path>', 'room briefing from file')
+        .option('--json', 'JSON output')
+        .action(async (opts) => {
+        try {
+            const cfg = loadCfg(opts);
+            let brief = opts.brief;
+            if (opts.briefFile)
+                brief = readFileSync(opts.briefFile, 'utf8');
+            let templateSnapshot;
+            if (opts.template) {
+                const t = resolveTemplate(opts.template, allTemplates(cfg));
+                if (!t)
+                    die(new Error(`template not found: ${opts.template}`));
+                templateSnapshot = snapshotTemplate(t);
+            }
+            const record = await provisionRoom(cfg, {
+                name: opts.name,
+                goal: opts.goal,
+                brief,
+                template: templateSnapshot,
+            });
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, room: record }, null, 2));
+                return;
+            }
+            console.log(`Room ${record.room_id} created · ${record.state}`);
+            if (templateSnapshot)
+                console.log(`Template: ${templateSnapshot.name}@${templateSnapshot.version}`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(roomCmd.command('list'))
+        .description('list rooms')
+        .option('--state <state>', 'filter by state (active|provisioning|closing|closed|all)')
+        .option('--json', 'JSON output')
+        .action(async (opts) => {
+        try {
+            const cfg = loadCfg(opts);
+            let stateFilter;
+            if (opts.state && opts.state !== 'all') {
+                stateFilter = opts.state;
+            }
+            const local = new Map(listRoomRecords().map(room => [room.room_id, room]));
+            const coworkRooms = await coworkFor(cfg).listRooms();
+            const rooms = coworkRooms
+                .filter(room => !stateFilter || room.state === stateFilter)
+                .map(room => ({ ...room, orchestration: local.get(room.room_id) ?? null }));
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, rooms }, null, 2));
+                return;
+            }
+            if (!rooms.length) {
+                console.log('No rooms.');
+                return;
+            }
+            for (const r of rooms)
+                console.log(`${r.room_id}  ${r.state}  ${r.room_name}${r.orchestration?.task_id ? ` (task: ${r.orchestration.task_id})` : ''}`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(roomCmd.command('show <id>'))
+        .description('show room details')
+        .option('--json', 'JSON output')
+        .action(async (id, opts) => {
+        try {
+            const cfg = loadCfg(opts);
+            const cowork = await coworkFor(cfg).getRoom(id);
+            if (!cowork)
+                die(new Error(`room not found: ${id}`));
+            const r = getRoomRecord(id);
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, room: cowork, orchestration: r ?? null }, null, 2));
+                return;
+            }
+            console.log(`Room: ${cowork.room_id}`);
+            console.log(`Name: ${cowork.room_name}`);
+            console.log(`State: ${cowork.state}`);
+            console.log(`Identity CID: ${cowork.identity_cid}`);
+            if (r?.task_id)
+                console.log(`Task: ${r.task_id}`);
+            if (r)
+                console.log(`Saga: ${r.saga.phase} (step ${r.saga.step_index})`);
+            if (r?.provisioning_detail)
+                console.log(`Detail: ${r.provisioning_detail}`);
+            if (r?.saga.error)
+                console.log(`Error: ${r.saga.error}`);
+            if (cowork.seats.length) {
+                console.log('Members:');
+                for (const s of cowork.seats)
+                    console.log(`  ${s.identity_cid} (${s.role}) ${s.seat_state}`);
+            }
+            if (r)
+                console.log(`Tracked by Fleet since: ${r.created_at}`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(roomCmd.command('open <id>'))
+        .description('open room in Cowork local console')
+        .option('--json', 'JSON output')
+        .action(async (id, opts) => {
+        try {
+            const cfg = loadCfg(opts);
+            const room = await coworkFor(cfg).getRoom(id);
+            if (!room)
+                die(new Error(`room not found: ${id}`));
+            const url = `http://localhost:4460/room/${id}`;
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, room_id: id, url, room_name: room.room_name }, null, 2));
+                return;
+            }
+            console.log(`Room ${id} — ${room.room_name}`);
+            console.log(`Local console: ${url}`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(roomCmd.command('members <id>'))
+        .description('show room members')
+        .option('--json', 'JSON output')
+        .action(async (id, opts) => {
+        try {
+            const cfg = loadCfg(opts);
+            const r = getRoomRecord(id);
+            const members = await coworkFor(cfg).getSeats(id);
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    schema_version: 1,
+                    room_id: id,
+                    members,
+                    owner_seat_cid: r?.owner_seat_cid ?? null,
+                }, null, 2));
+                return;
+            }
+            console.log(`Room ${id}${r ? ` — ${r.room_name}` : ''}`);
+            if (r?.owner_seat_cid)
+                console.log(`Owner: ${r.owner_seat_cid}`);
+            if (!members.length) {
+                console.log('No members.');
+                return;
+            }
+            for (const s of members)
+                console.log(`  ${s.identity_cid} (${s.role}) ${s.seat_state}`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(roomCmd.command('close <id> <confirm-id>'))
+        .description('close a room (requires ID twice for confirmation)')
+        .option('--json', 'JSON output')
+        .action(async (id, confirmId, opts) => {
+        try {
+            if (id !== confirmId)
+                die(new Error('confirmation ID must match room ID'));
+            coworkFor(loadCfg(opts));
+            const existing = getRoomRecord(id);
+            if (!existing)
+                throw new Error(`room not found in Fleet orchestration: ${id}`);
+            await acceptManagedRoomClose(id);
+            const settled = await launchRoomCloseWorker(id, opts.configuration);
+            const r = settled.room;
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, room_id: id, state: r.state, orchestration: r }, null, 2));
+                return;
+            }
+            if (settled.timedOut) {
+                console.log(`Room ${id} · closing (accepted/pending; run room recover ${id})`);
+                return;
+            }
+            console.log(`Room ${id} · closed`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(roomCmd.command('recover <id>'))
+        .description('attempt to recover a stuck room')
+        .option('--json', 'JSON output')
+        .action(async (id, opts) => {
+        try {
+            const cfg = loadCfg(opts);
+            const adapter = coworkFor(cfg);
+            let r = getRoomRecord(id);
+            if (r?.state === 'closing') {
+                const settled = await launchRoomCloseWorker(id, opts.configuration);
+                r = settled.room;
+                const cowork = r.state === 'closed' ? await adapter.getRoom(id) : undefined;
+                if (opts.json) {
+                    console.log(JSON.stringify({
+                        schema_version: 1, room: cowork ?? null, orchestration: r,
+                        recovery_actions: [settled.timedOut
+                                ? `Closing remains pending — retry room recover ${id}`
+                                : 'Closing saga resumed successfully'],
+                    }, null, 2));
+                    return;
+                }
+                console.log(`Room ${id} · ${r.state} · close: ${r.close?.phase ?? 'unknown'}`);
+                return;
+            }
+            const cowork = await adapter.recoverRoom(id);
+            r = getRoomRecord(id);
+            if (r && !r.owner_seat_cid
+                && (r.provisioning_detail === 'waiting_owner_invite'
+                    || r.provisioning_detail === 'owner_cid_mismatch')) {
+                const expected = cfg.rooms.owner.expected_cid.toLowerCase();
+                const existing = (await adapter.getSeats(id))
+                    .find(seat => seat.identity_cid.toLowerCase() === expected && seat.seat_state !== 'removed');
+                if (!existing && !cfg.ownerInvite)
+                    throw new ConfigError('rooms.owner: configure public_invite or public_invite_file before recovery');
+                let acceptedCid = existing?.identity_cid;
+                if (!acceptedCid) {
+                    const accepted = await adapter.acceptInvite(id, cfg.ownerInvite, {
+                        role: cfg.rooms.owner.role,
+                        expected_cid: cfg.rooms.owner.expected_cid,
+                    });
+                    acceptedCid = accepted.seat_cid;
+                }
+                setOwnerSeat(id, acceptedCid, cfg.ownerInviteFingerprint ?? '');
+                r = advanceSaga(id, 'create_members', 3);
+            }
+            const actions = [];
+            if (r?.saga.error)
+                actions.push(`Last error: ${r.saga.error}`);
+            if (r?.saga.recovery_hint)
+                actions.push(r.saga.recovery_hint);
+            if (r?.provisioning_detail === 'waiting_cowork')
+                actions.push('Check ours-cowork service status');
+            if (r?.provisioning_detail === 'waiting_owner_invite')
+                actions.push('Rotate rooms.owner.public_invite in config, then re-run recover');
+            if (r && r.state === 'provisioning') {
+                const resumable = ['create_members', 'join_role_groups', 'wait_seats', 'launch_work', 'activate'];
+                if (resumable.includes(r.saga.phase) && r.template_snapshot) {
+                    try {
+                        const template = resolveRoomTemplate(cfg, r.template_snapshot.name);
+                        if (template) {
+                            await provisionMembers({
+                                cfg,
+                                cowork: adapter,
+                                roomId: r.room_id,
+                                taskId: r.task_id,
+                                template,
+                                binPath: getBinPath(),
+                                goal: r.room_name,
+                            });
+                            r = getRoomRecord(id);
+                            actions.push('Provisioning resumed successfully');
+                        }
+                    }
+                    catch (error) {
+                        actions.push(`Resume failed: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+            }
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, room: cowork, orchestration: r ?? null, recovery_actions: actions }, null, 2));
+                return;
+            }
+            console.log(`Room ${cowork.room_id} · ${cowork.state}${r ? ` · saga: ${r.saga.phase}` : ''}`);
+            if (actions.length) {
+                console.log('Recovery:');
+                for (const a of actions)
+                    console.log(`  - ${a}`);
+            }
+            else {
+                console.log('No recovery actions needed.');
+            }
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+    cOpt(roomCmd.command('_close <id>', { hidden: true }))
+        .description('internal: settle an accepted room close')
+        .option('--json', 'JSON output')
+        .action(async (id, opts) => {
+        try {
+            const cfg = loadCfg(opts);
+            const r = await closeManagedRoom({ roomId: id, cowork: coworkFor(cfg) });
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, room_id: id, state: r.state, orchestration: r }, null, 2));
+                return;
+            }
+            console.log(`Room ${id} · ${r.state}`);
+        }
+        catch (e) {
+            await recordManagedRoomCloseError(id, errorText(e), `External close worker failed. Retry room recover ${id}.`).catch(() => { });
+            die(e);
+        }
+    });
+}