@ours.network/fleet 1.2.0-nightly.4 → 1.2.0-nightly.40

package/dist/workspace-enrollment.js

@@ -0,0 +1,370 @@
+import { validateAccountOrigin } from './account-origin.js';
+import { lstatSync, readFileSync, readdirSync, mkdirSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { readClientProfile } from './client-profile.js';
+import { stateRoot, defaultConfigPath, workspaceOwnerInvite } from './paths.js';
+import { replaceFileAtomically } from './atomic-file.js';
+import { loadConfig, splitRootFor } from './config.js';
+import { parse, parseDocument, stringify } from 'yaml';
+import { randomUUID } from 'node:crypto';
+import { attachOursClient } from '@ours.network/sdk/client';
+import { preflightInitPaths } from './init-wizard.js';
+import { WebAccessStore } from './web/access.js';
+import { WorkspaceDeviceStore } from './web/workspace-devices.js';
+export function readWorkspacePayload(file) {
+    const path = resolve(file), stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0 || stat.size > 32768)
+        throw Error('Setup payload requires an owned private regular file (chmod 600)');
+    let p;
+    try {
+        p = JSON.parse(Buffer.from(readFileSync(path, 'utf8').trim(), 'base64url').toString());
+    }
+    catch {
+        throw Error('Invalid workspace payload');
+    }
+    if (p.version !== 1 || !['https://app.ours.network', 'https://app.ours-tunnel.com'].includes(p.appOrigin) || !/^[a-z0-9][a-z0-9-]{2,60}\.ours-tunnel\.com$/.test(p.hostname) || !/^[a-z0-9-]{2,30}@[a-z0-9-]{2,30}$/.test(p.rootName) || !/^[a-f0-9]{64}$/i.test(p.serverCid) || !p.challenge || !['nonce', 'accountId', 'workspaceId'].every(k => /^[\w-]{43}$/.test(String(p.challenge[k]))) || p.challenge.expiresAt <= Date.now() || p.challenge.expiresAt > Date.now() + 16 * 60000)
+        throw Error('Workspace payload is invalid or expired');
+    for (const k of ['connectorToken', 'invitation', 'name', 'surname'])
+        if (typeof p[k] !== 'string' || !p[k] || p[k].length > 8192 || /[\x00-\x1f\x7f]/.test(p[k]))
+            throw Error('Invalid workspace payload');
+    return p;
+}
+const GENERATED_VERSION = 'ours.network/fleet/v2';
+/** The rooms section tunnel setup writes for the enrolled Human root. */
+const generatedRooms = (rootCid, inviteFile) => ({ rooms: { owner: { provider: 'messenger-server', expected_cid: rootCid, public_invite_file: inviteFile, role: 'Owner' }, defaults: { attach_owner: true, close_when_task_done: true } } });
+/**
+ * True only when this configuration is, key for key, what tunnel setup generated itself and nothing
+ * else was added beside it. Only then may its Owner entry be treated as the record of an enrollment.
+ */
+function generatedConfigurationOnly(configuration) {
+    let document;
+    try {
+        document = parse(readFileSync(configuration, 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    const only = (value, keys) => !!value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).sort().join() === [...keys].sort().join();
+    if (!only(document, ['api_version', 'rooms']) || document.api_version !== GENERATED_VERSION)
+        return false;
+    const rooms = document.rooms;
+    if (!only(rooms, ['owner', 'defaults']) || !only(rooms.owner, ['provider', 'expected_cid', 'public_invite_file', 'role']) || !only(rooms.defaults, ['attach_owner', 'close_when_task_done']))
+        return false;
+    if (rooms.owner.provider !== 'messenger-server' || rooms.owner.role !== 'Owner' || rooms.owner.public_invite_file !== workspaceOwnerInvite() || typeof rooms.owner.expected_cid !== 'string' || !/^[a-f0-9]{64}$/i.test(rooms.owner.expected_cid)
+        || rooms.defaults.attach_owner !== true || rooms.defaults.close_when_task_done !== true)
+        return false;
+    const split = splitRootFor(configuration);
+    if (!existsSync(split))
+        return true;
+    const entries = readdirSync(split);
+    return entries.every(entry => entry === 'agents') && (!entries.length || (lstatSync(join(split, 'agents')).isDirectory() && readdirSync(join(split, 'agents')).length === 0));
+}
+/**
+ * The Owner entry of a generated configuration records an enrollment whose host state is gone:
+ * no binding and no invitation remain. Nothing else is ever replaced.
+ */
+const recordsLostEnrollment = (configuration) => !existsSync(join(stateRoot(), 'workspace', 'binding.json')) && !existsSync(workspaceOwnerInvite()) && generatedConfigurationOnly(configuration);
+function hostMessenger() {
+    const profile = readClientProfile();
+    const base = new URL(profile.endpoint);
+    base.pathname = base.pathname.replace(/\/daemon\/?$/, '/messenger/');
+    if (!base.pathname.endsWith('/messenger/'))
+        throw Error('Workspace setup requires the supported gateway client profile');
+    const secret = readFileSync(profile.credentialPath, 'utf8').trim();
+    return async (path, value) => { const response = await fetch(new URL('api/' + path, base), { method: value === undefined ? 'GET' : 'POST', headers: { 'X-Ours-Api-Token': secret, ...(value === undefined ? {} : { 'Content-Type': 'application/json', 'Origin': base.origin, 'X-Ours-Messenger-CSRF': '1' }) }, ...(value === undefined ? {} : { body: JSON.stringify(value) }), signal: AbortSignal.timeout(value === undefined ? 15000 : 60000), redirect: 'error' }); if (!response.ok) {
+        await response.body?.cancel();
+        throw Object.assign(Error('Workspace Messenger enrollment failed (HTTP ' + response.status + '); request a fresh setup payload before retrying'), { status: response.status });
+    } return response.json(); };
+}
+const daemon = (attach, purpose) => { const profile = readClientProfile(); return attach({ endpoint: profile.endpoint, expectedInstanceId: profile.expectedInstanceId, credentialPath: profile.credentialPath, sessionMode: 'external', leaseToken: `ours-fleet-workspace-${purpose}-${process.pid}-${randomUUID()}`, env: {} }); };
+const CID = /^[a-f0-9]{64}$/i, same = (a, b) => a.toLowerCase() === b.toLowerCase();
+/**
+ * Who this host's Messenger is. Messenger either runs as the Human root itself, or as the person's own
+ * identity and then names the root the daemon describes for it. That is accepted only when this host's
+ * daemon, asked by Fleet itself, lists exactly one Human root, that root is the named one, and the
+ * Messenger identity is listed as a permanent identity under it.
+ */
+async function messengerIdentity(request, attach) {
+    const bound = await request('workspace/enrollment-identity');
+    if (bound.rootCid === undefined)
+        return { cid: bound.cid, preserveProfile: bound.preserveProfile === true };
+    if (typeof bound.cid !== 'string' || !CID.test(bound.cid) || typeof bound.rootCid !== 'string' || !CID.test(bound.rootCid) || same(bound.cid, bound.rootCid))
+        throw Error('Bound Messenger identity unavailable');
+    const root = await humanRoot(attach, bound.rootCid, bound.cid);
+    return { cid: bound.cid, preserveProfile: bound.preserveProfile === true, root };
+}
+/** This host's only Human root, as its daemon lists it; optionally with a permanent identity that must be listed under it. */
+async function humanRoot(attach, rootCid, under) {
+    const client = await daemon(attach, 'identities');
+    const rows = await client.listIdentities().finally(() => client.close());
+    const roots = rows.filter(row => 'kind' in row && row.kind === 'root'), root = roots[0], row = under === undefined ? undefined : rows.find(row => 'cid' in row && same(row.cid, under));
+    if (roots.length !== 1 || !('kind' in root) || !same(root.cid, rootCid) || (under !== undefined && (!row || !('kind' in row) || row.kind !== 'role' || row.temp !== null)))
+        throw Error("This host's Messenger identity is not a permanent identity under this host's Human root. Tunnel setup changed nothing.");
+    return { name: root.name, cid: root.cid };
+}
+/** Run one operation as the Human root and always give the root back, whatever happens. */
+async function asHumanRoot(attach, root, purpose, use) {
+    const client = await daemon(attach, purpose);
+    let done = false;
+    try {
+        const bound = await client.chooseIdentity({ name: root.name, force: false }).catch((error) => {
+            throw Error(`This host's Human root cannot be used right now (${error.code ?? error.message}). Close the session that holds it, then run setup again. Nothing was changed.`);
+        });
+        if (!same(bound.cid, root.cid))
+            throw Error("This host's Human root changed while setup was running. Nothing was changed.");
+        const result = await use(client);
+        // The operation is not reported as done while the root may still be held. The release is attempted exactly once.
+        done = true;
+        const released = await client.releaseLease();
+        if (released.failed > 0)
+            throw Error("This host's Human root was not given back completely. Run setup again.");
+        return result;
+    }
+    finally {
+        // After a failure the root is released once as well; what failed first is what is reported.
+        if (!done)
+            await client.releaseLease().catch(() => { });
+        await client.close().catch(() => { });
+    }
+}
+/** The signed workspace binding, sent by the Human root itself: the same command Messenger sends when it runs as the root. */
+async function proveWithHumanRoot(attach, root, payload, hostWorkspaceId, contactWaitMs) {
+    const serverCid = payload.serverCid.toUpperCase();
+    await asHumanRoot(attach, root, 'proof', async (client) => {
+        const peer = await client.addContact({ invite: payload.invitation });
+        if (peer.cid.toUpperCase() !== serverCid)
+            throw Error('Enrollment server identity mismatch');
+        const deadline = Date.now() + contactWaitMs;
+        while (!(await client.listContacts()).contacts.some(contact => contact.container_id.toUpperCase() === serverCid)) {
+            if (Date.now() >= deadline)
+                throw Error('Enrollment contact is not ready; obtain a fresh setup payload before retrying');
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        const outcome = await client.sendCommand({ contact: serverCid, command: 'bind-workspace', arguments: { type: 'ours.app.bind-workspace.v1', accountId: payload.challenge.accountId, workspaceId: payload.challenge.workspaceId, nonce: payload.challenge.nonce, hostWorkspaceId } });
+        if (!('sent' in outcome) || !outcome.sent)
+            throw Error('Workspace proof was not sent');
+    });
+}
+/**
+ * True when the Owner entry is the one tunnel setup manages and it still names the Human root of an
+ * installation whose Messenger now runs as the person's own identity under that root. Only then is the
+ * entry moved to that identity; an Owner entry anyone else wrote is never touched.
+ */
+function managedRootOwner(configuration, rooms, root) {
+    if (!same(rooms.owner.expected_cid, root.cid) || rooms.owner.public_invite_file !== workspaceOwnerInvite() || rooms.defaults?.attach_owner === false)
+        return false;
+    if (!existsSync(join(stateRoot(), 'workspace', 'binding.json')))
+        return false;
+    let written;
+    try {
+        written = parseDocument(readFileSync(configuration, 'utf8')).toJS()?.rooms;
+    }
+    catch {
+        return false;
+    }
+    const entry = written?.owner, defaults = written?.defaults, keys = (value) => Object.keys(value).sort().join();
+    // Exactly the Owner entry and defaults tunnel setup writes; anything added or changed beside them is someone's own configuration.
+    return !!written && keys(written) === 'defaults,owner' && !!entry && keys(entry) === 'expected_cid,provider,public_invite_file,role' && entry.provider === 'messenger-server' && entry.role === 'Owner' && typeof entry.expected_cid === 'string' && same(entry.expected_cid, root.cid)
+        && !!defaults && keys(defaults) === 'attach_owner,close_when_task_done' && defaults.attach_owner === true && defaults.close_when_task_done === true;
+}
+/**
+ * Check the Fleet configuration tunnel setup will use, before the one-time command is used.
+ * Reads only; an existing Owner is compared with this host's own Messenger identity.
+ */
+export async function checkWorkspaceConfiguration(configuration = defaultConfigPath(), attach = attachOursClient) {
+    const paths = preflightInitPaths(configuration);
+    if (!paths.manifestExisted) {
+        if (paths.rootExisted)
+            throw Error(`${paths.splitRoot} exists without ${paths.configPath}. Restore that file or move the directory away.`);
+        return;
+    }
+    const loaded = loadConfig(paths.configPath, { yamlMode: 'strict', deferredOwnerInviteFile: workspaceOwnerInvite() });
+    if (!loaded.rooms)
+        return;
+    if (loaded.rooms.defaults?.attach_owner === false)
+        throw Error(`${paths.configPath}: rooms.defaults.attach_owner is disabled; enable it before tunnel setup.`);
+    if (!loaded.rooms.owner.public_invite_file)
+        throw Error(`${paths.configPath}: rooms.owner must use public_invite_file before tunnel setup.`);
+    let cid, root;
+    try {
+        ({ cid, root } = await messengerIdentity(hostMessenger(), attach));
+    }
+    catch {
+        cid = undefined;
+    }
+    if (typeof cid !== 'string' || !/^[a-f0-9]{64}$/i.test(cid))
+        throw Error(`${paths.configPath} names a room Owner, and this host's Messenger identity cannot be read to compare with it. Start Messenger on this host first.`);
+    if (loaded.rooms.owner.expected_cid.toLowerCase() !== cid.toLowerCase() && !recordsLostEnrollment(paths.configPath) && !(root && managedRootOwner(paths.configPath, loaded.rooms, root)))
+        throw Error(`${paths.configPath}: rooms.owner.expected_cid names a different Owner than this host's Messenger identity. Tunnel setup does not replace an existing Owner.`);
+}
+export async function enrollWorkspace(payload, configuration = defaultConfigPath(), options = {}) {
+    const attach = options.attach ?? attachOursClient;
+    const request = hostMessenger();
+    if (new WebAccessStore().read().mode === 'none')
+        throw Error('Workspace enrollment requires protected web access; enable pairing or password before setup');
+    const dir = join(stateRoot(), 'workspace');
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const appOrigin = validateAccountOrigin(payload.appOrigin);
+    const previousFile = join(dir, 'binding.json');
+    let migrating = false;
+    if (existsSync(previousFile)) {
+        const previous = JSON.parse(readFileSync(previousFile, 'utf8'));
+        if (previous.workspaceId !== payload.challenge.workspaceId)
+            throw Error('This host is already associated with another workspace');
+        const priorOrigin = validateAccountOrigin(previous.appOrigin ?? 'https://app.ours.network');
+        migrating = priorOrigin !== appOrigin;
+        if (migrating && !options.migrateAppOrigin)
+            throw Error('Account origin change requires explicit --migrate-app-origin and a fresh setup payload');
+        if (migrating && previous.serverCid && previous.serverCid.toUpperCase() !== payload.serverCid.toUpperCase())
+            throw Error('Account origin migration must retain the enrollment server identity');
+    }
+    const loaded = loadConfig(configuration, { deferredOwnerInviteFile: workspaceOwnerInvite() });
+    // Decided before anything is sent or written: the Owner entry is replaced only when it records an enrollment this host has lost.
+    const lost = Boolean(loaded.rooms) && recordsLostEnrollment(resolve(configuration));
+    if (loaded.rooms?.defaults?.attach_owner === false)
+        throw Error('Existing rooms.defaults.attach_owner is disabled; enable automatic Human Owner admission before workspace setup');
+    if (loaded.rooms && !loaded.rooms.owner.public_invite_file)
+        throw Error('Existing room owner configuration must be reviewed before workspace enrollment');
+    const identity = await messengerIdentity(request, attach);
+    if (!/^[a-f0-9]{64}$/i.test(identity.cid))
+        throw Error('Bound Messenger identity unavailable');
+    // An installation that ran Messenger as the Human root and now runs it as the person's own identity keeps its managed Owner entry, moved to that identity.
+    const moved = Boolean(loaded.rooms) && !lost && !!identity.root && !same(loaded.rooms.owner.expected_cid, identity.cid) && managedRootOwner(resolve(configuration), loaded.rooms, identity.root)
+        && JSON.parse(readFileSync(previousFile, 'utf8')).serverCid?.toUpperCase() === payload.serverCid.toUpperCase();
+    if (options.preserveProfile && identity.preserveProfile !== true)
+        throw Error('Existing-host setup requires Messenger profile-preservation support; update the host Messenger before retrying');
+    if (loaded.rooms && !lost && !moved && loaded.rooms.owner.expected_cid.toLowerCase() !== identity.cid.toLowerCase())
+        throw Error('Retained room owner CID conflicts with the Human root');
+    const inviteFile = loaded.rooms?.owner.public_invite_file || join(dir, 'owner.invite');
+    if (existsSync(inviteFile)) {
+        const stat = lstatSync(inviteFile);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || stat.nlink !== 1 || (stat.mode & 0o077) !== 0)
+            throw Error('Retained Owner invitation file must be owned and private');
+    }
+    const devices = new WorkspaceDeviceStore();
+    const hostWorkspaceId = devices.workspaceId;
+    devices.close();
+    const { name, surname, ...proofPayload } = payload;
+    let result, ownerCid;
+    if (identity.root) {
+        // The Human root signs the binding; the person's own Messenger identity is the room Owner and issues the Owner invitation.
+        await proveWithHumanRoot(attach, identity.root, payload, hostWorkspaceId, options.contactWaitMs ?? 10000);
+        const invite = await request('invites', { mode: 'public' });
+        if (typeof invite.blob !== 'string' || !invite.blob)
+            throw Error('Malformed workspace enrollment response');
+        const after = await request('workspace/enrollment-identity');
+        if (typeof after.cid !== 'string' || !same(after.cid, identity.cid) || typeof after.rootCid !== 'string' || !same(after.rootCid, identity.root.cid))
+            throw Error("This host's Messenger identity changed while setup was running; local configuration is unchanged");
+        result = { submitted: true, rootCid: identity.root.cid, ownerInvite: invite.blob };
+        ownerCid = identity.cid;
+    }
+    else {
+        result = await request('workspace/enroll', options.preserveProfile ? { ...proofPayload, hostWorkspaceId, preserveProfile: true } : { ...payload, hostWorkspaceId });
+        if (!result.submitted || !/^[a-f0-9]{64}$/i.test(result.rootCid) || typeof result.ownerInvite !== 'string')
+            throw Error('Malformed workspace enrollment response');
+        // Whatever the configuration said before, what is recorded from here on is this host's own root.
+        if (result.rootCid.toLowerCase() !== identity.cid.toLowerCase())
+            throw Error('Workspace enrollment answered for a different root than this host identity; local configuration is unchanged');
+        if (loaded.rooms && !lost && loaded.rooms.owner.expected_cid.toLowerCase() !== result.rootCid.toLowerCase())
+            throw Error('Retained room owner CID conflicts with the Human root');
+        ownerCid = result.rootCid;
+    }
+    if (migrating) {
+        const deadline = Date.now() + 15000;
+        while (true) {
+            const response = await fetch(appOrigin + '/account-api/workspace-proof', { method: 'POST', headers: { Origin: appOrigin, 'Content-Type': 'application/json' }, credentials: 'omit', redirect: 'error', signal: AbortSignal.timeout(5000), body: JSON.stringify({ ...payload.challenge, hostWorkspaceId, rootCid: result.rootCid }) });
+            if (!response.ok) {
+                await response.body?.cancel();
+                throw Error('Account origin migration proof was rejected; local trust unchanged');
+            }
+            const receipt = await response.json();
+            if (receipt.verified === true)
+                break;
+            if (Date.now() >= deadline)
+                throw Error('Account origin migration proof is not confirmed; local trust unchanged');
+            await new Promise(resolve => setTimeout(resolve, 500));
+        }
+    }
+    replaceFileAtomically(inviteFile, result.ownerInvite + '\n', 0o600);
+    options.afterInvitation?.();
+    const split = splitRootFor(configuration);
+    mkdirSync(split, { recursive: true, mode: 0o700 });
+    if (!loaded.rooms)
+        replaceFileAtomically(configuration, readFileSync(configuration, 'utf8') + '\n' + stringify(generatedRooms(ownerCid, inviteFile)), 0o600);
+    else if (lost && loaded.rooms.owner.expected_cid.toLowerCase() !== ownerCid.toLowerCase())
+        replaceFileAtomically(configuration, `api_version: ${GENERATED_VERSION}\n\n` + stringify(generatedRooms(ownerCid, inviteFile)), 0o600);
+    else if (moved) {
+        // The invitation above and this entry are two files. A setup interrupted between them leaves the entry naming the root,
+        // which is this same case again: running setup once more writes both.
+        const document = parseDocument(readFileSync(configuration, 'utf8'));
+        document.setIn(['rooms', 'owner', 'expected_cid'], ownerCid);
+        replaceFileAtomically(configuration, document.toString(), 0o600);
+    }
+    replaceFileAtomically(join(dir, 'connector'), payload.connectorToken + '\n', 0o600);
+    const origin = `https://${payload.hostname}`;
+    replaceFileAtomically(join(dir, 'tunnel.json'), JSON.stringify({ origin, tokenFile: join(dir, 'connector') }) + '\n', 0o600);
+    replaceFileAtomically(previousFile, JSON.stringify({ workspaceId: payload.challenge.workspaceId, hostWorkspaceId, appOrigin, serverCid: payload.serverCid.toUpperCase(), ...(identity.root ? { proofRootCid: identity.root.cid } : {}) }) + '\n', 0o600);
+    loadConfig(configuration);
+    return { origin, hostWorkspaceId, rootCid: result.rootCid };
+}
+/** Only the existing signed-root receipt authorizes the scoped tunnel target. */
+/**
+ * The enrollment server contact exists only to carry the signed binding. Once the account has confirmed
+ * that binding, remove exactly that contact from this host's Messenger, so it does not stay in the
+ * person's chats. The server identity is the one recorded with the binding; nothing else is touched.
+ */
+export async function removeEnrollmentContact(attach = attachOursClient) {
+    let serverCid, proofRootCid;
+    try {
+        ({ serverCid, proofRootCid } = JSON.parse(readFileSync(join(stateRoot(), 'workspace', 'binding.json'), 'utf8')));
+    }
+    catch {
+        return false;
+    }
+    if (typeof serverCid !== 'string' || !/^[A-F0-9]{64}$/i.test(serverCid))
+        return false;
+    const contact = serverCid.toUpperCase();
+    // The contact belongs to whoever sent the binding. When that was the Human root itself, the binding records it.
+    if (typeof proofRootCid === 'string' && CID.test(proofRootCid)) {
+        try {
+            const root = await humanRoot(attach, proofRootCid);
+            await asHumanRoot(attach, root, 'cleanup', client => client.removeContact({ contact }));
+        }
+        catch {
+            throw Error('the Human root did not remove it');
+        }
+        return true;
+    }
+    try {
+        await hostMessenger()('contacts/remove', { contact });
+    }
+    catch {
+        throw Error('Messenger did not remove it');
+    }
+    return true;
+}
+export async function configureWorkspacePort(payload, hostWorkspaceId, rootCid, port) {
+    const deadline = Date.now() + 15000;
+    while (true) {
+        const response = await fetch(payload.appOrigin + '/account-api/workspace-tunnel-configure', { method: 'POST', headers: { Origin: payload.appOrigin, 'Content-Type': 'application/json' }, credentials: 'omit', redirect: 'error', signal: AbortSignal.timeout(15000), body: JSON.stringify({ ...payload.challenge, hostWorkspaceId, rootCid, port }) });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw Error('Workspace tunnel target configuration failed (HTTP ' + response.status + ')');
+        }
+        const receipt = await response.json();
+        if (receipt.configured === true)
+            return;
+        if (Date.now() >= deadline)
+            throw Error('Signed workspace binding is not confirmed; tunnel target was not changed');
+        await new Promise(resolve => setTimeout(resolve, 500));
+    }
+}
+/**
+ * Point the tunnel at this host's port. The account answers only for a confirmed signed binding, and
+ * only after that answer is the enrollment contact removed; a refused or unconfirmed target leaves it,
+ * so the setup can be finished later. A removal that fails is reported and does not undo the setup.
+ */
+export async function confirmWorkspaceTarget(payload, hostWorkspaceId, rootCid, port, cleanupFailed = () => { }) {
+    await configureWorkspacePort(payload, hostWorkspaceId, rootCid, port);
+    await removeEnrollmentContact().catch(cleanupFailed);
+}

package/docs/room-layouts.md

@@ -0,0 +1,227 @@
+# YAML Room Layouts
+
+Room Layout describes room goals, participants and their shared or independent
+sessions. Rooms and agents have independent lifecycles.
+
+Place a layout at `fleet/room_layouts/<name>.yaml` beside the split configuration
+for `fleet.yaml`. Agent Templates remain in `fleet/agent_templates/`.
+
+```yaml
+version: 1
+participants:
+  product: {agent_template: Product}
+  developer: {agent_template: Developer}
+  qa: {agent_template: QA}
+rooms:
+  discovery:
+    goal: Clarify the problem and acceptance criteria
+    members: [product, developer, qa]
+  design:
+    goal: Review implementation choices
+    members: [developer, qa]
+  amigos:
+    goal: Resolve a concrete acceptance question
+    members: [product, developer, qa]
+    roles: {product: product, developer: developer, qa: qa}
+```
+
+Participant `instance_scope` controls instance reuse:
+
+- `layout` (default): repeating a participant key reuses its exact running instance
+  and session within this layout run.
+- `room`: each room using the key gets its own identity and session, lazily created
+  when that room opens. Repeated opens of the same active room reuse that instance.
+
+For example, one shared process doctor and one independent critic per room:
+
+```yaml
+version: 1
+participants:
+  doctor: {agent_template: ProcessDoctor, instance_scope: layout}
+  critic: {agent_template: Critic, instance_scope: room}
+rooms:
+  discovery:
+    goal: Agree on the problem
+    members: [doctor, critic]
+  design:
+    goal: Review the design
+    members: [doctor, critic]
+```
+
+Different keys using the same Agent Template still create independent instances.
+See the [shared](../examples/room-layouts/shared.yaml) and
+[fresh](../examples/room-layouts/fresh.yaml) examples, and the mixed
+[scoped](../examples/room-layouts/scoped.yaml) example. All choices can coexist.
+Fresh agents receive their room context. Supply relevant evidence through ordinary
+room messages or existing project documents when needed.
+
+A participant without `agent_template` requires a binding. `layout instance`
+returns a local exact reference (supervisor, agent, launch, CID and session).
+Pass participant-to-reference YAML to `create --bindings`. A stopped or replaced instance is rejected. Cross-Fleet bindings require
+an explicit owner grant, as described below.
+Room-scoped participants require `agent_template`; an explicit binding for them
+is rejected before creating resources. Bindings for layout-scoped participants
+keep their existing behavior.
+
+```sh
+ours-fleet layout validate work
+ours-fleet layout create work --id example
+ours-fleet layout open example design
+ours-fleet layout open example discovery
+ours-fleet layout open example amigos
+ours-fleet layout close-room example amigos
+ours-fleet layout status example
+ours-fleet layout close example
+```
+
+Any declared room may open first. `create` only saves the definition and resolved
+Agent Templates; `open` lazily starts missing participants and admits all members
+before sending their room context. The membership notification is informational. Existing room rules govern when
+an agent contributes. Each room opens through an explicit command.
+
+`close-room` archives a room and keeps agents available to other rooms. `close`
+archives opened rooms and stops only temporary participants created by this layout
+instance. Explicitly bound participants survive. Cleanup processes existing resources. A 3-Amigos room is an ordinary room with
+complementary members.
+Room-scoped instances follow the same cleanup rules: closing a room does not
+retire them, and a closed room cannot reopen. A new layout run creates new instances.
+
+Private state keeps the authorable definition unchanged. Its `participants` map
+uses the original key for shared instances and `<room>:<participant>` for
+room-scoped instances, with `participant` and `room` metadata. Declared but unopened
+rooms have no running instance. Status and task read models distinguish these
+entries and resolve their original Agent Template. Existing snapshots without
+`instance_scope` retain their original keys and require no migration. Snapshots
+using `room` require a Fleet version that supports this field; they are not a
+downgrade format for older Fleet versions.
+
+Supported room fields: `goal`, `members`, optional `roles`, `contract`,
+`quiet_membership`, `anonymous`. `contract` is briefing text.
+Top-level fields: `version: 1`, optional `description`, `participants`, `rooms`.
+Participant fields: optional `agent_template`, `instance_scope: layout|room`.
+Unknown fields, ambiguous YAML and invalid member references are rejected.
+Existing templates and tasks keep their behavior.
+
+Local Fleet control uses the existing authenticated control socket,
+agent runtime, `spawnTemp` and session queue. Cross-Fleet bindings delegate
+membership operations to their owning Fleet as described below. Private state
+snapshots template definitions; public status hides their environment values.
+Existing owner settings apply; owner CID/invite fingerprint are pinned. Unknown
+mutation outcomes stop new work for inspection rather than blindly replaying a
+spawn or room creation. `close` and `close-room` can still clean known resources.
+Cleanup continues after individual errors and does not stop replacement or borrowed
+instances. Confirmed stopped workers need no live control socket. An unknown
+original outcome remains recorded, and cleanup reports incomplete until inspected;
+it never claims that unknown resources were found or removed. Retrying cleanup
+checks known resources and skips completed cleanup. Reopening an active layout room
+checks its native state, CID and required seats and reports drift without repairing it.
+
+
+Shared sessions retain available conversation context, not guaranteed perfect
+recall or isolation between rooms. Compaction and model judgment still matter.
+Rooms keep their existing turn scheduling.
+
+Each layout instance creates distinct native room names, so several instances can
+open the same declared room key. Participant roles must differ from the attached
+owner role; a collision is rejected before creating resources.
+
+Definitions are loaded for authoring commands. Retained instances use their saved
+layout and Agent Templates. Status and cleanup operate on saved resources even
+when the source YAML is broken or removed. New agent launches continue to use
+Fleet's normal configuration and launch checks.
+
+## Borrowing an instance from another Fleet on the same host
+
+Fleet A can open rooms using standalone temporary or persistent agents supervised
+by Fleet B under another OS user. Both must select the same daemon instance and
+Cowork gateway. An agent's original Fleet keeps its session, identity and lifecycle
+control. This extends layout bindings; it does not add bindings to legacy
+`room create` / RoomTemplate provisioning.
+
+On the agent owner's Fleet B, use its existing web server and grant access to an
+exact live standalone instance:
+
+```sh
+ours-fleet web serve --port 49272 --no-open
+# In another terminal belonging to Fleet B's owner:
+ours-fleet layout share Architect --temporary --participant architect \
+  --server-url http://127.0.0.1:49272 --output ./architect.binding.yaml
+```
+
+The command prints the grant ID and output path. It creates a binding YAML and
+an adjacent `.token` file, both owner-only. The private owner record stores a
+SHA-256 token digest, not the token. `share` never overwrites an existing export.
+Transfer both files explicitly to Fleet A's user through your existing secure
+file-transfer method, keeping the receiving credential file owned by that user
+with mode `0600`. Do not share Fleet B's console session, client profile, daemon
+credential, private state directory or supervisor socket. This feature creates
+no additional server; Fleet B's existing web server must remain available.
+
+Export each specialist under its logical layout participant key, then merge the
+YAML mappings into one bindings document. Keep every adjacent token filename
+unique. Relative credential paths resolve against the bindings file's directory.
+The reusable layout contains participant factories or empty participant mappings,
+never concrete credentials or running-instance references:
+
+```yaml
+version: 1
+participants:
+  architect: {}
+  developer: {}
+  doctor: {}
+rooms:
+  product: {goal: Scope, members: [architect, doctor]}
+  design: {goal: Design, members: [architect, developer, doctor]}
+  delivery: {goal: Delivery, members: [developer, doctor]}
+```
+
+On Fleet A:
+
+```sh
+ours-fleet layout create project --id project-run --bindings ./bindings.yaml
+ours-fleet layout open project-run product
+ours-fleet layout open project-run design
+ours-fleet layout open project-run delivery
+ours-fleet layout close-room project-run product
+ours-fleet layout close project-run
+```
+
+The exact CID, launch and harness session are reused. Reopening an active room
+checks existing membership without delivering duplicate context. Closing rooms
+archives Cowork history and never stops borrowed instances. After acceptance,
+the original Fleet B owner explicitly retires its standalone temporary specialists
+using the existing lifecycle commands. Persistent specialists keep their ordinary
+lifecycle. Mixed local-created and borrowed participants are supported.
+
+An exported reference adds `remote` to the existing instance reference:
+
+```yaml
+remote:
+  url: http://127.0.0.1:49272
+  grant_id: 11111111-1111-4111-8111-111111111111
+  credential_file: architect.binding.yaml.token
+  daemon_instance_id: 22222222-2222-4222-8222-222222222222
+```
+
+The grant authorizes only `verify`, `join`, and `assign` for that exact instance.
+Room admission validates the requested room ID and CID against shared Cowork and
+uses an invite issued by Cowork on the owner side; caller-supplied contact invites
+are rejected before contact mutation. Context delivery also requires its active seat, expected room CID and role in
+Cowork. It cannot inspect inventory, spawn, stop, reconfigure, export identities,
+or authenticate browser console routes. It grants the holder room admission and
+room-context delivery, so transfer it only to the intended room creator.
+
+Owner-side revocation does not stop the agent or remove existing memberships:
+
+```sh
+ours-fleet layout revoke-binding <grant-id>
+```
+
+Stopped/replaced sessions, a different daemon, revoked grants or unavailable
+owner transport produce errors; no replacement is spawned. A lost response to a
+membership/context mutation retains the existing layout `uncertain` marker.
+Inspect the native room and owning Fleet before retrying; no mutation is blindly
+replayed. Only direct loopback HTTP origins (`127.0.0.1`) are supported;
+redirects, external hosts and forwarded requests are rejected. No cross-host
+support, discovery protocol, mission service, or room conversation limits are
+introduced.