@ours.network/fleet 1.2.0-nightly.3 → 1.2.0-nightly.30

package/dist/web/service.d.ts

@@ -1,6 +1,7 @@
 import { type Exec } from '../exec.js';
 export declare const WEB_SYSTEMD_UNIT = "ours-fleet-web.service";
 export declare const WEB_LAUNCHD_LABEL = "network.ours.fleet.web";
+type ServiceEnvironment = Partial<Record<'OURS_CONFIG' | 'OURS_FLEET_HOME' | 'PATH', string>>;
 interface ServiceMetadata {
     version: 3;
     platform: 'linux' | 'darwin';
@@ -10,6 +11,7 @@ interface ServiceMetadata {
     configuration?: string;
     bind?: string;
     publicOrigin?: string;
+    environment?: ServiceEnvironment;
 }
 export interface WebServiceOptions {
     platform?: NodeJS.Platform;
@@ -18,6 +20,7 @@ export interface WebServiceOptions {
     stateDir?: string;
     uid?: number;
     runtimeExecutable?: string;
+    environment?: NodeJS.ProcessEnv;
 }
 export declare class WebServiceManager {
     private readonly platform;
@@ -26,6 +29,7 @@ export declare class WebServiceManager {
     private readonly stateDir;
     private readonly uid;
     private readonly runtimeExecutable;
+    private readonly environment;
     constructor(options?: WebServiceOptions);
     get metadataPath(): string;
     get definitionPath(): string;
@@ -45,9 +49,9 @@ export declare class WebServiceManager {
 export declare function systemdUnit(runtime: string, script: string, port: number, configuration?: string, web?: {
     bind?: string;
     publicOrigin?: string;
-}): string;
+}, environment?: ServiceEnvironment): string;
 export declare function launchdPlist(runtime: string, script: string, port: number, configuration?: string, web?: {
     bind?: string;
     publicOrigin?: string;
-}): string;
+}, environment?: ServiceEnvironment): string;
 export {};

package/dist/web/service.js

@@ -15,6 +15,7 @@ export class WebServiceManager {
     stateDir;
     uid;
     runtimeExecutable;
+    environment;
     constructor(options = {}) {
         const platform = options.platform ?? process.platform;
         if (platform !== 'linux' && platform !== 'darwin')
@@ -25,6 +26,7 @@ export class WebServiceManager {
         this.stateDir = options.stateDir ?? join(stateRoot(), 'web');
         this.uid = options.uid ?? process.getuid?.() ?? 501;
         this.runtimeExecutable = options.runtimeExecutable ?? process.execPath;
+        this.environment = serviceEnvironment(options.environment ?? process.env);
     }
     get metadataPath() { return join(this.stateDir, 'service.json'); }
     get definitionPath() {
@@ -42,13 +44,14 @@ export class WebServiceManager {
         const config = configuration ? resolve(configuration) : undefined;
         const metadata = {
             version: VERSION, platform: this.platform, runtime, script: resolvedScript, port,
+            environment: this.environment,
             ...(config ? { configuration: config } : {}),
             ...(web.bind ? { bind: web.bind } : {}),
             ...(web.publicOrigin ? { publicOrigin: web.publicOrigin } : {}),
         };
         replaceFileAtomically(this.definitionPath, this.platform === 'linux'
-            ? systemdUnit(runtime, resolvedScript, port, config, web)
-            : launchdPlist(runtime, resolvedScript, port, config, web), 0o600);
+            ? systemdUnit(runtime, resolvedScript, port, config, web, this.environment)
+            : launchdPlist(runtime, resolvedScript, port, config, web, this.environment), 0o600);
         replaceFileAtomically(this.metadataPath, JSON.stringify(metadata, null, 2) + '\n', 0o600);
         if (this.platform === 'linux') {
             await this.must('systemctl', ['--user', 'daemon-reload']);
@@ -159,19 +162,20 @@ function validatePort(port) {
 function systemdQuote(value) {
     return `"${value.replace(/[%\\"]/g, char => char === '%' ? '%%' : `\\${char}`)}"`;
 }
-export function systemdUnit(runtime, script, port, configuration, web = {}) {
+export function systemdUnit(runtime, script, port, configuration, web = {}, environment = {}) {
     const config = configuration ? ` --configuration ${systemdQuote(configuration)}` : '';
     const access = `${web.bind ? ` --bind ${systemdQuote(web.bind)}` : ''}`
         + `${web.publicOrigin ? ` --public-origin ${systemdQuote(web.publicOrigin)}` : ''}`;
     return `[Unit]\nDescription=ours-fleet localhost web console\nAfter=default.target\n\n`
         + `[Service]\nType=simple\nExecStart=${systemdQuote(runtime)} ${systemdQuote(script)} web serve --port ${port} --no-open${config}${access}\n`
+        + Object.entries(serviceEnvironment(environment)).map(([key, value]) => `Environment=${systemdQuote(`${key}=${value}`)}\n`).join('')
         + `Restart=on-failure\nRestartSec=5\nTimeoutStopSec=15\n\n`
         + `[Install]\nWantedBy=default.target\n`;
 }
 const xml = (value) => value.replace(/[&<>"']/g, char => ({
     '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;',
 }[char]));
-export function launchdPlist(runtime, script, port, configuration, web = {}) {
+export function launchdPlist(runtime, script, port, configuration, web = {}, environment = {}) {
     const config = configuration
         ? `<string>--configuration</string><string>${xml(configuration)}</string>` : '';
     const access = `${web.bind ? `<string>--bind</string><string>${xml(web.bind)}</string>` : ''}`
@@ -181,6 +185,20 @@ export function launchdPlist(runtime, script, port, configuration, web = {}) {
         + `<plist version="1.0"><dict>\n<key>Label</key><string>${WEB_LAUNCHD_LABEL}</string>\n`
         + `<key>ProgramArguments</key><array><string>${xml(runtime)}</string><string>${xml(script)}</string><string>web</string>`
         + `<string>serve</string><string>--port</string><string>${port}</string><string>--no-open</string>${config}${access}</array>\n`
+        + `<key>EnvironmentVariables</key><dict>${Object.entries(serviceEnvironment(environment)).map(([key, value]) => `<key>${key}</key><string>${xml(value)}</string>`).join('')}</dict>\n`
         + `<key>RunAtLoad</key><true/><key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>\n`
         + `<key>ProcessType</key><string>Background</string>\n</dict></plist>\n`;
 }
+// Retain only profile/tool paths, never inherited credentials or arbitrary environment.
+function serviceEnvironment(source) {
+    const result = {};
+    for (const key of ['OURS_CONFIG', 'OURS_FLEET_HOME', 'PATH']) {
+        const value = source[key];
+        if (!value)
+            continue;
+        if (/[\r\n\0]/.test(value))
+            throw new FleetError('invalid_request', `invalid service path setting: ${key}`);
+        result[key] = key === 'PATH' ? value : resolve(value);
+    }
+    return result;
+}

package/dist/web/workspace-devices.d.ts

@@ -0,0 +1,29 @@
+export interface WorkspaceDevice {
+    id: string;
+    label: string;
+    createdAt: number;
+    lastUsedAt: number;
+    expiresAt: number;
+    revokedAt: number | null;
+}
+export declare class WorkspaceDeviceStore {
+    private readonly now;
+    private readonly db;
+    readonly workspaceId: string;
+    constructor(dir?: string, now?: () => number);
+    mint(issuer?: string | null): {
+        enrollment: string;
+        workspaceId: string;
+        expiresAt: number;
+    };
+    enroll(enrollment: string, workspaceId: string, label: string): {
+        token: string;
+        device: WorkspaceDevice;
+        workspaceId: string;
+    };
+    authenticate(token: string): WorkspaceDevice;
+    valid(id: string): boolean;
+    list(): WorkspaceDevice[];
+    revoke(id: string): void;
+    close(): void;
+}

package/dist/web/workspace-devices.js

@@ -0,0 +1,84 @@
+import { createRequire } from 'node:module';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { mkdirSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { stateRoot } from '../paths.js';
+import { FleetError } from '../application/errors.js';
+const opaque = () => randomBytes(32).toString('base64url');
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+export class WorkspaceDeviceStore {
+    now;
+    db;
+    workspaceId;
+    constructor(dir = join(stateRoot(), 'web'), now = Date.now) {
+        this.now = now;
+        const { DatabaseSync } = createRequire(import.meta.url)('node:sqlite');
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        chmodSync(dir, 0o700);
+        const path = join(dir, 'workspace-devices.db');
+        this.db = new DatabaseSync(path);
+        chmodSync(path, 0o600);
+        this.db.exec(`PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000;
+      CREATE TABLE IF NOT EXISTS metadata(key TEXT PRIMARY KEY,value TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS devices(id TEXT PRIMARY KEY,hash TEXT NOT NULL,label TEXT NOT NULL,createdAt INTEGER NOT NULL,lastUsedAt INTEGER NOT NULL,expiresAt INTEGER NOT NULL,revokedAt INTEGER);
+      CREATE TABLE IF NOT EXISTS enrollments(hash TEXT PRIMARY KEY,expiresAt INTEGER NOT NULL,issuer TEXT);`);
+        this.db.prepare('INSERT OR IGNORE INTO metadata VALUES(?,?)').run('workspaceId', opaque());
+        this.workspaceId = String(this.db.prepare('SELECT value FROM metadata WHERE key=?').get('workspaceId').value);
+    }
+    mint(issuer = null) {
+        const now = this.now(), enrollment = opaque(), expiresAt = now + 5 * 60000;
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            this.db.prepare('DELETE FROM enrollments WHERE expiresAt<=?').run(now);
+            const count = Number(this.db.prepare('SELECT count(*) AS n FROM enrollments').get().n);
+            if (count >= 32)
+                throw new FleetError('rate_limited', 'too many pending device links');
+            this.db.prepare('INSERT INTO enrollments VALUES(?,?,?)').run(hash(enrollment), expiresAt, issuer);
+            this.db.exec('COMMIT');
+            return { enrollment, workspaceId: this.workspaceId, expiresAt };
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    enroll(enrollment, workspaceId, label) {
+        if (workspaceId !== this.workspaceId || typeof enrollment !== 'string' || !/^[\w-]{43}$/.test(enrollment))
+            throw new FleetError('unauthorized', 'invalid device enrollment');
+        if (typeof label !== 'string' || !label.trim() || label.length > 100 || /[\x00-\x1f\x7f]/.test(label))
+            throw new FleetError('invalid_request', 'device name must contain 1–100 printable characters');
+        const now = this.now(), id = opaque(), token = `${id}.${opaque()}`;
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const code = this.db.prepare('DELETE FROM enrollments WHERE hash=? AND expiresAt>? RETURNING issuer').get(hash(enrollment), now);
+            if (!code)
+                throw new FleetError('unauthorized', 'device enrollment is expired or already used');
+            if (code.issuer && !this.db.prepare('SELECT id FROM devices WHERE id=? AND revokedAt IS NULL AND expiresAt>?').get(code.issuer, now))
+                throw new FleetError('unauthorized', 'issuing device has been revoked');
+            const count = Number(this.db.prepare('SELECT count(*) AS n FROM devices WHERE revokedAt IS NULL AND expiresAt>?').get(now).n);
+            if (count >= 128)
+                throw new FleetError('rate_limited', 'authorized device limit reached');
+            const device = { id, label: label.trim(), createdAt: now, lastUsedAt: now, expiresAt: now + 90 * 86400000, revokedAt: null };
+            this.db.prepare('INSERT INTO devices VALUES(?,?,?,?,?,?,NULL)').run(id, hash(token), device.label, now, now, device.expiresAt);
+            this.db.exec('COMMIT');
+            return { token, device, workspaceId };
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    authenticate(token) {
+        const id = typeof token === 'string' ? token.split('.')[0] : '', now = this.now();
+        const row = this.db.prepare('SELECT * FROM devices WHERE id=? AND revokedAt IS NULL AND expiresAt>?').get(id, now);
+        const supplied = Buffer.from(hash(token || '')), expected = Buffer.from(String(row?.hash || '0'.repeat(64)));
+        if (!row || !timingSafeEqual(supplied, expected))
+            throw new FleetError('unauthorized', 'workspace device is missing, expired, or revoked');
+        this.db.prepare('UPDATE devices SET lastUsedAt=? WHERE id=?').run(now, id);
+        return { id, label: String(row.label), createdAt: Number(row.createdAt), lastUsedAt: now, expiresAt: Number(row.expiresAt), revokedAt: null };
+    }
+    valid(id) { return Boolean(this.db.prepare('SELECT id FROM devices WHERE id=? AND revokedAt IS NULL AND expiresAt>?').get(id, this.now())); }
+    list() { return this.db.prepare('SELECT id,label,createdAt,lastUsedAt,expiresAt,revokedAt FROM devices ORDER BY createdAt DESC LIMIT 256').all().map(row => ({ id: String(row.id), label: String(row.label), createdAt: Number(row.createdAt), lastUsedAt: Number(row.lastUsedAt), expiresAt: Number(row.expiresAt), revokedAt: row.revokedAt === null ? null : Number(row.revokedAt) })); }
+    revoke(id) { this.db.prepare('UPDATE devices SET revokedAt=? WHERE id=? AND revokedAt IS NULL').run(this.now(), id); this.db.prepare('DELETE FROM enrollments WHERE issuer=?').run(id); }
+    close() { this.db.close(); }
+}

package/dist/web/workspace-tunnel.d.ts

@@ -0,0 +1 @@
+export declare function startWorkspaceTunnel(origin: string): () => Promise<void>;

package/dist/web/workspace-tunnel.js

@@ -0,0 +1,32 @@
+import { spawn } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stateRoot } from '../paths.js';
+export function startWorkspaceTunnel(origin) {
+    const dir = join(stateRoot(), 'workspace'), file = join(dir, 'tunnel.json');
+    if (!existsSync(file))
+        return async () => { };
+    const config = JSON.parse(readFileSync(file, 'utf8'));
+    if (config.origin !== origin)
+        throw Error('Workspace tunnel requires its configured public origin');
+    const tokenFile = join(dir, 'connector');
+    if (config.tokenFile !== tokenFile)
+        throw Error('Unexpected connector credential path');
+    const stat = lstatSync(tokenFile);
+    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.())
+        throw Error('Connector credential must be an owned private file');
+    let stopped = false, child, timer, backoff = 1000;
+    const launch = () => {
+        if (stopped)
+            return;
+        child = spawn('cloudflared', ['tunnel', '--no-autoupdate', 'run', '--token-file', tokenFile], { stdio: 'ignore' });
+        let scheduled = false;
+        const retry = () => { if (scheduled || stopped)
+            return; scheduled = true; timer = setTimeout(launch, backoff); backoff = Math.min(30000, backoff * 2); };
+        child.once('error', retry);
+        child.once('exit', retry);
+    };
+    launch();
+    return async () => { stopped = true; clearTimeout(timer); const current = child; if (!current || current.exitCode !== null)
+        return; await new Promise(resolve => { const timeout = setTimeout(() => { current.kill('SIGKILL'); resolve(); }, 5000); current.once('exit', () => { clearTimeout(timeout); resolve(); }); current.kill('SIGTERM'); }); };
+}

package/dist/workspace-enrollment.d.ts

@@ -0,0 +1,25 @@
+export interface WorkspacePayload {
+    version: 1;
+    appOrigin: string;
+    hostname: string;
+    rootName: string;
+    name: string;
+    surname: string;
+    connectorToken: string;
+    invitation: string;
+    serverCid: string;
+    challenge: {
+        nonce: string;
+        workspaceId: string;
+        accountId: string;
+        expiresAt: number;
+    };
+}
+export declare function readWorkspacePayload(file: string): WorkspacePayload;
+export declare function enrollWorkspace(payload: WorkspacePayload, configuration?: string, options?: {
+    migrateAppOrigin?: boolean;
+    preserveProfile?: boolean;
+}): Promise<{
+    origin: string;
+    hostWorkspaceId: string;
+}>;

package/dist/workspace-enrollment.js

@@ -0,0 +1,112 @@
+import { validateAccountOrigin } from './account-origin.js';
+import { lstatSync, readFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { readClientProfile } from './client-profile.js';
+import { stateRoot, defaultConfigPath } from './paths.js';
+import { replaceFileAtomically } from './atomic-file.js';
+import { loadConfig, splitRootFor } from './config.js';
+import { stringify } from 'yaml';
+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;
+}
+export async function enrollWorkspace(payload, configuration = defaultConfigPath(), options = {}) {
+    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();
+    const request = 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(15000), redirect: 'error' }); if (!response.ok) {
+        await response.body?.cancel();
+        throw Error('Workspace Messenger enrollment failed (HTTP ' + response.status + '); request a fresh setup payload before retrying');
+    } return response.json(); };
+    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);
+    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 request('workspace/enrollment-identity');
+    if (!/^[a-f0-9]{64}$/i.test(identity.cid))
+        throw Error('Bound Messenger identity unavailable');
+    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 && 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;
+    const 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');
+    if (loaded.rooms && loaded.rooms.owner.expected_cid.toLowerCase() !== result.rootCid.toLowerCase())
+        throw Error('Retained room owner CID conflicts with the Human root');
+    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);
+    const split = splitRootFor(configuration);
+    mkdirSync(split, { recursive: true, mode: 0o700 });
+    if (!loaded.rooms)
+        replaceFileAtomically(configuration, readFileSync(configuration, 'utf8') + '\n' + stringify({ rooms: { owner: { provider: 'messenger-server', expected_cid: result.rootCid, public_invite_file: inviteFile, role: 'Owner' }, defaults: { attach_owner: true, close_when_task_done: true } } }), 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() }) + '\n', 0o600);
+    loadConfig(configuration);
+    return { origin, hostWorkspaceId };
+}

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.