@ours.network/fleet 1.2.0-nightly.2 → 1.2.0-nightly.20

package/dist/application/supervisor-ours-tools.d.ts

@@ -0,0 +1,159 @@
+export interface SupervisorToolRequest {
+    tool: string;
+    arguments?: Record<string, unknown>;
+}
+/** CLI and REST use the same fixed-identity MCP server as the agent harness. */
+export declare class SupervisorOursTools {
+    private withClient;
+    list(role: string): Promise<{
+        tools: {
+            inputSchema: {
+                [x: string]: unknown;
+                type: "object";
+                properties?: Record<string, object> | undefined;
+                required?: string[] | undefined;
+            };
+            name: string;
+            description?: string | undefined;
+            outputSchema?: {
+                [x: string]: unknown;
+                type: "object";
+                properties?: Record<string, object> | undefined;
+                required?: string[] | undefined;
+            } | undefined;
+            annotations?: {
+                title?: string | undefined;
+                readOnlyHint?: boolean | undefined;
+                destructiveHint?: boolean | undefined;
+                idempotentHint?: boolean | undefined;
+                openWorldHint?: boolean | undefined;
+            } | undefined;
+            execution?: {
+                taskSupport?: "optional" | "required" | "forbidden" | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        }[];
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        nextCursor?: string | undefined;
+        agent: string;
+        identity: {
+            name: string;
+            cid: string;
+            generation: number;
+        };
+    }>;
+    call(role: string, request: SupervisorToolRequest): Promise<{
+        agent: string;
+        identity: {
+            name: string;
+            cid: string;
+            generation: number;
+        };
+        result: {
+            [x: string]: unknown;
+            content: ({
+                type: "text";
+                text: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                type: "image";
+                data: string;
+                mimeType: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                type: "audio";
+                data: string;
+                mimeType: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                type: "resource";
+                resource: {
+                    uri: string;
+                    text: string;
+                    mimeType?: string | undefined;
+                    _meta?: Record<string, unknown> | undefined;
+                } | {
+                    uri: string;
+                    blob: string;
+                    mimeType?: string | undefined;
+                    _meta?: Record<string, unknown> | undefined;
+                };
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                uri: string;
+                name: string;
+                type: "resource_link";
+                description?: string | undefined;
+                mimeType?: string | undefined;
+                size?: number | undefined;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                icons?: {
+                    src: string;
+                    mimeType?: string | undefined;
+                    sizes?: string[] | undefined;
+                    theme?: "light" | "dark" | undefined;
+                }[] | undefined;
+                title?: string | undefined;
+            })[];
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+            structuredContent?: Record<string, unknown> | undefined;
+            isError?: boolean | undefined;
+        } | {
+            [x: string]: unknown;
+            toolResult: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        };
+    }>;
+}

package/dist/application/supervisor-ours-tools.js

@@ -0,0 +1,113 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { agentDir } from '../paths.js';
+import { ROLE_NAME_RE } from '../config.js';
+import { legacySupervisorIdentity } from './legacy-supervisor-identity.js';
+import { FleetError } from './errors.js';
+/** CLI and REST use the same fixed-identity MCP server as the agent harness. */
+export class SupervisorOursTools {
+    async withClient(role, work) {
+        if (!ROLE_NAME_RE.test(role))
+            throw new FleetError('invalid_request', 'invalid agent name');
+        const findCandidates = () => [false, true].map(temporary => ({ temporary, dir: agentDir(role, temporary) }))
+            .map(row => ({ ...row, path: join(row.dir, '.ours-bridge', 'descriptor.json') }))
+            .filter(row => existsSync(row.path));
+        const candidates = findCandidates();
+        if (candidates.length !== 1)
+            throw new FleetError('capability_unavailable', 'agent supervisor endpoint is missing or ambiguous');
+        const selected = candidates[0];
+        let descriptor;
+        let identityName;
+        try {
+            descriptor = JSON.parse(readFileSync(selected.path, 'utf8'));
+            identityName = readFileSync(join(selected.dir, '.identity'), 'utf8').trim();
+            if (!descriptor || typeof descriptor !== 'object')
+                throw new Error();
+        }
+        catch {
+            throw new FleetError('capability_unavailable', 'supervisor identity metadata cannot be read');
+        }
+        const legacy = ['role', 'identity', 'cid'].every(key => descriptor[key] === undefined);
+        const identity = legacy
+            ? legacySupervisorIdentity(role, identityName, selected.temporary, descriptor.generation)
+            : { name: identityName, cid: descriptor.cid, generation: descriptor.generation };
+        if (legacy && descriptor.socket !== join(selected.dir, '.ours-bridge', `g${descriptor.generation}.sock`))
+            throw new FleetError('capability_unavailable', 'legacy supervisor socket does not match the selected agent');
+        if ((!legacy && (descriptor.role !== role || descriptor.identity !== identityName))
+            || !/^[a-f0-9]{64}$/i.test(identity.cid ?? '') || !Number.isSafeInteger(descriptor.generation) || descriptor.generation < 1)
+            throw new FleetError('capability_unavailable', 'supervisor identity metadata is unavailable or mismatched');
+        const verifySelection = () => {
+            try {
+                const current = findCandidates();
+                const freshDescriptor = JSON.parse(readFileSync(selected.path, 'utf8'));
+                if (current.length !== 1 || current[0].path !== selected.path
+                    || readFileSync(join(selected.dir, '.identity'), 'utf8').trim() !== identityName
+                    || ['role', 'identity', 'cid', 'socket', 'capability', 'generation']
+                        .some(key => freshDescriptor[key] !== descriptor[key]))
+                    throw new Error();
+            }
+            catch {
+                throw new FleetError('capability_unavailable', 'selected supervisor assignment changed');
+            }
+        };
+        const client = new Client({ name: 'ours-fleet-supervisor-tools', version: '1' });
+        const transport = new StdioClientTransport({
+            command: process.execPath,
+            args: [fileURLToPath(new URL('../agent-ours/bridge.js', import.meta.url))],
+            env: { ...Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined)),
+                FLEET_OURS_BRIDGE_DESCRIPTOR: selected.path,
+                FLEET_OURS_BRIDGE_EXPECTED: JSON.stringify({ role: descriptor.role, identity: descriptor.identity, cid: descriptor.cid, generation: descriptor.generation,
+                    transportDigest: createHash('sha256').update(JSON.stringify([descriptor.socket, descriptor.capability, descriptor.generation])).digest('hex') }) },
+            stderr: 'pipe',
+        });
+        try {
+            await client.connect(transport);
+            const verify = async () => {
+                if (!legacy) {
+                    verifySelection();
+                    return;
+                }
+                // The supervisor owns the binding. The authenticated bridge and pinned local
+                // assignment are authoritative; current_identity is display text, not a protocol.
+                const fresh = legacySupervisorIdentity(role, identityName, selected.temporary, descriptor.generation);
+                if (!('proof' in identity) || fresh.proof !== identity.proof)
+                    throw new FleetError('capability_unavailable', 'legacy supervisor identity changed');
+                verifySelection();
+            };
+            await verify();
+            return await work(client, { name: identity.name, cid: identity.cid, generation: identity.generation }, verify);
+        }
+        catch (error) {
+            if (error instanceof FleetError)
+                throw error;
+            // Do not leak arguments, invites, capabilities, or raw transport errors.
+            throw new FleetError('control_unavailable', 'supervisor tool request failed; its outcome may be unknown, do not retry a mutation automatically', { retryable: false });
+        }
+        finally {
+            await client.close().catch(() => { });
+            await transport.close().catch(() => { });
+        }
+    }
+    list(role) {
+        return this.withClient(role, async (client, identity) => ({
+            agent: role, identity, ...(await client.listTools()),
+        }));
+    }
+    call(role, request) {
+        if (!request || typeof request.tool !== 'string'
+            || (request.arguments !== undefined && (!request.arguments || typeof request.arguments !== 'object' || Array.isArray(request.arguments))))
+            throw new FleetError('invalid_request', 'tool and object arguments are required');
+        return this.withClient(role, async (client, identity, verify) => {
+            const { tools } = await client.listTools();
+            if (!tools.some(tool => tool.name === request.tool))
+                throw new FleetError('forbidden', 'tool is not exposed by the fixed-identity supervisor');
+            await verify();
+            const result = await client.callTool({ name: request.tool, arguments: request.arguments ?? {} });
+            return { agent: role, identity, result };
+        });
+    }
+}

package/dist/application/task-layouts.d.ts

@@ -0,0 +1,89 @@
+import { type RoomLayoutDefinition } from '../rooms-tasks/layout-config.js';
+import { RoomLayoutService } from '../rooms-tasks/layout-service.js';
+import type { TaskLayoutLink, TaskRecord } from '../rooms-tasks/types.js';
+export type TaskLayoutOperation = 'open' | 'close-room' | 'close';
+export interface TaskLayoutOperationRecord {
+    /** Only the worker holding the current ID may update the record. */
+    id: string;
+    operation: TaskLayoutOperation;
+    room?: string;
+    status: 'launching' | 'running' | 'succeeded' | 'failed';
+    error?: string;
+    updated_at: string;
+}
+export interface TaskLayoutRoomView {
+    key: string;
+    goal: string;
+    members: string[];
+    roles?: Record<string, string>;
+    state: 'declared' | 'provisioning' | 'active' | 'closed';
+    room_id?: string;
+    identity_cid?: string;
+    ready: string[];
+}
+export interface TaskLayoutView {
+    name: string;
+    run_id: string;
+    created: boolean;
+    closed: boolean;
+    closing: boolean;
+    uncertain?: string;
+    rooms: TaskLayoutRoomView[];
+    participants: Array<{
+        key: string;
+        agent_template?: string;
+        owned: boolean;
+        retired: boolean;
+        agent?: string;
+        cid?: string;
+    }>;
+    operation?: TaskLayoutOperationRecord;
+}
+/** Hash of the authorable definition only (never the source file path). */
+export declare function layoutDefinitionHash(definition: RoomLayoutDefinition): string;
+/** Always-current brief for layout participants; rooms may open long after the run snapshot.
+ * It lives in Fleet's private layout state, never in the agent-writable task workspace. */
+export declare function taskBriefPath(task: Pick<TaskRecord, 'task_id'>): string;
+export declare function writeTaskBrief(task: Pick<TaskRecord, 'task_id' | 'title' | 'brief'>): void;
+/** Task context reaches every participant through the room contract (briefing text).
+ * The contract references the brief file instead of copying the brief, so later edits reach later rooms. */
+export declare function taskScopedDefinition(definition: RoomLayoutDefinition, task: Pick<TaskRecord, 'task_id' | 'title' | 'brief' | 'workspace'>): RoomLayoutDefinition;
+/** Opening rooms requires a started, live task; checked again by the worker before any side effect. */
+export declare function assertLayoutOpenable(task: TaskRecord): void;
+export declare class TaskLayouts {
+    private configPath?;
+    private deps;
+    constructor(configPath?: string | undefined, deps?: {
+        service?: RoomLayoutService;
+        launch?: (args: string[], operation: string) => Promise<void>;
+        binPath?: () => string | undefined;
+    });
+    private service;
+    private operationPath;
+    private provenancePath;
+    /** Serializes run creation, worker preconditions and deletion's removal of the run. */
+    private withTaskLock;
+    /** Resolve a layout for task creation: it must exist, parse and reference known Agent Templates. */
+    resolve(name: string): {
+        name: string;
+        definition_hash: string;
+    };
+    runExists(link: TaskLayoutLink): boolean;
+    /** Idempotent: reuse a run whose provenance matches this task, or snapshot one from the pinned source. */
+    ensureRun(task: TaskRecord, precondition?: (current: TaskRecord) => void): Promise<void>;
+    private verifyProvenance;
+    readOperation(runId: string): TaskLayoutOperationRecord | undefined;
+    /** Update only the still-current operation; a superseded or forgotten one is never resurrected. */
+    private updateOperation;
+    private writeOperation;
+    /** Sanitized read model: no Agent Template snapshots, owner fingerprints or session internals. */
+    view(task: TaskRecord): TaskLayoutView | undefined;
+    /** Accept an operation and run it in a detached worker; the outcome is recorded for polling. */
+    launch(task: TaskRecord, operation: TaskLayoutOperation, room?: string): Promise<TaskLayoutOperationRecord>;
+    /** Worker body. Errors are recorded and rethrown; unknown engine outcomes stay in run state for inspection. */
+    /** Without an ID (direct CLI use) the worker claims a new current operation. */
+    run(task: TaskRecord, operation: TaskLayoutOperation, room?: string, operationId?: string): Promise<void>;
+    private perform;
+    /** Deletion: close every layout resource, then remove the run and its operation record. */
+    closeAndForget(task: Pick<TaskRecord, 'task_id' | 'layout'>): Promise<void>;
+}

package/dist/application/task-layouts.js

@@ -0,0 +1,248 @@
+/** Task ↔ Room Layout bridge.
+ * A layout task owns exactly one Room Layout run, `task-<task_id>`, snapshotted
+ * from the named source layout with task context added to every room contract.
+ * Room opening and closing reuse the #199 engine in detached workers; each
+ * operation's outcome is recorded beside the run so HTTP callers can observe it.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { canonicalJson } from '../canonical-json.js';
+import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
+import { assertLayoutFile } from '../rooms-tasks/layout-config.js';
+import { getTask as readTask } from '../rooms-tasks/task-state.js';
+import { stateRoot } from '../paths.js';
+import { launchFleetWorker } from '../rooms-tasks/external-worker.js';
+import { layoutSupervisorId } from '../rooms-tasks/layout-control.js';
+import { layoutRunPath, RoomLayoutService } from '../rooms-tasks/layout-service.js';
+import { FleetError } from './errors.js';
+/** Hash of the authorable definition only (never the source file path). */
+export function layoutDefinitionHash(definition) {
+    const { version, description, participants, rooms } = definition;
+    return createHash('sha256').update(canonicalJson({ version, description: description ?? null, participants, rooms })).digest('hex');
+}
+/** Always-current brief for layout participants; rooms may open long after the run snapshot.
+ * It lives in Fleet's private layout state, never in the agent-writable task workspace. */
+export function taskBriefPath(task) {
+    return layoutRunPath(`task-${task.task_id}`).replace(/\.json$/, '.brief.md');
+}
+export function writeTaskBrief(task) {
+    const path = taskBriefPath(task); // layoutRunPath verified the private directory
+    if (existsSync(path))
+        assertLayoutFile(path);
+    replaceFileAtomically(path, `# ${task.title}\n\nTask ${task.task_id}\n\n${task.brief?.trim() ?? ''}\n`, 0o600);
+}
+/** Task context reaches every participant through the room contract (briefing text).
+ * The contract references the brief file instead of copying the brief, so later edits reach later rooms. */
+export function taskScopedDefinition(definition, task) {
+    const preamble = [
+        `Task ${task.task_id}: ${task.title}`,
+        ...(task.workspace ? [`Task workspace: ${task.workspace.path}`] : []),
+        `Current task brief: ${taskBriefPath(task)} (kept up to date by Fleet; read it before starting work)`,
+    ].join('\n');
+    for (const room of Object.values(definition.rooms))
+        room.contract = room.contract ? `${preamble}\n\nRoom contract:\n${room.contract}` : preamble;
+    return definition;
+}
+const ROOM_KEY = /^[A-Za-z][A-Za-z0-9_-]*$/;
+/** Opening rooms requires a started, live task; checked again by the worker before any side effect. */
+export function assertLayoutOpenable(task) {
+    if (task.deletion?.status === 'pending')
+        throw new FleetError('conflict', 'task is being deleted; its layout rooms cannot be opened');
+    if (task.terminal_intent || ['done', 'cancelled', 'failed'].includes(task.state))
+        throw new FleetError('conflict', 'task is closing or closed; its layout rooms cannot be opened');
+    if (task.state !== 'active' && task.state !== 'review')
+        throw new FleetError('conflict', `start the task before opening rooms (state '${task.state}')`);
+}
+export class TaskLayouts {
+    configPath;
+    deps;
+    constructor(configPath, deps = {}) {
+        this.configPath = configPath;
+        this.deps = deps;
+    }
+    service() { return this.deps.service ?? new RoomLayoutService(this.configPath); }
+    operationPath(runId) { return join(stateRoot(), 'layouts', `${runId}.op.json`); }
+    provenancePath(runId) { return layoutRunPath(runId).replace(/\.json$/, '.provenance.json'); }
+    /** Serializes run creation, worker preconditions and deletion's removal of the run. */
+    withTaskLock(runId, fn) {
+        return withFileLock(layoutRunPath(runId).replace(/\.json$/, '.task.lock'), fn);
+    }
+    /** Resolve a layout for task creation: it must exist, parse and reference known Agent Templates. */
+    resolve(name) {
+        return { name, definition_hash: layoutDefinitionHash(this.service().definition(name)) };
+    }
+    runExists(link) { return existsSync(layoutRunPath(link.run_id)); }
+    /** Idempotent: reuse a run whose provenance matches this task, or snapshot one from the pinned source. */
+    async ensureRun(task, precondition) {
+        const link = task.layout;
+        if (!link)
+            throw Error(`task ${task.task_id} has no layout`);
+        await this.withTaskLock(link.run_id, async () => {
+            const current = readTask(task.task_id);
+            precondition?.(current);
+            writeTaskBrief(current);
+            if (this.runExists(link)) {
+                this.verifyProvenance(current);
+                return;
+            }
+            const service = this.service();
+            const source = service.definition(link.name);
+            if (layoutDefinitionHash(source) !== link.definition_hash)
+                throw Error(`room layout ${link.name} changed before this task's layout run was created; create a new task to use the edited layout`);
+            const scoped = taskScopedDefinition(structuredClone(source), current);
+            const provenance = { task_id: current.task_id, source_hash: link.definition_hash, scoped_hash: layoutDefinitionHash(scoped) };
+            // Provenance precedes the run: a crash in between is re-derived from the same pinned source.
+            replaceFileAtomically(this.provenancePath(link.run_id), JSON.stringify(provenance), 0o600);
+            await service.create(link.name, {}, link.run_id, { source: scoped, cwd: current.workspace?.path });
+        });
+    }
+    verifyProvenance(task) {
+        const link = task.layout, path = this.provenancePath(link.run_id);
+        let provenance;
+        try {
+            assertLayoutFile(path);
+            provenance = JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch { /* missing or untrusted */ }
+        const snapshot = this.service().open(link.run_id, true).snapshot();
+        if (!provenance || provenance.task_id !== task.task_id || provenance.source_hash !== link.definition_hash
+            || provenance.scoped_hash !== layoutDefinitionHash({ version: 1, ...snapshot.definition }))
+            throw Error(`layout run ${link.run_id} does not match this task's pinned layout; inspect it before continuing`);
+    }
+    readOperation(runId) {
+        const path = this.operationPath(runId);
+        try {
+            return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Update only the still-current operation; a superseded or forgotten one is never resurrected. */
+    updateOperation(runId, record) {
+        return withFileLock(this.operationPath(runId) + '.lock', () => {
+            if (this.readOperation(runId)?.id !== record.id)
+                return false;
+            this.writeOperation(runId, record);
+            return true;
+        });
+    }
+    writeOperation(runId, record) {
+        layoutRunPath(runId); // validates the ID and creates the private layouts directory
+        replaceFileAtomically(this.operationPath(runId), JSON.stringify({ ...record, updated_at: new Date().toISOString() }), 0o600);
+    }
+    /** Sanitized read model: no Agent Template snapshots, owner fingerprints or session internals. */
+    view(task) {
+        const link = task.layout;
+        if (!link)
+            return undefined;
+        const base = { name: link.name, run_id: link.run_id, operation: this.readOperation(link.run_id) };
+        if (!this.runExists(link))
+            return { ...base, created: false, closed: false, closing: false, rooms: [], participants: [] };
+        const state = this.service().open(link.run_id, true).snapshot();
+        return {
+            ...base, created: true, closed: state.closed, closing: Boolean(state.closing),
+            ...(state.uncertain ? { uncertain: state.uncertain } : {}),
+            rooms: Object.entries(state.definition.rooms).map(([key, spec]) => {
+                const room = state.rooms[key];
+                return {
+                    key, goal: spec.goal, members: [...spec.members], ...(spec.roles ? { roles: { ...spec.roles } } : {}),
+                    state: room?.state ?? 'declared', ready: [...(room?.ready ?? [])],
+                    ...(room?.native ? { room_id: room.native.room_id, identity_cid: room.native.identity_cid } : {}),
+                };
+            }),
+            participants: Object.entries(state.participants).map(([key, p]) => ({
+                key, agent_template: state.definition.participants[key]?.agent_template, owned: p.owned, retired: Boolean(p.retired),
+                ...(p.instance?.agent ? { agent: p.instance.agent } : {}), ...(p.instance?.cid ? { cid: p.instance.cid } : {}),
+            })),
+        };
+    }
+    /** Accept an operation and run it in a detached worker; the outcome is recorded for polling. */
+    async launch(task, operation, room) {
+        const link = task.layout;
+        if (!link)
+            throw Error(`task ${task.task_id} has no layout`);
+        if (operation !== 'close' && (!room || !ROOM_KEY.test(room)))
+            throw new FleetError('invalid_request', 'a valid room key is required');
+        if (room) {
+            const definition = this.runExists(link) ? this.service().open(link.run_id, true).snapshot().definition : undefined;
+            if (definition && !Object.hasOwn(definition.rooms, room))
+                throw new FleetError('resource_not_found', `unknown layout room: ${room}`);
+        }
+        const record = { id: randomUUID(), operation, ...(room ? { room } : {}), status: 'launching' };
+        await withFileLock(this.operationPath(link.run_id) + '.lock', () => {
+            const current = this.readOperation(link.run_id);
+            // Full close always proceeds: terminal cleanup must not wait behind an open; the engine lock serializes them.
+            if (operation !== 'close' && current && ['launching', 'running'].includes(current.status) && Date.now() - Date.parse(current.updated_at) < 10 * 60_000)
+                throw new FleetError('conflict', `layout operation already in progress: ${current.operation}${current.room ? ' ' + current.room : ''}`);
+            this.writeOperation(link.run_id, record);
+        });
+        const args = ['task', '_layout', task.task_id, operation, ...(room ? [room] : []), '--operation-id', record.id];
+        const launch = this.deps.launch
+            ?? ((cli, name) => launchFleetWorker(cli, name, this.configPath, this.deps.binPath?.()));
+        try {
+            await launch(args, `task-layout-${task.task_id}`);
+        }
+        catch (error) {
+            await this.updateOperation(link.run_id, { ...record, status: 'failed', error: `worker failed to start: ${String(error.message ?? error)}` });
+            throw error;
+        }
+        return this.readOperation(link.run_id);
+    }
+    /** Worker body. Errors are recorded and rethrown; unknown engine outcomes stay in run state for inspection. */
+    /** Without an ID (direct CLI use) the worker claims a new current operation. */
+    async run(task, operation, room, operationId) {
+        const link = task.layout;
+        if (!link)
+            throw Error(`task ${task.task_id} has no layout`);
+        const record = { id: operationId ?? randomUUID(), operation, ...(room ? { room } : {}) };
+        if (!operationId)
+            await withFileLock(this.operationPath(link.run_id) + '.lock', () => this.writeOperation(link.run_id, { ...record, status: 'running' }));
+        else
+            await this.updateOperation(link.run_id, { ...record, status: 'running' });
+        try {
+            await this.perform(task, operation, room);
+            await this.updateOperation(link.run_id, { ...record, status: 'succeeded' });
+        }
+        catch (error) {
+            await this.updateOperation(link.run_id, { ...record, status: 'failed', error: error.message ?? String(error) });
+            throw error;
+        }
+    }
+    async perform(task, operation, room) {
+        const link = task.layout;
+        if (operation === 'open') {
+            // Re-read under the task-layout lock: a deletion or terminal action accepted after HTTP admission wins.
+            await this.ensureRun(task, assertLayoutOpenable);
+            // If deletion removed the run since, fail rather than recreate it.
+            if (!this.runExists(link))
+                throw new FleetError('conflict', 'task layout run was removed');
+            await this.service().open(link.run_id).activate(layoutSupervisorId(), room);
+            return;
+        }
+        if (!this.runExists(link))
+            return; // nothing was created, nothing to close
+        const engine = this.service().open(link.run_id, true);
+        if (operation === 'close-room') {
+            if (!engine.snapshot().rooms[room]?.native)
+                return; // declared but never opened
+            await engine.closeRoom(layoutSupervisorId(), room);
+        }
+        else
+            await engine.close(layoutSupervisorId());
+    }
+    /** Deletion: close every layout resource, then remove the run and its operation record. */
+    async closeAndForget(task) {
+        const link = task.layout;
+        if (!link)
+            return;
+        if (this.runExists(link))
+            await this.service().open(link.run_id, true).close(layoutSupervisorId());
+        await this.withTaskLock(link.run_id, async () => {
+            for (const path of [layoutRunPath(link.run_id), this.provenancePath(link.run_id), taskBriefPath(task)])
+                rmSync(path, { force: true });
+            await withFileLock(this.operationPath(link.run_id) + '.lock', () => rmSync(this.operationPath(link.run_id), { force: true }));
+        });
+    }
+}