@ours.network/fleet 1.2.0-nightly.8 → 1.2.0-nightly.81

package/docs/conversation-stream.md

@@ -0,0 +1,216 @@
+# Conversation event stream (wire version 1)
+
+Initial `conversation?latest=1&limit=200` history uses the captured command and
+pending-permission inventories when the supervisor supplies a complete observation
+snapshot with its revision and ledger barrier. Empty inventories are authoritative.
+This avoids scanning the current generation for old context events after the
+latest page is full. Legacy, failed or incomplete captures retain ledger context
+recovery. Generation checks, resumed-session filtering and event cursors still apply.
+The private snapshot checks also use the store's recovered/appended segment ranges
+to skip healthy segments ending at or before their cursor. A retained prior
+generation therefore does not require rereading its whole prefix merely because
+the current-generation cursor is outside the in-memory tail. Degraded stores and
+unknown or damaged ranges retain conservative reads.
+Older pages can scan intervening newer ledger segments; the event count alone is
+not a disk-read byte bound.
+
+Disconnecting a latest/before HTTP history request cancels its disk tail reader
+at asynchronous read boundaries and prevents further orchestration or publication.
+An already admitted private-control RPC retains its existing timeout; disconnect
+does not interrupt the agent or its work. Forward-history reads and passive SSE
+retain their separate lifetimes.
+
+`GET /api/v1/roles/:id/conversation/events?expectedGeneration=GENERATION&after=CURSOR`
+uses the existing Fleet route boundary, including `/fleet/api/v1/...` through the
+prefix gateway. Use authenticated `fetch`, then read the response body. Cookies
+work for standalone and same-origin frame access; the hosted App sends its current
+workspace access bearer in `Authorization`. Query parameters are data, never
+credentials. `after` is a nonnegative safe integer; generation is required.
+No new WebSocket path, controller lease, notification acknowledgement, work
+submission, or read receipt is introduced.
+
+## Framing
+
+Content type is `text/event-stream; charset=utf-8`, with `Cache-Control: no-store`
+and `X-Accel-Buffering: no`. Every frame is exactly:
+
+```text
+event: conversation
+data: {"version":1,"type":"TYPE","payload":...}
+
+```
+
+The six logical types are:
+
+- `role`: complete public role replacement (`roleId`, `roleRevision`,
+  `roleLifetime`, `availability`, `health`, optional backend/fallback/failure).
+  Local state paths are omitted. This ordering is independent of session state.
+- `ledger`: either a single durable conversation event, or a coverage marker
+  `{coveredThrough:number}`. All events covered by a marker precede it. Replay
+  can legitimately advance coverage without visible events. Never advance a
+  recovery cursor from maximum rendered event sequence alone.
+- `ready`: `{sessionGeneration,stateRevision,ledgerBarrier,coveredThrough,
+  capability:"complete",authorizedUntil}`. The coherent initial snapshot arrives
+  as a preceding `state` record, keeping its full 16 MiB payload budget. Hold
+  initial state/replay as provisional until matching ready; validate generation,
+  stateRevision and ledgerBarrier against the staged state and coverage against
+  delivered replay. Only successful private replay certifies `coveredThrough`;
+  the snapshot barrier alone does not. Disconnect between state and ready must
+  not publish live initial state or advance the certified cursor. Reconnect with
+  same-generation certified coverage. State revision and event sequence differ.
+- `state`: complete conversation observation replacement, including
+  `sessionGeneration`, `stateRevision` and `ledgerBarrier`. Do not merge it as a
+  patch or use its barrier as coverage.
+- `resync`: `{reason,retry,capability}`. Clear partial assembly and resynchronize
+  explicitly or enter supported fallback. Temporary role read/watch failure is
+  retryable; a fresh observer can recover after repair. `retry:false` alone does
+  not establish permanent incapability on older servers. Explicit unsupported
+  capability or persistent oversize remains supported fallback without tight reconnects. `capability` is
+  `degraded`, except `auth-expired` below.
+- `keepalive`: `{at:number}`. Transport liveness only; it cannot certify role,
+  session, replay, or private-control health.
+
+A large logical payload uses `start`, ordered `chunk`, then `commit` frames,
+without the `payload` field:
+
+```json
+{"version":1,"type":"start","id":"3","recordType":"state","totalBytes":1048576,"generation":"g","revision":7}
+{"version":1,"type":"chunk","id":"3","index":0,"data":"a slice of the serialized payload JSON"}
+{"version":1,"type":"commit","id":"3","totalBytes":1048576,"generation":"g","revision":7}
+```
+
+Chunks contain JSON text, **not base64**. Concatenate `data`, UTF-8 count it,
+then JSON-parse only after commit. The optional generation/revision are derived
+from payload sessionGeneration/stateRevision or roleRevision;
+commit and reconstructed payload must match start. Reject duplicate/out-of-order
+chunks, empty chunks, mismatched identities/revisions/lengths, overlapping assemblies, invalid
+UTF-8, over-budget frames, and an incomplete end. Never publish partial snapshots.
+`ConversationStreamDecoder` implements these framing checks without Node APIs.
+It is not a domain reducer: consumers must additionally enforce current workspace,
+generation and monotonic state/role revisions before applying records.
+
+## Limits and ownership
+
+Encoded frames, including SSE and JSON overhead, are at most 512 KiB. Payload JSON
+is at most 16 MiB; one assembly is allowed at a time. The encoder splits at safe
+UTF-16 boundaries into at most 48 Ki code units, so JSON escaping still fits the
+encoded-frame bound. The active logical record is streamed progressively while
+waiting encoded records are capped at 8 MiB per web connection. A valid 16 MiB
+ledger event is sent independently of its coverage marker so the page envelope
+does not consume its logical-record budget. Oversize records explicitly degrade.
+The writer waits for socket drain before writing another frame; overflow sends a
+resync when writable, otherwise closes. Ledger delivery has no batching delay
+(therefore no intentional wait beyond the required 50 ms); network backpressure
+can delay actual receipt.
+
+The private supervisor separately owns its 8 MiB live replay backlog and writes
+64 KiB slices under socket backpressure. The adapter bounds each raw NDJSON line
+at 16 MiB plus the maximum computed serialized replay/ready/state/event envelope
+(replay has an empty events array; ready omits its null placeholder; coverage uses
+`Number.MAX_SAFE_INTEGER`). This admits one exact 16 MiB event;
+malformed or oversized passive input closes the stream. The receiving browser
+owns its 16 MiB assembly limit. A parsed record, serialized UTF-16 string, encoded
+frame, and socket buffers can coexist: these are logical budgets, not an RSS cap.
+Aggregate memory scales with connections, as do role watchers and private sockets.
+There is no global subscriber cap. HTTP/1 browsers commonly share about six
+connections per origin; multiple tabs, pane consumers and voice can exhaust that
+pool. Dispose surplus consumers; HTTP/2 deployment and browser pooling vary.
+
+Each web connection owns one role observer, including while the role is missing.
+Session describe/follow borrow it. Missing/replaced roles stop the old follow;
+reappearance can open another follow, still bound to the requested generation.
+Abort, revocation, server shutdown and late connector completion release owners
+idempotently. Pane observation does not acquire or release voice's independent
+controller. Private heartbeats remain serialized every two seconds; six seconds
+without one ends private health even if SSE keepalives continue.
+
+Fleet emits browser keepalives every second. Each App pane/voice attempt independently
+bounds opening through complete ready to ten seconds, regardless of incoming activity.
+After ready, nonempty byte chunks (including keepalives/comments and partial records)
+reset a ten-second silence deadline. Elapsed checks before activity and on browser
+visibility/pageshow resume give no hidden grace; suspended code expires at its first
+subsequent check. Expiry retires health and aborts the old attempt before bounded
+recovery/fallback. These browser clocks do not renew or replace credential deadlines.
+Comment-only/blank SSE frames are transport activity and publish no domain record.
+
+## Authentication, fallback and filesystem assumptions
+
+The stream is bound to its **opening** credential deadline. Rotating access lasts
+at most five minutes; it is not renewable in place. On `auth-expired`, obtain the
+renewed access credential and reconnect using only same-generation certified
+coverage. Count this normal auth reconnect separately from degraded operation.
+Fixed credentials use their device/sunset deadline. Cookie idle expiry is checked
+without updating lastSeenAt, including the exact 30-minute boundary; ordinary
+requests still update activity. Absolute expiry and revocation also end streams.
+The terminal resync uses `capability:"auth-expired"`, with retry `"authenticate"`
+for rotating credentials or `"reauthenticate"` for cookies/fixed credentials.
+Actions after expiry must reauthenticate; heartbeats cannot refresh session policy.
+
+`conversation_live_complete` describes current intersection of healthy role
+observation and private replay/heartbeat capability. It never certifies requested
+history. REST remains for initial latest history, user-requested older pages,
+explicit recovery, and older/unsupported/degraded server fallback. Healthy active
+consumers must not periodically fetch role details or history.
+
+Active pane and independent voice consumers recover transient transport, temporary observer or
+bootstrap failures after their bounded fast attempts: one delayed attempt after 10 seconds,
+then 20 seconds, then capped 30 seconds between failed settled attempts. Fallback refresh ticks
+do not start probes. Retire/abort the fallback request and timer before recovery takes cursor
+ownership; fence late responses without waiting indefinitely for cancellation. Resume only
+same-generation certified coverage; otherwise establish a canonical latest baseline. Ordinary
+REST progress and identical unsuccessful resync never reset the fast restart budget. Complete
+ready ends fallback polling and resets delayed backoff. Pane generation replacement may load a
+new baseline; voice generation replacement stops that session until explicit Start, without
+transferring controller/provider leases. Auth-required/expired ends automatic reads/probes.
+
+
+Complete role delivery relies on native directory notifications for fleet config,
+role manifests and session files. Qualified native host filesystems are the
+intended deployment (macOS local APFS or Linux local filesystems with functional
+inotify). Watch errors, unexpected closure, unsupported watching, or invalid
+current role reads withdraw completeness. Silent event loss is not detectable
+without polling and is not promised away. Docker must expose the same state files
+and private socket to the Fleet process, with working directory-change delivery
+across the selected bind mount/volume. Docker Desktop host-to-VM mounts, network
+filesystems and remote/FUSE mounts require deployment-specific notification tests;
+use degraded REST fallback when those assumptions cannot be established. No ACP
+library changes are required.
+
+## Admission receipt provenance
+
+Prompt admission responses additionally expose optional `sessionGeneration`: the
+original durable admission generation. Both backend session generations are immutable
+for the admitting lifetime. Cached receipts retain that generation, and reopened command
+indexes derive it from the original `prompt.admitted` event, never a replacement session.
+Historical receipts without provable generation leave the field absent.
+
+This permits an explicitly retried pre-change `{text, commandId}` browser draft to settle
+only when matching receipt identity and original generation validate against its captured
+current owner. Missing/old provenance keeps a visible unresolved draft and its idempotency
+ID. Existing generation-bound drafts retain their original fences. `eventCursor` and causal
+coverage/inventory settlement remain unchanged; provenance is not a new settlement watermark.
+
+## Cross-repository qualification
+
+`test/web/fixtures/conversation-stack.ts` shares the real HTTP and private-control
+stack with the legacy conversation tests and the matching App checkout's optional
+`tests/fleet-live-data.integration.mjs`. ACP uses the existing child-process protocol
+fixture; native Codex uses the existing app-server protocol driver. Both exercise
+actual session, ledger, control adapter, HTTP framing and App decoder/reconciler/UI.
+Role availability changes are controlled fixture inputs; this does not qualify native
+filesystem event delivery on an arbitrary mount.
+
+Run Fleet's full tests and typecheck after integrated changes. Retain the SSE,
+workspace-auth-provenance and workspace-tunnel suites for frame/hosted authentication,
+expiry/revocation, delayed-open disposal and bounded slow consumers. App reports
+healthy content requests separately from bootstrap, paging, credential reconnect,
+explicit recovery and unsupported-host fallback. DOM mutation and fixture latency
+measurements have no claim about real-provider inference or physical-device audio.
+The App and Fleet changes require coordinated upstream delivery; source qualification
+does not establish that installed or serving packages contain them.
+
+## Full resource delivery qualification
+
+Directory, configuration/definitions, previews, provider/status, layout and admitted-operation views share the authenticated ephemeral resource connection with per-view epochs. Complete ready requires the canonical subscribed payload; a heartbeat does not certify a failed upstream watcher. User commands remain HTTP. Controller, voice and selected-daemon health are independent owners. The selected-daemon health deadline passes its cancellation signal through the public SDK selection/request API, cancelling underlying HTTP I/O as well as retiring the result.
+
+The matching App source qualification composes the existing ACP/Codex browser fixture and records sixty-second healthy windows separately from initial/history/recovery/command/health/lease/long-poll traffic. Unit and HTTP producer checks are not proof of every rendered resource combination or installed deployment. Preserve existing room-layout suite sources and qualify released service/dependency versions separately.

package/docs/fleet-migration.md

@@ -0,0 +1,54 @@
+# Upgrade to one Fleet service
+
+Permanent and task agents share one systemd user service on Linux or one
+LaunchAgent on macOS. Install the package and explicitly run `ours-fleet init`;
+package installation alone does not migrate services. New task/temporary launches
+refuse `FLEET_SERVICE_NOT_INSTALLED` until init succeeds. Native supervision uses
+the OS user's home; a custom `OURS_FLEET_HOME` is refused. Manual/isolated fleets
+can use `OURS_FLEET_SUPERVISOR=none` without boot recovery.
+
+Before init, back up Fleet configuration, private member/runtime/session state,
+task/room records and native units/plists. Preserve operator readiness commands,
+timeout/restart settings and environment in the common parent's explicit
+systemd drop-ins (`~/.config/systemd/user/ours-fleet.service.d/`). Conflicting
+per-agent settings need operator resolution. Migration does not copy scripts or
+silently discard hooks. Resolve `OPERATOR_DROPIN_REQUIRED` or `UNSUPPORTED_DROPIN`,
+reload the user manager, verify its effective settings, then retry.
+
+Init preflights configured permanent agents, retires only their proven old native
+services and registers them after exact old-process absence. `up NAME` migrates
+only NAME. Existing identity and conversation files remain in place. On Linux,
+enabled legacy roles transfer running boot intent, including enabled inactive
+roles; disabled inactive roles remain untouched. macOS stopped roles stay stopped.
+Interrupted transfers retain receipts; retry with the original state instead of
+deleting proof or starting old and new supervisors together.
+
+The parent starts existing agent runners. Adding a member does not restart it.
+Restarting the parent affects every managed agent. Permanent agents resume their
+conversation with their existing readiness/continuity prompts and may receive a
+new private runtime instance after orderly release. Task agents retain their
+original identity, runtime owner and conversation. Managed stop persists across
+parent restart/reboot. Non-resumable temporary agents retire on parent shutdown.
+
+## Existing tasks
+
+Running pre-upgrade transient task members remain untouched and report
+`migration_pending`; init does not make them durable. Clean legacy shutdown or
+explicit temporary stop releases/archives them. After abrupt process loss,
+`ours-fleet task recover-members TASK_ID` can adopt a stopped single-room member
+only with its original owner, identity, launch, workspace, conversation and room
+admission intact and exact process absence proven. Missing/mismatched evidence
+and unmarked legacy layouts require reconciliation. There is no automatic live
+handover: let old work retire normally, or preserve and inspect its original
+state before a controlled transition. Do not create replacement identities,
+redeem invitations again or fabricate ownership records to force recovery.
+
+## Rollback
+
+Stop the common parent and prove all managed process groups absent. Preserve an
+offline backup of catalog, receipts, private state and operator drop-ins. Restore
+the prior Fleet release and reviewed legacy units/plists, enabling only intended
+running agents. Keep the common parent disabled while legacy supervision runs.
+Re-entering central mode requires retained-proof reconciliation and old-process
+absence. Physical reboot/boot ordering, real macOS launchd and live host migration
+have not been qualified by the isolated process and injected native tests.

package/docs/live-voice.md

@@ -0,0 +1,13 @@
+# Live voice managed-session boundary
+
+App Live voice sends transcripts through existing ACP managed sessions and reads the actual agent conversation. Updated ACP and native Codex supervisors advertise `generation_bound_prompts`, `idle_bound_prompts` and `targeted_voice_interrupt`; `/api/v1/roles/:id/voice-capabilities` authenticates the browser and reports whether all are present.
+
+`submit_voice_prompt` accepts `requireIdle: true`. Receipt replay precedes the idle check so retrying a lost acknowledgment does not create a second prompt or fail just because the first is running. New admission checks generation and idle/queue/tool/permission state inside the existing turn arbiter before queuing. Unrelated work is never interrupted to make room.
+
+`interrupt_voice_v2` requires a command ID, expected session generation and exact prompt ID. A matching active prompt uses normal managed-session cancellation; a settled or different prompt is a harmless no-op. A stale generation is rejected. Receipts are idempotent and conflicting reuse of an interrupt command is rejected. The browser's `/interrupt` route selects this path only when the complete target is present, with no legacy unbound fallback.
+
+Authenticated CSRF-protected `POST /api/v1/roles/:id/live-presence` takes `{ expectedSessionGeneration }`, validates the current generation before attaching `followConversation`, and streams NDJSON readiness/heartbeats. The HTTP connection owns one attended controller until disconnect. Close, generation change, auth expiry, slow consumer or attach failure detach it. The browser's ordinary workspace fetch supports this stream without provider credentials in a URL. Existing ACP permission expiry and controller detach grace remain in force.
+
+The daemon/App changes and configuration instructions live in the corresponding `ours-app/docs/live-voice.md` and `ours-sdk` Live voice documentation. The daemon owns the OpenAI key and 60-second Realtime credential minting; Fleet never receives the provider key.
+
+Coverage includes actual ACP/control-socket busy/retry/targeted-cancel tests, native Codex transport tests, authenticated presence-boundary tests and the App native browser/audio integration with separate Codex/Claude ACP protocol fixtures. Provider inference and physical-device acceptance are separate operator checks.

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.