@ours.network/fleet 1.2.0-nightly.6 → 1.2.0-nightly.61

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.

package/docs/task-workspaces.md

@@ -0,0 +1,225 @@
+# Task workspaces and artifact retention
+
+New Tasks allocate a private workspace at
+`$OURS_FLEET_HOME/.ours-fleet/workspaces/tasks/<task-id>` (the user's home is the
+default for `OURS_FLEET_HOME`). New standalone Rooms use
+`.ours-fleet/workspaces/rooms/<room-id>`. A linked Room shares its Task's workspace.
+The absolute path, owner kind/ID and random ownership token are stored in the
+record before directory allocation; `.fleet-workspace.json` proves ownership.
+The path is visible in Task/Room JSON from both CLI and API. A folder of the same
+name without the matching marker is never adopted.
+
+Every newly managed member starts at that exact workspace, including retries.
+An explicit template/member `cwd` remains in the sealed input execution plan as
+source context, but the owned workspace overrides the effective launch cwd.
+Copy or clone required source into the workspace; Fleet does not move or delete
+the configured source directory. Briefings explain this rule. Use separate
+per-agent branches/directories inside the workspace for concurrent edits.
+
+All execution artifacts, dependency checkouts and worktrees belong inside the
+workspace. Clone each repository there first, then use `git worktree add` with
+destinations inside the same workspace. Git's native worktree registry is the
+registry of record. Fleet audits `.git`, `commondir` and reverse `gitdir` links
+before deletion; both the common repository and all registered worktrees must
+be inside the workspace. An external repository's worktree inside the workspace,
+or an internal repository's worktree outside it, blocks deletion. No broad
+`git worktree prune`, branch deletion, reset or modification of unrelated Git
+metadata is performed. Removing the owned repositories also removes their
+complete internal worktree registries, including dirty and stale owned entries.
+
+| Operation | Workspace and execution artifacts | Member runtime evidence |
+| --- | --- | --- |
+| Complete, fail, cancel | Retained while Task is recorded | Retained in Fleet recovery archives |
+| Linked Room retirement or deletion | Task workspace retained | Retained |
+| Internal standalone Room retirement | Room workspace retained | Retained |
+| Explicit Task deletion | Removed after member retirement | All proven owned retired launches removed |
+| Explicit standalone Room deletion | Removed after member retirement | All proven owned retired launches removed |
+
+Internal room close means retirement, not destructive Task deletion.
+The existing CLI `room close ID ID` remains a deprecated alias for explicit
+`room delete ID ID`: it deletes standalone room-owned artifacts, but always
+retains a linked Task workspace. Its repeated-ID confirmation is unchanged. To remove a Task's
+artifacts, explicitly delete the Task. Cancellation is not deletion. Automatic
+compatibility cleanup of legacy closed Rooms skips records with owned workspaces.
+These choices reconcile close/remove wording with the requirement that completed,
+recorded Tasks retain all artifacts.
+
+Fleet's active member state (briefings, logs, session state and WORKLOG) remains
+under `.ours-fleet/tmp` while supervisors run, then in
+`.ours-fleet/recovery/temporary`. The launch stores the workspace descriptor.
+Explicit deletion first proves managed agents retired, then identifies all
+matching archived launches, including failed and replaced attempts, using the
+workspace descriptor plus role and termination/launch evidence. It preflights
+these archives and atomically transfers them to `.fleet-retired-agents` in the
+workspace before removal. Unrelated archives are not adopted by a name prefix.
+Explicit deletion also erases legacy archives with exact launch/action or room
+provenance, matching private supervisor journals and admission/launch descriptors,
+and the exact retired-launch rows in the global termination journal. It never
+infers ownership from an Agent's shared `cwd`. Artifact removal uses a durable
+manifest, ownership fingerprints and per-entry rename/removal checkpoints, so
+an interrupted deletion can resume without deleting a replacement at the old path.
+Task deletion acceptance receipts exist only during cleanup and are erased after
+settlement (including retry after a crash between Task unlink and receipt cleanup).
+Shared Fleet command audit and lifecycle delivery ledgers have exactly attributed
+target labels, configuration and command arguments removed; unrelated entries are
+preserved. Delivery/deduplication metadata and a content-free erased-resource ID
+registry remain so a running writer cannot resurrect erased content. Infrastructure
+logs without structured ownership, backups, and copies already delivered to other
+identities are external retention boundaries; this is not a claim to erase every
+external copy.
+
+Provisioning serializes Task operation then Room close locks, including bounded
+seat waits, so concurrent retries cannot publish competing members and deletion
+cannot race a member launch. Local published Rooms are reused if the Task link
+write was interrupted. Workspace allocation publishes a marked staging directory;
+restart reuses the durable token. Deletion renames the validated workspace to a
+token-specific sibling tombstone before removal. A crash during removal resumes
+that exact tombstone; the Task record is unlinked last. Before collecting archives,
+Task deletion durably checkpoints verified retirement evidence. Retries verify
+any remaining original archive and still refuse replacement live member state
+or a recreated identity even after the archive has been consumed. Failed deletion
+remains retryable with its recorded error.
+
+Explicit deletion restores missing owner read/write/traversal bits on real
+directories inside a proven owned workspace or retired archive before the Git
+audit and removal. This handles restrictive artifacts left by tests even when
+they belong to the same Unix user. It adds no group/other access, follows no
+artifact symlinks, crosses no mounted device boundary, and never changes the
+owner. Only Git pointer files that the audit must read may gain owner-read;
+hardlinked unreadable pointers are refused to avoid changing an outside alias.
+Permission changes target a verified open inode. Readable foreign-UID directories
+may be traversed unchanged; missing owner access is never repaired for another
+UID. On Linux, traversal and Git pointer reads use pinned directory/file
+descriptors, and a detected pathname replacement stops cleanup before descending.
+Unreadable entries
+use an `O_PATH` descriptor through `/proc/self/fd`; other platforms retain the
+error if they cannot open the entry safely. A restricted workspace root is
+temporarily accessible to verify its exact ownership marker; failed marker
+verification restores its original mode. Partial token-derived deletion
+tombstones resume directory cleanup without re-reading already-removed Git
+metadata. List, show, and ordinary Git audit do not repair permissions.
+
+An accepted deletion is hidden from ordinary task lists while cleanup settles.
+Use `ours-fleet task list --include-deleting --json` (or the API's
+`includeDeleting=true`) to include retained cleanup intents, and `task show ID`
+to see pending/error/retry information. Disappearance from the ordinary list is
+not proof of completed deletion; successful deletion removes the task record
+after workspace and member cleanup.
+Cowork HTTP transport failures record the RPC method, failing stage and a
+bounded error category in the cleanup intent. Credential rejection remains an
+explicit `unauthorized` protocol error. Transport diagnostics do not include
+request bodies, credentials, URLs or raw exception text, and failed mutations
+are never automatically replayed.
+
+Deletion rejects traversal, foreign recorded paths, changed markers and symlinked
+workspace ancestors. Ordinary artifact symlinks are unlinked without following
+their targets. Git control symlinks and foreign pointers are refused. As with
+Fleet's other filesystem lifecycle operations, a hostile same-UID process that
+mutates paths during validation requires OS isolation; application checks are
+not a security boundary against that process. Fleet enforces launch cwd and
+safe deletion; unrestricted agents can still write outside cwd, so the artifact
+placement rule also requires agent compliance and/or filesystem isolation.
+
+## Compatibility and limits
+
+Records from before this feature without `workspace` remain unmanaged. Existing
+agents retain their cwd and exact briefing/fingerprint so restart matching works.
+Fleet never claims an old cwd, an outcome artifact path, or a legacy recovery
+archive as owned merely because it was mentioned by a Task. Create a new managed
+Task and explicitly copy desired artifacts to migrate; deleting a legacy Task
+continues its previous lifecycle and does not delete arbitrary old files.
+
+Changing `OURS_FLEET_HOME` does not silently rebase recorded absolute ownership
+paths. Restore the original state root or explicitly migrate records and files
+with the supervisors stopped; mismatched paths fail closed. Archive transfer
+uses same-filesystem rename and reports a recoverable failure across mounts.
+
+Cowork's remote create operation has no idempotency key in this interface. A crash
+after remote creation but before local Room publication is an existing uncertain
+remote result; this change deduplicates locally recorded rooms and does not claim
+to solve that remote transaction window. Inspect remote room ownership before
+retrying ambiguous remote creation. No services or installed Fleet code are
+changed by building or testing this feature.
+
+
+## Broken provisioning and deletion recovery
+
+Deletion accepts every lifecycle state. Missing temporary directories, identities,
+remote rooms and already-erased artifacts are settled outcomes. Retry the same
+explicit delete after an interruption. A missing local member CID is recovered
+only from a matching authenticated seat in the pinned room (exact invite and
+role, uniquely matched), or a supervisor journal tied to the selected daemon,
+temporary instance and recorded creation action. These sources must agree.
+The recovered CID is persisted before retirement consumes the evidence.
+
+A contradictory CID, replacement launch, ambiguous seat, unreadable/corrupt
+record, or unreachable authority is not evidence of absence. Cleanup retains its
+cursor and reports the conflict instead of deleting an unrelated resource or
+claiming complete erasure. An identity with no recoverable authenticated binding
+requires restoring its actual ownership evidence; a name-only force removal is
+not supported. Room deletion removes the linked Task's dead room/member links and preserves its workspace; use explicit
+Task deletion when the request includes the associated Task and its artifacts.
+
+
+## Retained task agents
+
+Task agents use the common Fleet service and existing runners while remaining
+outside the standalone agent roster. Recovery retains their original identity,
+private runtime owner, launch, working directory, admitted room and supported
+backend conversation. `ours-fleet task recover-members TASK_ID` resumes proven
+stopped members or resets their held restart circuit; it never creates identities
+or invitations. See [upgrade and rollback](fleet-migration.md) for legacy tasks.
+
+Recovery delivers an undispatched assignment once, continues interrupted work,
+and sends no readiness/work prompt to a completed idle conversation. An uncertain
+dispatch gets a continuation instead of replaying the assignment. First-session
+retry requires proof that no readiness/work was submitted; established session
+loss requires restoration of the original context. Task agents require a resumable
+harness. Missing ownership, workspace or room evidence keeps recovery held.
+
+Parent shutdown suspends task agents. Explicit member stop terminally releases
+the exact saved owner and archives its launch; it does not complete the task.
+Finish/cancel/review retain their existing semantics. Task deletion stops and
+unregisters only owned members, verifies identity absence and retries cleanup
+before erasing task/room/workspace resources. Permanent siblings remain intact.
+Standalone CLI/web removal refuses `TASK_MEMBER_IS_TASK_OWNED`; use the owning
+task lifecycle. Lost/corrupt task or launch records require restoring original
+backup evidence or explicit ownership reconciliation before deletion can finish.
+
+## Owner lifecycle notifications
+
+A task mutation commits its notification event in the same atomic task record as
+its effective status. Creation, backlog, provisioning, active, review, done,
+cancelled and failed are covered; block/unblock and deletion are effective changes
+as well. Editing a description, list, block reason or saga checkpoint is not a
+status transition. Each event freezes the task identity, title, old/new status and
+navigation route at commit time, so several transitions between delivery polls
+remain separate. Legacy records begin emitting on their next actual change and
+are not retroactively announced as newly created.
+
+The Fleet manager drains committed task events without requiring the web console
+or restarting agents. Its notification producer uses the installation's existing
+owner-scoped credential; it grants no agent arbitrary-send capability. Missing
+configuration or service failure retains the events. Delivery acknowledgement
+runs under the task lock and removes only the accepted event, preserving newer
+changes. A corrupt/unreadable task record is isolated with a safe warning, so
+other tasks continue. Bounded rotating batches prevent one rejected task from
+blocking the entire sender. The built-in `default` task list is unchanged.
+
+Deleting is announced only after its intent commits. Before unlink, settlement
+prepares retained pending events plus a stable deleted event outside the task-owned
+workspace. The sender admits that retained copy only when the original task record
+is absent; an interrupted or failed unlink cannot announce deletion. The final
+event opens the task list and includes the removed task's identity. Earlier events
+keep their immutable detail routes, which may be absent after explicit deletion.
+
+A service restart or producer crash after acceptance may replay an event; the
+Notifications service must retain its acceptance receipts across read/delete to
+make that replay harmless. Upgrade Notifications alongside Fleet to obtain this
+stronger guarantee. The service's authenticated delivery diagnostics distinguish
+provider acceptance, retry, expired subscription and foreground suppression.
+Provider acceptance is not evidence of actual phone receipt. iPhone Web Push
+requires a supported Home Screen installation and granted device/browser permission;
+reopen the workspace to reconcile an expired subscription and explicitly re-enable
+permission if it was revoked. Every received push must display a notification to
+honor Safari's user-visible push requirement.