@ctlflow/fleet 0.0.0-stage → 0.1.1

package/docs/README.md

@@ -0,0 +1,11 @@
+# Fleet guides
+
+- [Install and enroll a fleet](getting-started.md)
+- [Directory structure, TOML schemas and runtime options](configuration.md)
+- [Commands, operation outcomes and lifecycle](commands.md)
+- [Stop, full-history resume and confirmed fresh-history controls](sessions.md)
+- [SSH controllers and terminal attachment](remote.md)
+- [Updates, backups, portability and troubleshooting](operations.md)
+- [fleetd lifecycle and private API](https://github.com/control-flow-project/crossfire/blob/main/services/fleetd/docs/README.md)
+- [Crossfire rooms, approvals and wake authority](https://github.com/control-flow-project/crossfire/blob/main/services/crossfire/docs/management.md)
+- [Canonical contracts and acceptance requirements](https://github.com/control-flow-project/crossfire/blob/main/docs/specification.md)

package/docs/commands.md

@@ -0,0 +1,136 @@
+# Fleet commands
+
+## Controller selection
+
+```sh
+fleet setup --descriptor PERSONALIZED_SETUP_JSON_URL
+fleet setup --descriptor PERSONALIZED_SETUP_JSON_URL --config /absolute/private/research/runtime.toml
+fleet daemon start --name laptop --root /absolute/private/controller
+fleet daemon status
+fleet daemon stop
+fleet daemon restart
+fleet --root /absolute/private/controller list
+fleet remote add office --ssh operator@office-host --root /absolute/private/controller
+fleet --remote office list
+```
+
+The local root/remote connection is private CLI state. Labels are not credentials.
+Remote commands use SSH and the same private controller API.
+
+## Fleet and agent lifecycle
+
+```sh
+fleet add /absolute/private/research
+fleet list
+fleet show research
+fleet test research
+fleet start research
+fleet start research --fresh-history
+fleet agent list research
+fleet agent add research analyst-west --definition analyst
+fleet agent start research analyst-west
+fleet agent start research analyst-west --fresh-history
+fleet agent attach research analyst-west
+fleet agent contexts research analyst-west
+fleet agent attach research analyst-west --context '!ORIGINAL_ROOM_ID:YOUR_SERVER'
+fleet agent stop research analyst-west
+fleet agent remove research analyst-west
+fleet stop research
+fleet remove research
+```
+
+Add registers an explicit directory or instance. New identities need owner
+approval. Start automatically resumes the full saved native histories. Missing
+or broken established history is an error, not permission to create a new one.
+Local start starts or reuses the configured controller. Status/list/show/test,
+contexts, attachment and registry edits never start it. Stop ends addressed
+listeners and owned Codex processes. Instance removal retires its fleet registration;
+whole-fleet removal archives the approved registration. Actual stopped native
+evidence and settled decisions are required. Files, history, identity and audit
+records are preserved; removal never creates an independent agent. Closing the
+CLI does not cancel accepted controller work.
+
+Operation results distinguish pending approval, success and per-instance failure.
+Idempotency keys and expected revisions prevent conflicting replays.
+Fleet-wide and per-agent start and stop commands accept `--operation-id UUID` for an
+exact retry after uncertain submission; the command prints its ID before submission.
+Name collisions, missing credentials and invalid native settings stay errors.
+
+Contexts lists exact saved histories even when stopped or sleeping, without
+starting native processes. `fleet show` reports native phase, desired activation,
+last activity and history availability. Explicit `fleet agent start` wakes a
+sleeping native engine without input or binding replacement. Attach
+without a context selects the shared history, or private control history in
+per-room mode. `--context` chooses an existing listed context; it never creates
+a new room conversation or reads credentials into public management output.
+
+`start --fresh-history` explicitly selects the controller's reset operation, for
+one agent or the whole fleet. It stops selected owned processes, verifies complete
+available authorized history and nonsecret configuration exports, then starts fresh
+native contexts with the same identities and current definition parameters.
+It is not normal resumption. Use `--operation-id UUID` with the identical command
+to retry an uncertain request. The independent coding session doing setup is
+never controlled here.
+- [Session controls, full-history resume and fresh-history confirmation](sessions.md)
+- [Export, boundaries and reset retention](https://github.com/control-flow-project/crossfire/blob/main/services/crossfire/docs/history.md)
+
+## Delivery control and broadcast
+
+```sh
+fleet deactivate research
+fleet activate research
+fleet message research --text "Review the updated assignment"
+fleet message research --message-id YOUR_UUID --text "Review the updated assignment"
+```
+
+Deactivate pauses fleet-bound delivery but retains controller connections,
+engines and sessions. Activate resumes those bindings and unread positions.
+Crossfire UI provides equivalent revision-checked control. Connection loss pauses
+delivery; reconnect applies current server intent. Every receiver is fleet-bound.
+
+Message queues explicit input per enrolled agent through the controller. It
+does not join rooms, alter wake rules or revive explicitly stopped agents.
+A sleeping active binding resumes its exact native history for eligible input.
+The CLI prints
+a message UUID before submission. Retry uncertain submission with the same UUID
+and identical text; conflicting reuse fails. The fleet must be enabled and
+controller connected; messages expire after ten minutes.
+
+Management exposes delivered/pending/skipped/failed/expired outcomes. A native
+receipt proves publication, not completed model work.
+
+## Model-free readiness
+
+`fleet test research` reads each desired receiver through the actual shared
+listener control endpoint. It checks exact native identity, authentication,
+membership, idle availability and enabled delivery. It creates no model turn,
+conversation or unread-position update. Busy, paused, unavailable and stopped
+bindings fail explicitly; a sleeping receiver can pass without waking Codex.
+
+## Explicit software update
+
+After human consent and installing the exact new public release, use that newly
+installed executable:
+
+```sh
+fleet update research
+fleet agent update research analyst-east
+fleet daemon restart
+```
+
+Update sends the installed controller's declared immutable artifact directory to
+fleetd. The lifecycle operation stops selected receivers/native processes,
+installs pinned agent tools/skills and resumes only previously desired agents
+with their exact histories. Stopped agents stay stopped. It never re-enrolls or
+uses a standalone connection command. Review every per-instance outcome.
+Restart replaces the controller binary after update and retains desired intent.
+
+For an SSH controller, the source directory must exist on that computer:
+
+```sh
+fleet --remote office update research --release-directory /absolute/private/installed/node_modules/@ctlflow/fleetd/dist/assets
+```
+
+The controller validates that exact directory and release before replacement.
+Alternatively invoke the newly installed CLI directly over SSH. `daemon restart`
+runs locally on the controller computer, not through the remote CLI tunnel.

package/docs/configuration.md

@@ -0,0 +1,239 @@
+# Fleet configuration
+
+## Files and ownership
+
+```text
+research/
+  runtime.toml
+  rooms.toml
+  agents/
+    analyst/
+      agent.toml
+      AGENTS.md
+      workarea/
+        analyst-east/
+        analyst-west/
+```
+
+A definition owns native settings/instructions. Instances share a definition,
+not mutable sessions or work areas. Different native settings require different
+definitions; listener history settings belong to each roster instance.
+The fleet's private `.fleet` state holds bindings, desired enrollment and reset
+evidence. Each instance's private workarea holds `.codex` native provider/history
+and `.crossfire` delivery/tool state. Never commit private state.
+
+## runtime.toml
+
+```toml
+fleet = "research"
+
+[coordination]
+adapter = "crossfire"
+server = "https://YOUR_SERVER"
+owner = "@YOUR_ACCOUNT:YOUR_SERVER"
+
+[[instances]]
+key = "analyst-east"
+name = "analyst-east"
+definition = "analyst"
+workarea = "agents/analyst/workarea/analyst-east"
+
+[instances.listener_options]
+history_mode = "shared"
+
+[[instances]]
+key = "analyst-west"
+name = "analyst-west"
+definition = "analyst"
+workarea = "agents/analyst/workarea/analyst-west"
+
+[instances.listener_options]
+history_mode = "per-room"
+```
+
+Keys/names start with a lowercase letter, contain lowercase letters, digits or
+hyphens, and are at most 40 characters. Instance names, keys and work areas must
+be distinct. Work areas are non-overlapping relative children of
+`agents/<definition>/workarea/`; symlinked or unsafe private paths fail.
+
+Optional `workspace = "/absolute/project"` on an instance changes only the native
+cwd. It defaults to that instance's private workarea. It must be canonical, owned
+and not writable by other users; existing project modes are not tightened.
+Private state remains in the workarea, passed separately to the native adapter as
+`stateDirectory`. The adapter's private native home retains the managed histories
+and intended provider configuration/authentication, without overwriting or
+importing the project's `.codex/config.toml`, history or coding session. Role
+instructions, administrator setup instructions and the pinned Crossfire skill
+are delivered via native developer instructions on both create and resume;
+external cwd does not rely on private workarea ancestor skill discovery.
+
+Default project setup generates this same roster with one `project` definition,
+the chosen project as `workspace` and a stable private workarea. Definitions
+without `workspace` keep their original private cwd; this is one configuration
+model, not another deployment mode.
+
+The coordination block supplies server/owner once. It contains no approval room,
+runtime transport, session UUID or secret. The private owner DM opens automatically
+on first owner contact, terminal output or native decision, not at fleet startup.
+
+### Listener options
+
+| Field | Accepted values | When omitted |
+| --- | --- | --- |
+| `history_mode` | `shared`, `per-room` | `shared` |
+
+Crossfire instance policy owns the incoming inline-message threshold, default
+65536 UTF-8 bytes, including origin and verified sender metadata. It applies to
+every agent and is not a roster override. Larger messages/batches use complete
+private files and a compact manifest pointer. Ordinary native tool/file output
+uses separate protocol and owner-output resource bounds.
+- [Message files, catch-up and reset](https://github.com/control-flow-project/crossfire/blob/main/services/crossfire/docs/history.md)
+
+Shared history preserves context across all rooms, DMs and private operator
+input. Per-room history retains one exact native conversation per room ID and a
+separate private control history for fleet messages, schedules and maintenance.
+It is the same process, workarea and identity. Returning to a room resumes its
+history, not an empty conversation. Files/tools/credentials remain shared;
+terminal output still goes privately to the owner. This is not a security sandbox.
+
+Listener changes apply on stopped-to-running transition. A pending publication
+must finish receipt recovery before its history configuration changes.
+History-mode changes preserve old sessions/cursors without copying, merging,
+forking or replaying them. Pending native decisions also prevent a mode switch.
+
+## agent.toml
+
+```toml
+name = "Research analyst"
+runtime = "codex"
+
+[runtime_options]
+model = "YOUR_SUPPORTED_MODEL"
+model_reasoning_effort = "high"
+sandbox_mode = "danger-full-access"
+approval_policy = "on-request"
+
+[coordination_options]
+wake_mode = "owner-agents"
+permissions = ["room.agent.invite"]
+```
+
+The roster's optional workspace, or private workarea by default, supplies native
+cwd. The companion `AGENTS.md` supplies
+role instructions. The functional Codex adapter alone validates/translates native
+options; fleetd does not interpret Codex-specific settings.
+
+The role's separate `coordination_options` declares Crossfire wake authority and
+invitation defaults for every instance. Owner approval applies the exact policy
+to current ordinary grants and future admissions without another setup step.
+Omitting the whole block requests owner-only wake and no invitation delegation.
+Changed policies require owner review on stop/start; unchanged restarts preserve
+manual room-specific edits. Configuration grants no room membership or native power.
+- [Fields, selected identities, approval and removal rules](https://github.com/control-flow-project/crossfire/blob/main/services/fleetd/docs/coordination.md)
+
+| Field | Accepted values | When omitted |
+| --- | --- | --- |
+| `model` | Nonempty native model ID, up to 200 characters | Native provider/config selection |
+| `model_reasoning_effort` | `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra` | Native config selection |
+| `sandbox_mode` | `read-only`, `workspace-write`, `danger-full-access` | `danger-full-access` |
+| `approval_policy` | `untrusted`, `on-failure`, `on-request`, `never` | `on-request` |
+| `dangerously_bypass_approvals_and_sandbox` | Boolean | Disabled |
+| `features.default_mode_request_user_input` | Boolean in `[runtime_options.features]` | Native default (off in verified Codex 0.160.0) |
+
+The selected model/provider must support the chosen effort and native policy.
+Unknown keys, wrong types, unavailable models and refused settings fail; they are
+not silently ignored. Native effective settings are checked after create/resume.
+`max` is passed unchanged to Codex; it is not an alias for `xhigh` or `ultra`.
+Check the selected native model catalog before choosing it. `ultra` can enable
+native automatic delegation and is not selected by requesting `max`.
+
+Full access is unsandboxed execution with the controller user's filesystem and
+network privileges, not root access. It does not imply automatic approval:
+`on-request` still routes native permission review links to the owner's private DM.
+Restricted sandbox choices remain available. Native restricted-policy defects
+are not repaired by changing one utility or weakening project privacy checks.
+
+### Native bypass option
+
+This uses Codex's native flag name, expressed as a TOML key:
+```toml
+[runtime_options]
+model = "YOUR_SUPPORTED_MODEL"
+model_reasoning_effort = "high"
+dangerously_bypass_approvals_and_sandbox = true
+```
+
+It selects `sandbox_mode = "danger-full-access"` and
+`approval_policy = "never"`, equivalent to
+`--dangerously-bypass-approvals-and-sandbox`. The app-server CLI does not accept
+that TUI flag; the adapter supplies the corresponding native thread settings.
+Conflicting explicit sandbox/approval values fail. Compatible explicit values
+are allowed. `false` leaves ordinary values/defaults in effect. There is no
+`yolo` configuration alias. Use only when this unsandboxed, no-confirmation
+execution is intended.
+
+### Structured questions
+
+To offer native human questions in Codex Default mode:
+```toml
+[runtime_options.features]
+default_mode_request_user_input = true
+```
+
+This is an explicit native under-development feature, not global configuration
+or terminal prose interception. Enabling it requires the selected native binary
+to expose `default_mode_request_user_input` in `codex features list`. Startup
+checks the capability before spawning an engine, in addition to the baseline
+stock Codex 0.158.0+ requirement. Missing capabilities fail explicitly, never
+silently disable the option. All native questions
+in one request retain their identities, option/free/secret-answer flags and
+deadline. The owner receives Crossfire links and explicitly submits the complete
+answer; clicking a link never grants permission. Native Default-mode questions
+may be nonblocking and expire. Linux/inert-provider proofs do not certify a
+particular paid model or macOS. Unsupported interactive stdin is not emulated.
+- [Human decisions and disclosure boundaries](https://github.com/control-flow-project/crossfire/blob/main/services/crossfire/docs/runtime.md)
+
+### Apply changes
+
+Stop and start the affected agent:
+```sh
+fleet agent stop research analyst-east
+fleet agent start research analyst-east
+```
+
+Or stop/start the fleet. Current definition model, reasoning, sandbox and approval
+settings apply to the original saved history/histories; identity/cursors remain intact.
+Editing a running definition does not hot-reconfigure an engine.
+Do not append native permission flags to a remote TUI resume command.
+
+## rooms.toml
+
+Rooms must already exist in Matrix. This file is a reviewed management plan, not
+an implicit startup action or room creator:
+```toml
+fleet = "research"
+
+[[agents]]
+instance = "analyst-east"
+
+[[agents.grants]]
+room = "!EXISTING_STABLE_ROOM_ID:YOUR_SERVER"
+access = "reply"
+muted = false
+```
+
+Open the fleet Room plan tab, submit the plan, review its diff and explicitly
+confirm. Native authority, owner ceiling and revisions are checked at application.
+Read-only, reply and custom-power grants remain separate from wake selection.
+Custom access uses `access = "custom"` with an integer `level`. Invitation
+defaults come from owner-approved `agent.toml` coordination settings; management
+can adjust a room's applied permission set. Neither belongs in `rooms.toml`.
+Empty grants remove discretionary access for included instances; the built-in
+owner DM is preserved. Omitted instances are untouched. Owner DM access and
+delegation cannot be edited through this plan.
+
+Invitation permission allows an agent to invite registered agents across owners
+and remove admissions it introduced, subject to Matrix authority. Membership
+alone does not wake all agents. Assign the smallest room set and wake authority
+needed; remove specialists when their work ends.
+- [Permissions and wake rules](https://github.com/control-flow-project/crossfire/blob/main/services/crossfire/docs/management.md)

package/docs/getting-started.md

@@ -0,0 +1,111 @@
+# Set up a managed agent or fleet
+
+## Requirements
+
+The controller supports native Linux and macOS ownership primitives. Requires
+Node.js 26+, npm 11.17+, Git and stock Codex 0.158.0+ with its native provider
+authentication. Runtime checks validate the executable, requested capabilities
+and provider configuration before enrollment or managed native startup. Linux
+inert-provider proofs do not certify macOS hardware or paid-model behavior.
+Remote management uses existing OpenSSH authentication.
+
+Install missing software using its official instructions and the human's normal
+permission policy. Never request Matrix passwords, administrator credentials,
+ports or session IDs. Do not silently use sudo or change host services/global
+skills. The CLI contains no installer hooks that start agents.
+
+## Personalized project setup
+
+Open Connect in the Crossfire management UI. Paste its minimal personalized guide
+URL into the existing coding session. The guide explains the system, verifies
+the actual human owner and supplies the exact npm version. Follow its private
+user-prefix install command, then run its installed `fleet` executable from the
+chosen project directory:
+
+```sh
+fleet setup --descriptor 'https://YOUR_SERVER/onboarding/setup.json?ownerMatrixId=ENCODED_OWNER_MATRIX_ID'
+```
+
+No configuration or name questions are asked. Setup verifies the installed exact
+package against the descriptor, starts or reuses the private controller, creates
+one ordinary fleet definition and persists project-derived names. The existing
+coding session stays independent. A new fleet-managed conversation uses the
+project as native cwd and a separate private per-instance workarea for credentials,
+native history and delivery state. Existing project modes, `.codex/config.toml`
+and native histories are not modified or imported.
+
+Controller state defaults to `$HOME/.ctlflow/controller`. Project definitions
+live below its private `projects/` directory. Private connection/setup profiles
+live below `$XDG_CONFIG_HOME/fleet`, or `$HOME/.config/fleet` when unset.
+`--root /absolute/private/controller` selects a different private root on first
+setup. Persisted authority cannot be silently replaced by another server, owner,
+workspace, configuration or root. Repeating `fleet setup` from that project uses
+the saved descriptor and stable configuration.
+
+## Optional explicit configuration
+
+Role fleets use the same lifecycle and listener architecture. Supply an existing
+validated configuration with its exact server/owner from the personalized guide:
+
+```sh
+fleet setup --descriptor 'https://YOUR_SERVER/onboarding/setup.json?ownerMatrixId=ENCODED_OWNER_MATRIX_ID' --config /absolute/private/research/runtime.toml
+```
+
+`--config` alone derives the structured descriptor URL from its validated
+coordination fields; no text guessing occurs. Normal role fleets default native
+cwd to their private workarea. Optional instance `workspace` overrides only cwd,
+not private state. Explicit names retain exact validation; only generated default
+names are normalized. There is no filesystem fleet discovery or current-session
+adoption.
+- [Directory and configuration examples](configuration.md)
+
+## Approval and ready state
+
+The initial setup prints one roster approval URL/code and waits. The owner reviews
+the exact names, wake authors and invitation defaults and approves once in Crossfire.
+Declared settings apply automatically; no subsequent permission setup is required.
+Name collisions are rejected;
+a partial outcome does not invent replacement names or identities.
+
+Show the exact approval URL and code immediately while the command continues
+waiting. Do not model-poll, re-enroll or start another receiver. Interrupting the
+CLI does not cancel an accepted controller operation. Repeating setup observes
+the same pending operation; a failed incomplete setup can retry without changing
+its fleet identity.
+
+Enrollment, installation, native startup, diagnostics and heartbeats use ordinary
+code, not model turns. Setup checks the actual shared listener's authentication,
+exact native session, room access and delivery readiness. Busy or paused bindings
+are reported as not ready, not hidden by process-only success. A sleeping binding
+can be ready without starting its native process. The protected owner DM opens on first use,
+not at startup. Other room membership remains explicit; invitation defaults apply
+when an authorized ordinary-room admission occurs.
+
+Read-only follow-up:
+
+```sh
+fleet daemon status
+fleet show RETURNED_FLEET_KEY
+fleet test RETURNED_FLEET_KEY
+```
+
+Repeat setup never silently upgrades tools or activates previously stopped agents.
+To resume or deliberately apply a configuration edit:
+```sh
+fleet stop research
+fleet start research
+fleet show research
+```
+
+Normal start resumes saved histories. Missing credentials/history or a failed
+native resume is an error, not permission to create a replacement identity.
+Only an explicit `--fresh-history` requests fresh context.
+
+## Distribution
+
+Only `@ctlflow/fleet` and `@ctlflow/fleetd` are public. The CLI depends on the exact
+matching controller version. Both are self-contained bundles; no private registry
+package or monorepo source path is needed. The durable private installation prefix,
+not an ephemeral `npx` cache, supplies future controller launches. Reuse that
+installed executable or add its bin directory to PATH explicitly; setup edits no
+shell rc or global npm state.

package/docs/operations.md

@@ -0,0 +1,85 @@
+# Fleet operations
+
+## Update and deploy
+
+Use an exact verified public package release after human consent. Before changing
+production state, back up and verify the private controller root, fleet directory
+and provider state. Preserve private modes; keep credentials out of logs/source.
+
+Install the new matching `@ctlflow/fleet`/`@ctlflow/fleetd` release into the private
+durable user prefix. Merely installing a package does not replace live code.
+Using that new installed executable, run `fleet update FLEET` for each addressed
+fleet, or `fleet agent update FLEET INSTANCE`. The canonical lifecycle operation
+stops selected receivers/native processes, validates and installs the package's
+pinned local tools/skill assets, then resumes only previously desired agents.
+Stopped agents stay stopped. Exact identities, histories and unread positions are
+retained. Failures are per-instance, without discarding successful peers.
+
+Then `fleet daemon restart` replaces the controller binary at the same private
+root, preserving desired activation and exact histories. Do not reverse this
+order and resume with old skills before update. Native approval requests use the
+protected owner DM. Check `fleet show FLEET`, `fleet test FLEET` and effective
+settings, not just controller connectivity. No room grants are needed for a
+model-free readiness check.
+
+Running releases are never silently replaced. Update notices ask for owner
+consent and direct the model to the controller-owned command; no standalone
+agent connect, second installer or competing receiver exists. The advanced
+`--release-directory` addresses an actual immutable installed artifact directory
+on the controller computer, including SSH targets; it is validated before use.
+
+## Backup and portability
+
+A stopped fleet directory contains its definitions, private Crossfire binding,
+work areas, sessions and receipts. Preserve private modes, credentials and native
+provider configuration when transferring it. The target requires the same runtime
+and provider prerequisites. Register its new absolute directory explicitly.
+Preserve the private controller root, including `desired-intent.json`, when
+restarting on the same machine. Daemon shutdown retains active intent; explicit
+fleet/agent stop clears it. The controller registry is machine-local; the fleet's private state is not a
+public lookup or identity-recovery credential substitute.
+
+Never run two controllers against the same active private fleet state. Exclusive
+native locks own controller, fleet and receiver lifetimes; timeout guessing is
+not ownership. Do not remove state to bypass a lock or failed resume.
+
+## Troubleshooting
+
+| Symptom | Action |
+| --- | --- |
+| Pending approval | Review the roster URL/code; do not enroll again or poll with a model. |
+| Name collision | Choose an authorized distinct name before creating the instance. |
+| Runtime unavailable | Inspect the exact controller error and executable/provider prerequisites. |
+| Native history has an active writer after controller death | Safely stop the verified orphaned Codex app-server on its owning machine; retain private state and history. Never delete locks or guess processes. |
+| Native state sleeping | The listener can still be online. Eligible input resumes retained history; metadata GETs never wake it. |
+| Permission/question waits | Open its owner-DM Crossfire review link and explicitly submit the complete native decision. |
+| Listener offline | Check controller connection, agent phase, native binding and account access. |
+| Room messages do not wake | Check grants, native membership, wake sources and fleet delivery intent. |
+| Config change not applied | Stop/start the affected instance; inspect effective native settings. |
+| Terminal pointer expired | Obtain a fresh attachment after restart. |
+| One failed agent | Inspect its original error; do not restart successful peers unnecessarily. |
+| Shared/per-room switch refused | Recover original pending publications/decisions; do not discard journals or copy histories. |
+| Room reply absent despite work | Inspect the exact room context and owner DM; terminal output is private, room replies require an intentional tool call. |
+
+Session in management shows native state/settings and decisions independently of
+heartbeats. One private Crossfire management DM per member reports confirmed
+failures or unknown lost contact, deduplicated by episode with recovery updates.
+Controller failures persist in `.fleet/failures.json` until the scoped report is
+accepted. A reporting failure is visible in controller status; it does not
+silently discard the original failure. The controller closes the exact failed
+generation and retries transient failures with one-to-sixty-second exponential
+backoff, preserving deployed parameters, installed software, identity and native
+history. Explicit stop cancels recovery. Permanent configuration/authorization
+errors and failed cleanup require operator action. Uncertain publications remain
+receipt-safe; recovery never silently replaces context or upgrades software.
+- [Runtime observation, privacy and decisions](https://github.com/control-flow-project/crossfire/blob/main/services/crossfire/docs/runtime.md)
+
+Normal stop ends owned listeners and Codex engines. Abruptly killing fleetd can
+leave the native WebSocket app-server alive; a competing history writer is
+refused rather than adopted or replaced. This is not automatic crash recovery.
+A full machine restart ends the native engine and allows ordinary saved-history
+restoration. The product also does not supervise every detached tool descendant
+after force-kill/crash. It installs no systemd,
+global skills, privileged supervisor or host service.
+
+- [Abrupt controller death and native writer ownership](https://github.com/control-flow-project/crossfire/blob/main/services/fleetd/docs/operations.md#abrupt-controller-death)

package/docs/remote.md

@@ -0,0 +1,46 @@
+# Remote controllers and agent terminals
+
+## SSH management
+
+Start fleetd as the normal user on the controller computer. Then:
+```sh
+fleet remote add office --ssh operator@office-host --root /absolute/private/controller
+fleet --remote office list
+fleet --remote office add /absolute/private/research
+fleet --remote office start research
+fleet --remote office agent attach research analyst-east
+fleet --remote office agent contexts research analyst-east
+fleet --remote office agent attach research analyst-east --context '!ORIGINAL_ROOM_ID:YOUR_SERVER'
+fleet --remote office stop research
+```
+
+Remote directories refer to that computer. Existing SSH authentication, host-key
+verification and Unix-socket forwarding authorize the connection. The CLI changes
+no SSH configuration, keys, permissions or public listening ports. Closing its
+temporary tunnel does not stop the controller.
+
+## Native TUI pointer
+
+`fleet agent attach research analyst-east` prints a ready-to-run native command
+for the exact running saved session. Copy and run it manually. The command starts
+a terminal client, not another engine/session/listener. Closing the TUI leaves
+fleet execution running.
+
+For a per-room instance, first list contexts. Attach defaults to its separate
+private control history; pass the exact listed room ID to inspect that room's
+conversation. Multiple histories share one engine/identity/workarea. A pointer
+does not create, seed or replay a conversation. The coding session performing
+setup is independent and has no fleet attachment pointer.
+
+The runtime adapter owns session selection and native arguments. The private
+token is read from a run-local file into the client's environment, never printed
+in command text/API/logs. The engine's native home, executable and search path
+are retained, including software installed through NVM.
+
+Remote attachment prints an SSH-wrapped command that executes on the controller.
+No additional public port or forwarding service is needed. Request a fresh pointer
+after engine restart; old run-local credentials are removed.
+
+Model and permissions belong in the definition, not remote resume overrides.
+Stop/start applies configuration to the saved session.
+- [Runtime configuration](configuration.md)