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

package/dist/rooms-tasks/layout.js

@@ -0,0 +1,227 @@
+/** Durable local room-layout controller.
+ * Uses native Cowork operations and a supervising Fleet's exact-instance port.
+ * Unknown mutation outcomes stop for reconciliation; they are never replayed.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { canonicalJson } from '../canonical-json.js';
+import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
+const ownerReference = (owner) => ({ cid: owner.cid, role: owner.role, fingerprint: createHash('sha256').update(owner.invite).digest('hex') });
+const own = (o, key) => Object.hasOwn(o, key);
+function need(ok, message) { if (!ok)
+    throw Error(message); }
+export function validateLayout(def) {
+    need(Object.keys(def.rooms).length && Object.keys(def.participants).length, 'rooms and participants required');
+    for (const [key, room] of Object.entries(def.rooms)) {
+        need(key.length && room.goal.trim() && room.members.length, 'room goal and members required');
+        need(new Set(room.members).size === room.members.length, 'duplicate participant in room');
+        for (const member of room.members)
+            need(own(def.participants, member), `unknown participant ${member}`);
+    }
+    for (const key of [...Object.keys(def.rooms), ...Object.keys(def.participants)])
+        need(/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(key) && !['constructor', 'prototype', '__proto__'].includes(key), 'invalid layout key');
+}
+export class RoomLayout {
+    file;
+    supervisor;
+    owner;
+    coworkAdapter;
+    coworkFactory;
+    constructor(file, cowork, supervisor, owner) {
+        this.file = file;
+        this.supervisor = supervisor;
+        this.owner = owner;
+        this.coworkFactory = typeof cowork === 'function' ? cowork : () => cowork;
+    }
+    get cowork() { return this.coworkAdapter ??= this.coworkFactory(); }
+    snapshot() { return JSON.parse(readFileSync(this.file, 'utf8')); }
+    save(s) { replaceFileAtomically(this.file, JSON.stringify(s, null, 2)); }
+    async verify(i) {
+        need(i.supervisor === this.supervisor.id, 'remote binding unsupported');
+        need(i.launch && i.cid && i.session, 'incomplete instance reference');
+        await this.supervisor.verify(i);
+    }
+    async create(definition, controller, bindings = {}, agentTemplates) {
+        validateLayout(definition);
+        need(controller, 'controller required');
+        this.checkOwnerRoles(definition);
+        await withFileLock(this.file + '.lock', async () => {
+            need(!existsSync(this.file), 'layout instance already exists');
+            for (const key of Object.keys(bindings))
+                need(own(definition.participants, key), 'unknown binding');
+            // Validate every supplied binding before any external mutation.
+            for (const [key, p] of Object.entries(definition.participants)) {
+                need(bindings[key] || p.agent_template, `binding required for ${key}`);
+                if (bindings[key])
+                    await this.verify(bindings[key]);
+            }
+            for (const room of Object.values(definition.rooms)) {
+                const cids = room.members.flatMap(key => bindings[key] ? [bindings[key].cid] : []);
+                need(new Set(cids).size === cids.length, 'same instance cannot occupy two seats in one room');
+            }
+            this.save({ version: 1, definition, controller, ...(this.owner ? { owner: ownerReference(this.owner) } : {}), agent_templates: agentTemplates, participants: Object.fromEntries(Object.keys(definition.participants).map(key => [key, { owned: !bindings[key], ...(bindings[key] ? { instance: bindings[key] } : {}) }])), rooms: {}, order: [], closed: false });
+        });
+    }
+    checkOwnerRoles(definition) {
+        if (!this.owner)
+            return;
+        for (const room of Object.values(definition.rooms))
+            need(room.members.every(member => (room.roles?.[member] ?? member) !== this.owner.role), 'participant cannot use the owner role');
+    }
+    async operation(actor, work, cleanup = false) {
+        return withFileLock(this.file + '.lock', async () => {
+            const s = this.snapshot();
+            need(actor === s.controller, 'controller authorization required');
+            if (!cleanup) {
+                need(!s.closed && !s.closing, 'layout instance closing or closed');
+                need(!s.uncertain, `reconciliation required: ${s.uncertain}`);
+            }
+            return work(s);
+        });
+    }
+    async mutation(s, id, work, commit) {
+        s.uncertain = id;
+        this.save(s);
+        // On any error keep the cursor, even if the operation may have succeeded.
+        const result = await work();
+        commit(result);
+        delete s.uncertain;
+        this.save(s);
+    }
+    async activateRoom(s, key, spec) {
+        if (s.owner)
+            need(this.owner && canonicalJson(s.owner) === canonicalJson(ownerReference(this.owner)), 'room owner configuration changed');
+        this.checkOwnerRoles(s.definition);
+        need(s.rooms[key]?.state !== 'closed', 'room closed');
+        for (const member of spec.members) {
+            const i = s.participants[member]?.instance;
+            if (i)
+                await this.verify(i);
+            need(!s.participants[member]?.retired, 'participant retired');
+        }
+        if (s.rooms[key]?.state === 'active') {
+            await this.assertRoomActive(s, key);
+            return;
+        }
+        const room = s.rooms[key] ??= { spec, state: 'provisioning', ready: [] };
+        this.save(s);
+        for (const member of spec.members) {
+            const p = s.participants[member];
+            if (!p.instance) {
+                const template = s.definition.participants[member]?.agent_template;
+                need(template, `no factory for ${member}`);
+                await this.mutation(s, `spawn:${member}`, () => this.supervisor.spawn(member, template), i => { p.instance = i; });
+                await this.verify(p.instance);
+            }
+        }
+        const roleFor = (member) => spec.roles?.[member] ?? member;
+        if (!room.native)
+            await this.mutation(s, `create:${key}`, () => this.cowork.createRoom({
+                room_name: `${key.slice(0, 24)}-${createHash('sha256').update(this.file + '\0' + key).digest('hex').slice(0, 24)}`,
+                goal: spec.goal, briefing: JSON.stringify({ goal: spec.goal, contract: spec.contract }),
+                quiet_membership: spec.quiet_membership ?? true, anonymous: spec.anonymous ?? false,
+                activation_requirements: [...new Set(spec.members.map(roleFor))].map(role => ({ role, count: spec.members.filter(m => roleFor(m) === role).length })),
+            }), native => { room.native = native; s.order.push(key); });
+        if (s.owner && !room.owner_ready)
+            await this.mutation(s, `owner:${key}`, async () => {
+                await this.cowork.acceptInvite(room.native.room_id, this.owner.invite, { role: s.owner.role, expected_cid: s.owner.cid });
+                await this.cowork.setRoleCommands(room.native.room_id, { role: s.owner.role, commands: ['*'] });
+            }, () => { room.owner_ready = true; });
+        for (const member of spec.members) {
+            if (room.ready.includes(member))
+                continue;
+            const i = s.participants[member].instance;
+            await this.verify(i);
+            const seats = await this.cowork.getSeats(room.native.room_id);
+            if (!seats.some(seat => seat.identity_cid === i.cid && seat.role === roleFor(member) && seat.seat_state !== 'removed')) {
+                await this.mutation(s, `admit:${key}:${member}`, async () => {
+                    const invitation = await this.cowork.issueInvite(room.native.room_id, { mode: 'one_time', role: roleFor(member), min_accepts: 1 });
+                    await this.supervisor.join(i, invitation.invite, room.native.identity_cid);
+                }, () => { });
+            }
+        }
+        await this.assertRoomActive(s, key);
+        // Admission of all required seats precedes any participant work.
+        for (const member of spec.members) {
+            if (room.ready.includes(member))
+                continue;
+            const i = s.participants[member].instance;
+            await this.verify(i);
+            await this.mutation(s, `assignment:${key}:${member}`, () => this.supervisor.assign(i, {
+                id: `${key}:${member}`, room_id: room.native.room_id, room_cid: room.native.identity_cid,
+                participant: member, room_role: roleFor(member), goal: spec.goal, contract: spec.contract,
+            }), () => { room.ready.push(member); });
+        }
+        room.state = 'active';
+        this.save(s);
+    }
+    activate(actor, key) {
+        return this.operation(actor, async (s) => {
+            need(own(s.definition.rooms, key), 'unknown room');
+            await this.activateRoom(s, key, s.definition.rooms[key]);
+        });
+    }
+    async assertRoomActive(s, key) {
+        const room = s.rooms[key], native = await this.cowork.getRoom(room.native.room_id);
+        need(native?.identity_cid === room.native.identity_cid && native.state === 'active', 'native room missing, changed or inactive');
+        if (s.owner)
+            need(native.seats.some(seat => seat.identity_cid === s.owner.cid
+                && seat.role === s.owner.role && seat.seat_state === 'active'), 'owner membership not active');
+        need(room.spec.members.every(member => native.seats.some(seat => seat.identity_cid === s.participants[member].instance.cid
+            && seat.role === (room.spec.roles?.[member] ?? member) && seat.seat_state === 'active')), 'membership not active');
+    }
+    async archiveRoom(s, key) {
+        const room = s.rooms[key];
+        need(room?.native, 'room not created');
+        if (room.state === 'closed')
+            return;
+        const native = await this.cowork.getRoom(room.native.room_id);
+        if (native) {
+            need(native.identity_cid === room.native.identity_cid, 'native room identity changed');
+            if (native.state !== 'closed')
+                await this.cowork.closeRoom(room.native.room_id);
+        }
+        room.state = 'closed';
+        this.save(s);
+    }
+    closeRoom(actor, key) {
+        return this.operation(actor, s => this.archiveRoom(s, key), true);
+    }
+    close(actor) {
+        return this.operation(actor, async (s) => {
+            if (s.closed)
+                return;
+            s.closing = true;
+            this.save(s);
+            const errors = [];
+            for (const key of [...s.order].reverse()) {
+                try {
+                    await this.archiveRoom(s, key);
+                }
+                catch (error) {
+                    errors.push(`room ${key}: ${String(error)}`);
+                }
+            }
+            for (const [key, p] of Object.entries(s.participants))
+                if (p.owned && p.instance && !p.retired) {
+                    try {
+                        need(p.instance.supervisor === this.supervisor.id, 'remote binding unsupported');
+                        await this.supervisor.retire(p.instance);
+                        p.retired = true;
+                        this.save(s);
+                    }
+                    catch (error) {
+                        errors.push(`participant ${key}: ${String(error)}`);
+                    }
+                }
+            // Clean known resources without erasing evidence of an unknown creation outcome.
+            if (s.uncertain)
+                errors.push(`known resources cleaned where possible; inspection still required: ${s.uncertain}`);
+            if (errors.length)
+                throw Error(`layout cleanup incomplete: ${errors.join('; ')}`);
+            s.closed = true;
+            delete s.closing;
+            this.save(s);
+        }, true);
+    }
+}

package/dist/rooms-tasks/live-readiness.js

@@ -11,7 +11,8 @@ export async function taskLiveReadiness(task, room, cowork, deps = {}) {
         || room.task_id !== task.task_id || !room.room_identity_cid
         || task.room_identity_cid !== room.room_identity_cid)
         return degraded('room_record_mismatch');
-    const expected = room.template_snapshot?.members.reduce((n, member) => n + member.count, 0);
+    const baseExpected = room.template_snapshot?.members.reduce((n, member) => n + member.count, 0);
+    const expected = baseExpected === undefined ? undefined : baseExpected + (room.additional_member_templates ?? []).reduce((n, t) => n + t.members.reduce((m, s) => m + s.count, 0), 0);
     if (expected === undefined || room.member_seats.length !== expected
         || new Set(room.member_seats.map(seat => seat.role_name)).size !== expected
         || new Set(room.member_seats.map(seat => seat.identity_cid)).size !== expected)

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

@@ -3,6 +3,7 @@ import type { RoomOrchestrationRecord, TemplateSnapshot } from './types.js';
 import { type FleetConfig } from '../config.js';
 export declare function getBinPath(): string;
 export interface ProvisionMembersInput {
+    configPath?: string;
     cfg: FleetConfig;
     cowork: CoworkAdapter;
     roomId: string;
@@ -12,6 +13,8 @@ export interface ProvisionMembersInput {
     brief?: string;
     goal?: string;
     startupWait?: Partial<StartupWaitPolicy>;
+    /** Append only the supplied new slots to an already active room. */
+    append?: boolean;
 }
 export interface StartupWaitPolicy {
     timeoutMs: number;

package/dist/rooms-tasks/provision.js

@@ -131,7 +131,7 @@ function roomTask(input, member, settings, members, roomIdentityCid, ownerSeatCi
             cowork_role: member.coworkRole,
             persona: settings.persona,
         },
-        roster: members.map(candidate => ({
+        roster: [...(input.append ? (getRoomRecord(input.roomId)?.member_seats ?? []).filter(seat => !members.some(m => m.name === seat.role_name)).map(seat => ({ name: seat.role_name, coworkRole: seat.cowork_role })) : []), ...members].map(candidate => ({
             role_name: candidate.name,
             cowork_role: candidate.coworkRole,
         })),
@@ -264,6 +264,7 @@ async function launchMember(input) {
     try {
         const launched = await spawnRoomMember({
             name: member.name,
+            configPath: provision.configPath,
             temp: true,
             identity: member.name,
             agentDefinition: settings.definition,
@@ -335,6 +336,8 @@ function reconcileMemberSeats(roomId, members, observed, ownerSeatCid) {
         && seat.seat_state === 'active');
     const seats = current.member_seats.map(seat => {
         const member = members.find(candidate => candidate.name === seat.role_name);
+        if (!member)
+            return seat;
         const readiness = readRoomReadiness(current.room_identity_cid, member.name);
         if (!readiness || readiness.room !== roomId || readiness.invite !== seat.invite_id) {
             complete = false;
@@ -373,6 +376,18 @@ export async function provisionMembers(input) {
     // and standalone retirement as well as member publication. Seat waits are bounded.
     const run = () => withFileLock(roomCloseLockPath(input.roomId), () => {
         assertProvisioningOpen(input);
+        if (input.append) {
+            const task = input.taskId ? getTask(input.taskId) : undefined;
+            const room = getRoomRecord(input.roomId);
+            if (!task || !['active', 'review'].includes(task.state) || task.blocked || room?.state !== 'active'
+                || room.task_id !== task.task_id || room.room_identity_cid !== task.room_identity_cid)
+                throw new Error('Adding an agent requires the exact active, unblocked task room');
+            const names = expandMembers(input.template, shortId(task.task_id)).map(m => m.name);
+            if (room.member_seats.some(seat => names.includes(seat.role_name)))
+                throw new Error('Member slot is already recorded; inspect its existing launch');
+            if (room.member_seats.some(seat => seat.seat_state !== 'active'))
+                throw new Error('Existing member admission must finish before adding an agent');
+        }
         if (!getRoomRecord(input.roomId))
             throw new Error(`room ${input.roomId} is missing; refusing provisioning`);
         return provisionMembersUnlocked(input);
@@ -408,22 +423,23 @@ async function provisionMembersUnlocked(input) {
     const resuming = members.length > 0
         && members.every(member => persistedNames.has(member.name));
     if (!resuming) {
-        advanceSaga(roomId, 'create_members', 3);
-        updateMemberSeats(roomId, members.map(member => {
-            const memberSettings = settings.get(member.name);
-            const evidence = launchDefinition(memberSettings.definition);
-            return ({
-                role_name: member.name,
-                slot: member.slot,
-                cowork_role: member.coworkRole,
-                seat_state: 'pending',
-                launch: { state: 'pending', attempt: 0,
-                    agent_definition: evidence.projection, agent_fingerprint: evidence.fingerprint,
-                    agent_template: memberSettings.template,
-                    agent_template_hash: memberSettings.templateHash,
-                    updated_at: new Date().toISOString() },
-            });
-        }));
+        if (!input.append)
+            advanceSaga(roomId, 'create_members', 3);
+        updateMemberSeats(roomId, [...(input.append ? existing.member_seats : []), ...members.map(member => {
+                const memberSettings = settings.get(member.name);
+                const evidence = launchDefinition(memberSettings.definition);
+                return ({
+                    role_name: member.name,
+                    slot: member.slot,
+                    cowork_role: member.coworkRole,
+                    seat_state: 'pending',
+                    launch: { state: 'pending', attempt: 0,
+                        agent_definition: evidence.projection, agent_fingerprint: evidence.fingerprint,
+                        agent_template: memberSettings.template,
+                        agent_template_hash: memberSettings.templateHash,
+                        updated_at: new Date().toISOString() },
+                });
+            })], input.append ? template : undefined);
     }
     else {
         for (const member of members) {
@@ -441,7 +457,8 @@ async function provisionMembersUnlocked(input) {
         now: input.startupWait?.now ?? Date.now,
         sleep: input.startupWait?.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms))),
     };
-    advanceSaga(roomId, 'join_role_groups', 4);
+    if (!input.append)
+        advanceSaga(roomId, 'join_role_groups', 4);
     try {
         const initialRoom = await cowork.recoverRoom(roomId);
         assertCoworkRoomPolicy(initialRoom, roomPolicy.anonymous);
@@ -526,7 +543,8 @@ async function provisionMembersUnlocked(input) {
         }
         throw error;
     }
-    advanceSaga(roomId, 'wait_seats', 5);
+    if (!input.append)
+        advanceSaga(roomId, 'wait_seats', 5);
     const deadline = policy.now() + policy.timeoutMs;
     let delay = policy.initialDelayMs;
     for (;;) {
@@ -536,10 +554,12 @@ async function provisionMembersUnlocked(input) {
         if (reconciled.complete && remote.state === 'active')
             break;
         if (policy.now() >= deadline) {
-            advanceSaga(roomId, 'wait_seats', 5, 'waiting_seats');
+            if (!input.append)
+                advanceSaga(roomId, 'wait_seats', 5, 'waiting_seats');
             return getRoomRecord(roomId);
         }
-        advanceSaga(roomId, 'wait_seats', 5, 'waiting_seats');
+        if (!input.append)
+            advanceSaga(roomId, 'wait_seats', 5, 'waiting_seats');
         await policy.sleep(delay);
         delay = Math.min(policy.maxDelayMs, Math.max(delay + 1, delay * 2));
     }
@@ -564,9 +584,11 @@ async function provisionMembersUnlocked(input) {
             };
         });
         updateTaskMembers(taskId, taskMembers);
-        if (getTask(taskId).blocked)
+        if (!input.append && getTask(taskId).blocked)
             unblockTask(taskId);
     }
+    if (input.append)
+        return getRoomRecord(roomId);
     advanceSaga(roomId, 'activate', 6);
     const record = activateRoom(roomId);
     if (taskId)

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

@@ -22,7 +22,7 @@ export declare function advanceSaga(id: string, phase: SagaPhase, stepIndex?: nu
 export declare function setSagaError(id: string, error: string, hint?: string, detail?: ProvisioningDetail): RoomOrchestrationRecord;
 export declare function setRoomIdentity(id: string, roomIdentityCid: string): RoomOrchestrationRecord;
 export declare function setOwnerSeat(id: string, ownerSeatCid: string, inviteFingerprint: string): RoomOrchestrationRecord;
-export declare function updateMemberSeats(id: string, seats: RoomMemberSeat[]): RoomOrchestrationRecord;
+export declare function updateMemberSeats(id: string, seats: RoomMemberSeat[], additionalTemplate?: import('./types.js').TemplateSnapshot): RoomOrchestrationRecord;
 export declare function updateRoomRoleBriefing(id: string, role: string, definition: RoomRoleBriefingDefinition): RoomOrchestrationRecord;
 export declare function updateRoomHistoryCursor(id: string, cursor: number): RoomOrchestrationRecord;
 export declare function updateMemberStartup(id: string, roleName: string, update: {

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

@@ -128,11 +128,13 @@ export function setOwnerSeat(id, ownerSeatCid, inviteFingerprint) {
     writeRoom(r);
     return r;
 }
-export function updateMemberSeats(id, seats) {
+export function updateMemberSeats(id, seats, additionalTemplate) {
     const r = readRoom(id);
     if (r.state === 'closing' || r.state === 'closed')
         throw new RoomStateError(`room ${id} is ${r.state}; member provisioning is fenced`);
     r.member_seats = seats;
+    if (additionalTemplate)
+        r.additional_member_templates = [...(r.additional_member_templates ?? []), additionalTemplate];
     writeRoom(r);
     return r;
 }

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

@@ -18,6 +18,10 @@ export interface CreateTaskInput {
     idempotency_key?: string;
     start?: boolean;
     no_room?: boolean;
+    layout?: {
+        name: string;
+        definition_hash: string;
+    };
     room_id?: string;
     listId?: string;
 }
@@ -172,4 +176,19 @@ export declare function settleAbsentTaskDeletionMember(id: string, name: string)
 export declare function detachDeletedRoom(taskId: string, roomId: string): void;
 /** A completed room may consume its archives while other task members still retire. */
 export declare function beginTaskArchiveCleanup(id: string): void;
+/** Metadata-only edit; compare under the task lock to prevent lost updates. */
+/**
+ * Choose, change or clear a Backlog task's Room Layout before it starts.
+ * `expected` is the layout name the caller saw (null = none); a different
+ * current choice is a stale edit. Choosing a layout drops the sealed room
+ * template plan; the caller releases the returned launch snapshot hash.
+ */
+export declare function updateTaskLayout(id: string, expected: string | null, next: {
+    name: string;
+    definition_hash: string;
+} | null): {
+    task: TaskRecord;
+    releasedSnapshot?: string;
+};
+export declare function updateTaskBrief(id: string, brief: string, expectedBrief: string): TaskRecord;
 export {};

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

@@ -126,15 +126,17 @@ export function assertNoPendingDeletion(task) {
         throw new TaskStateError(`task ${task.task_id} is pending deletion; run 'ours-fleet task delete ${task.task_id} ${task.task_id}' to retry cleanup`);
     }
 }
+function creationPlan(plan, layout) {
+    return JSON.stringify([plan?.plan_hash ?? null, storedRoomLaunchPolicy(plan?.room_policy) ?? null,
+        layout ? `${layout.name}@${layout.definition_hash}` : null]);
+}
 export function createTask(input) {
     const key = input.idempotency_key ?? randomUUID();
     const existing = listTasks({ includeDeleting: true }).find(task => task.idempotency_key === key);
+    const requestedPlan = creationPlan(input.execution_plan, input.layout);
     if (existing) {
-        const existingPlan = existing.execution_plan?.plan_hash;
-        const requestedPlan = input.execution_plan?.plan_hash;
-        const existingPolicy = storedRoomLaunchPolicy(existing.execution_plan?.room_policy);
-        const requestedPolicy = storedRoomLaunchPolicy(input.execution_plan?.room_policy);
-        if (existingPlan !== requestedPlan || JSON.stringify(existingPolicy) !== JSON.stringify(requestedPolicy))
+        // After a Backlog plan edit the current plan differs from the one created; retries compare the original request.
+        if ((existing.creation_plan ?? creationPlan(existing.execution_plan, existing.layout)) !== requestedPlan)
             throw new TaskStateError(`idempotency key '${key}' was already used with a different execution plan`);
         return withTaskLock(existing.task_id, () => {
             const fresh = readTask(existing.task_id);
@@ -144,9 +146,12 @@ export function createTask(input) {
             return fresh;
         });
     }
+    if (input.layout && (input.execution_plan || input.no_room || input.room_id))
+        throw new TaskStateError('a layout task cannot also use a room template, no-room mode or a room');
     const state = input.start === false ? 'backlog' : 'provisioning';
+    const taskId = generateTaskId();
     const record = {
-        task_id: generateTaskId(),
+        task_id: taskId,
         list_id: input.listId ?? DEFAULT_TASK_LIST_ID,
         title: input.title,
         brief: input.brief,
@@ -155,10 +160,12 @@ export function createTask(input) {
         template: input.template,
         execution_plan: input.execution_plan,
         no_room: input.no_room || undefined,
+        ...(input.layout ? { layout: { name: input.layout.name, run_id: `task-${taskId}`, definition_hash: input.layout.definition_hash } } : {}),
         room_id: input.room_id,
         member_roles: [],
         origin: input.origin,
         idempotency_key: key,
+        creation_plan: requestedPlan,
         created_at: new Date().toISOString(),
         started_at: state === 'provisioning' ? new Date().toISOString() : undefined,
     };
@@ -840,3 +847,48 @@ export function beginTaskArchiveCleanup(id) {
         writeTask(stored);
     });
 }
+/** Metadata-only edit; compare under the task lock to prevent lost updates. */
+/**
+ * Choose, change or clear a Backlog task's Room Layout before it starts.
+ * `expected` is the layout name the caller saw (null = none); a different
+ * current choice is a stale edit. Choosing a layout drops the sealed room
+ * template plan; the caller releases the returned launch snapshot hash.
+ */
+export function updateTaskLayout(id, expected, next) {
+    return withTaskLock(id, () => {
+        const task = readTask(id);
+        assertNoPendingDeletion(task);
+        assertNoPendingTerminalIntent(task);
+        if (task.state !== 'backlog' || task.room_id)
+            throw new TaskStateError(`task ${id} has started; its room layout is fixed (state '${task.state}')`);
+        const current = task.layout?.name ?? null;
+        // A replay of the same choice is idempotent (and refreshes the pinned source hash).
+        if (current !== expected && current !== (next?.name ?? null))
+            throw new TaskStateError(`task ${id} room layout changed to '${current ?? 'one room'}'; reload before changing it`);
+        const releasedSnapshot = next ? task.execution_plan?.snapshot.launch_snapshot_hash : undefined;
+        if (next) {
+            task.layout = { name: next.name, run_id: `task-${task.task_id}`, definition_hash: next.definition_hash };
+            delete task.execution_plan;
+            delete task.template;
+            delete task.no_room;
+        }
+        else
+            delete task.layout;
+        task.room_plan_changed_at = new Date().toISOString();
+        writeTask(task);
+        return { task: readTask(id), ...(releasedSnapshot ? { releasedSnapshot } : {}) };
+    });
+}
+export function updateTaskBrief(id, brief, expectedBrief) {
+    assertCanonicalTaskId(id);
+    return withTaskLock(id, () => {
+        const task = readTask(id);
+        assertNoPendingDeletion(task);
+        assertNoPendingTerminalIntent(task);
+        if ((task.brief ?? '') !== expectedBrief && task.brief !== brief)
+            throw new TaskStateError('Description changed elsewhere. Reload the task before saving.');
+        task.brief = brief;
+        writeTask(task);
+        return task;
+    });
+}

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

@@ -97,6 +97,13 @@ export interface TaskDeletionIntent {
     first_failure?: string;
     first_recovery_hint?: string;
 }
+export interface TaskLayoutLink {
+    name: string;
+    /** Deterministic `task-<task_id>` Room Layout run ID. */
+    run_id: string;
+    /** sha256 of the canonical source layout definition the run must snapshot. */
+    definition_hash: string;
+}
 export interface TaskRecord {
     workspace?: import('./workspace.js').OwnedWorkspace;
     task_id: string;
@@ -119,6 +126,12 @@ export interface TaskRecord {
         plan_hash: string;
     };
     no_room?: boolean;
+    /** Multi-room task: rooms and participants come from a Room Layout run. */
+    layout?: TaskLayoutLink;
+    /** Set when the room plan (layout or one-room template) was changed after creation, before start. */
+    room_plan_changed_at?: string;
+    /** Fingerprint of the room plan requested at creation; idempotent retries compare against it after later plan edits. */
+    creation_plan?: string;
     room_id?: string;
     room_identity_cid?: string;
     member_roles: TaskMemberRole[];
@@ -247,6 +260,7 @@ export interface RoomOrchestrationRecord {
     goal?: string;
     task_id?: string;
     template_snapshot?: TemplateSnapshot;
+    additional_member_templates?: TemplateSnapshot[];
     /** Resolved once at launch; legacy absence means non-anonymous. */
     room_policy?: RoomLaunchPolicy;
     saga: SagaCursor;

package/dist/runner.d.ts

@@ -30,7 +30,7 @@ export interface RunnerDeps {
     /** Neutral construction seam for deterministic runner lifecycle tests. */
     startAgentSession(adapter: AgentSessionAdapter, options: AgentSessionStartOptions): Promise<AgentSession>;
     /** Construct the authenticated role control route (injectable where sockets are unavailable). */
-    createControlServer(stateDir: string, session: AgentSession, log: (line: string) => void): Pick<RoleControlServer, 'start' | 'close' | 'setFleetSpawner' | 'setFleetAuditor' | 'setOwnerChannel' | 'setConfigReloader' | 'setLoopManager'>;
+    createControlServer(stateDir: string, session: AgentSession, log: (line: string) => void): Pick<RoleControlServer, 'start' | 'close' | 'setFleetSpawner' | 'setFleetAuditor' | 'setOwnerChannel' | 'setConfigReloader' | 'setLoopManager'> & Partial<Pick<RoleControlServer, 'setLayoutControl' | 'setCorrespondence'>>;
     /** Construct scheduled-loop execution (injectable for fail-closed startup tests). */
     createLoopManager(...args: ConstructorParameters<typeof ScheduledLoopManager>): ScheduledLoopManagerHandle;
     /** Acquire the cross-process owner-channel binder lease before replacing the control socket. */
@@ -45,6 +45,11 @@ export declare class SupervisorRecycleRequiredError extends Error {
     readonly code = "OWNER_CHANNEL_SUPERVISOR_RECYCLE_REQUIRED";
     constructor();
 }
+export declare function localFleetAuditor(stateDir: string, caller: string, log: (line: string) => void, session: AgentSession): {
+    begin(requestId: string, argv: string[]): Promise<import("./fleet-command-audit.js").FleetAuditAttempt>;
+    finish(input: Parameters<NonNullable<OwnerChannelHandle["finishFleetCommandAudit"]>>[0]): Promise<import("./fleet-command-audit.js").FleetAuditAttempt>;
+    present(): Promise<void>;
+};
 /** Environment injected only into the managed harness process. */
 export declare function managedFleetProxyEnv(role: ResolvedRole, stateDir: string): Record<string, string>;
 /**
@@ -169,7 +174,7 @@ export interface AttemptResult {
     mode: 'fresh' | 'resume';
     modelRecovery?: 'advance' | 'hold';
     /** Present only when a temporary-role lifecycle signal ended the session. */
-    retirementReason?: 'identity-closed' | 'operator-stop' | 'supervisor-signal';
+    retirementReason?: 'identity-closed' | 'operator-stop' | 'supervisor-signal' | 'idle-timeout';
 }
 /** Continuous authoritative absence required after an identity was observed. */
 export declare const TEMP_IDENTITY_CLOSE_DEBOUNCE_MS = 5000;