@ours.network/fleet 1.2.0-nightly.7 → 1.2.0-nightly.71

package/README.md

@@ -10,8 +10,9 @@ turns such sessions into **roles**: long-lived agents that
 
 - **run through structured managed sessions** behind one provider-neutral
   agent-session interface, which you can inspect or prompt,
-- are **supervised** — systemd (Linux) or launchd (macOS) restarts them on crash
-  and brings them back after a reboot,
+- are **supervised** — one Fleet systemd service (Linux) or LaunchAgent (macOS)
+  runs their existing agent runners, restarts them on crash, and restores the
+  desired running roster at boot or login,
 - **resume their context** across restarts (when the harness supports it),
 - **bind an ours.network identity**, so you — and every other agent — can message
   them by name over an end-to-end-encrypted channel
@@ -44,11 +45,11 @@ brain: { inline: { harness: codex, session: codex-app-server } }
 
 ```
 ~/fleet.yaml + ~/fleet/{agents,agent_templates,roles,brains,room_templates}/*.yaml   your declaration
-        │  ours-fleet up
+        │  ours-fleet init, then up
         ▼
-briefing.md per role  ──►  agent session adapter  ──►  native app-server or ACP transport
-        ▲                        │
- systemd --user / launchd ───────┘   restart on crash, start at boot/login
+one Fleet OS service  ──►  private member catalog + existing agent runners
+                                               │
+briefing.md per member  ──►  session adapter  ──►  native app-server or ACP transport
 ```
 
 Each role gets a state dir (`~/.ours-fleet/agents/<Name>/`) holding its briefing,
@@ -62,9 +63,9 @@ The state dir contract:
 
 | File | Owner | Lifecycle |
 |---|---|---|
-| `briefing.md` | generated | rewritten on every `up`/`restart`; never hand-edit |
-| `WORKLOG.md` | the agent | seeded empty, agent-appended; survives restarts |
-| `ROUTINES.md` | operator / agent | **optional** recurring-work instructions; re-read at the start of every wake, hot-editable **without a restart**; absence means "no routines" |
+| `briefing.md` | generated | rewritten on every `up`/`restart`; never hand-edit; the agent reads it once per model session, not per turn or wake |
+| `WORKLOG.md` | the agent | seeded empty, agent-appended; survives restarts; read back once only when a new conversation starts after a restart and it records previous work |
+| `ROUTINES.md` | operator / agent | **optional** recurring-work instructions; read once per session for concrete work, hot-editable **without a restart** — tell the agent it changed so it rereads; absence means "no routines" |
 | `.identity`, `.cwd`, `.session-id`, `.booted`, `.exit-status`, `.config-path` | supervisor | dot-marker state — session resume and boot bookkeeping |
 | `.monitor-state.json`, `.monitor-status` | supervisor monitor | atomic body-free cursor/pending state and health |
 | `.owner-channel-state.json` | owner-channel bridge | bounded wire-ID dedupe only; never message/reply plaintext |
@@ -79,11 +80,12 @@ The state dir contract:
 |---|---|---|
 | Node ≥ 22 | runs `ours-fleet` and its maintained adapters | nodejs.org, `apt`, or `brew` |
 | a harness CLI, logged in | the agent itself | e.g. Claude Code (`claude`) or Codex CLI (`codex`) |
-| `ours` CLI + shared daemon | identity + agent-to-agent messaging | `npm i -g @ours.network/cli@2.8.1-nightly.7 @ours.network/daemon@3.8.1-nightly.1 && ours-daemon start` |
+| `ours` CLI + shared daemon | identity + agent-to-agent messaging | `ours-install client --config /absolute/private/profile.json --integrations fleet --fleet-settings /absolute/fleet-settings.json` |
 
-Linux only: `ours-fleet init` enables *linger* so roles run without a login session
-and survive reboots. macOS: launchd agents start **at login** (no linger
-equivalent); logs land in `~/.ours-fleet/logs/`.
+Linux only: `ours-fleet init` enables *linger* so Fleet runs without a login session
+and restores running members after reboot. On macOS the Fleet LaunchAgent starts
+**at login** (no linger equivalent). Member logs live in each member's state
+directory; use `ours-fleet logs <Name>` to read them.
 
 ## Install
 
@@ -103,6 +105,12 @@ maintained adapters require Node 22 or newer.
 Each OS user manages their own fleet — to host roles under a sandboxed account,
 become that account and repeat.
 
+When upgrading from per-agent services, coordinate package installation with
+explicit `ours-fleet init`. Preserve operator readiness hooks on the common
+parent before migration; new task/temporary creation requires that parent.
+See the [migration and rollback runbook](docs/fleet-migration.md)
+for changed stop/restart behaviour and legacy task transfer limits.
+
 ## Quickstart
 
 ```sh
@@ -139,72 +147,60 @@ the caller's owner channel with the caller and spawned-role details. This is an
 honest-actor convenience and attribution path, not a security boundary; host
 shells and deliberately bypassed absolute binaries retain direct behavior.
 
-## Local web console
+## Local HTTP service
 
-The interactive console is packaged with `@ours.network/fleet` and binds to
-IPv4 loopback by default. Remote or proxy exposure is always explicit:
+Fleet is an HTTP backend. It serves no pages, bundles no frontend and opens no
+browser: every screen belongs to the App, which calls this API with a device
+credential. Any address outside `/api/` answers JSON `404`.
 
 ```sh
-npm run build
-ours-fleet web
+ours-fleet setup-tunnel <encoded-v2-grant> # App command; prints QR and connection code
+ours-fleet link-device                 # connect another browser or device
 # choose a free port for an isolated test:
-ours-fleet web serve --port 0 --no-open
-# nginx/TLS terminates at the declared browser origin; fleet remains loopback-bound
+ours-fleet web serve --port 0
+# nginx/TLS terminates at the declared origin; fleet remains loopback-bound
 ours-fleet web install --public-origin https://fleet.example.com --password-file /secure/fleet-password
-# Intentional no-password mode, for example when nginx already authenticates:
-ours-fleet web install --public-origin https://fleet.example.com --no-password
 ```
 
-The normal `ours-fleet web` command installs or updates an owner-level native
-service, starts it on stable `127.0.0.1:49271`, and opens/re-pairs the browser.
-Linux uses a systemd user unit and macOS uses a LaunchAgent; both restart after
-process failures and send logs to the native supervisor. Service management is
-explicit through `ours-fleet web install|start|stop|restart|status|uninstall`.
-Use `ours-fleet web serve` for a foreground development process. Linux login
-persistence requires linger; the installer reports when it is missing but
+`ours-fleet web` installs or updates an owner-level native service and starts
+it on stable `127.0.0.1:49271`. Linux uses a systemd user unit and macOS uses a
+LaunchAgent; both restart after process failures and send logs to the native
+supervisor. Service management is explicit through
+`ours-fleet web install|start|stop|restart|status|uninstall`. Use
+`ours-fleet web serve` for a foreground development process. `--no-open` is
+still accepted because installed service units pass it; it has no effect. Linux
+login persistence requires linger; the installer reports when it is missing but
 never enables it or requests root privileges.
 
-The normal command opens a one-time five-minute fragment directly in the local
-browser; it does not print a reusable secret. If the browser needs pairing
-again while the server is running, use `ours-fleet web open`. The fragment is
-exchanged once and removed from history. A paired browser receives a rotating,
-30-day `HttpOnly; SameSite=Strict` device credential and can return after a
-session idle timeout or server restart. Use **Sign out** to revoke the current
-browser, or `ours-fleet web revoke-all` to revoke every trusted browser and
-active web session.
-
-Only a domain-separated SHA-256 device-secret hash and bounded timestamps are
-stored in the owner-private fleet state directory (`0700` directory, `0600`
-atomic file). The re-pair and revoke controls use an owner-private Unix socket;
-local processes running as the same OS user are therefore inside the trust
-boundary.
+Use `ours-fleet web revoke-all` to revoke every linked device and active
+session. Only a domain-separated SHA-256 device-secret hash and bounded
+timestamps are stored in the owner-private fleet state directory (`0700`
+directory, `0600` atomic file). App browser links use 5-minute access
+credentials and rotating refresh credentials; see
+[workspace onboarding](docs/workspace-onboarding.md#browser-link-credentials). The link and revoke controls use an
+owner-private Unix socket; local processes running as the same OS user are
+therefore inside the trust boundary.
+
+The read-only [conversation event stream](docs/conversation-stream.md) documents
+authentication deadlines, replay coverage, bounded framing and filesystem support.
 
 On first setup, the CLI requires an explicit access choice: `--password-file`
 or `--pairing` for protected access, or `--no-password` for intentional
 unprotected access. `--password-file` stores only a salted scrypt verifier in
-the owner-private web state; the source file remains operator-managed. New
-browsers sign in and then receive the same rotating HttpOnly trusted-device
-credential. `--no-password` is deliberately named and prints a warning: anyone
-who can reach that origin can control the fleet.
+the owner-private web state; the source file remains operator-managed.
+`--no-password` is deliberately named and prints a warning: anyone who can
+reach that origin can control the fleet.
 
 For nginx on a VPS, keep the default loopback bind and set the exact external
 `--public-origin` (scheme, hostname, optional port). nginx should proxy HTTP and
 WebSocket upgrades to `127.0.0.1:49271` and provide TLS; rewriting the upstream
-Host is not required because the declared browser Origin remains authoritative. To listen beyond
+Host is not required because the declared Origin remains authoritative. To listen beyond
 loopback, add an explicit `--bind`; fleet refuses a non-loopback bind without a
 public origin. Host and Origin validation use that declaration rather than
 trusting forwarded headers. `localhost` and `127.0.0.1` both work in normal
-local mode; an unconfigured hostname gets a self-describing HTML page instead
-of raw internal Host-header JSON.
+local mode; an unconfigured hostname is refused with a JSON error.
 
-The console is installable as a standalone PWA. Its service worker caches only
-the data-free offline page and successful content-hashed JavaScript/CSS assets.
-HTML stays network-first and no API, authentication, bootstrap, device,
-WebSocket, terminal, event, audit, log, session, query-bearing, or error response
-is cached. When the local daemon is unavailable, the PWA shows an explicit
-offline shell and no stale fleet state.
-
-The console provides evidence-separated inventory and status, ACP activity and
+The API provides evidence-separated inventory and status, ACP activity and
 permission controls, redacted logs, typed text send, confirmed lifecycle
 actions, and transactional permanent/temporary creation. Identity is fixed to
 the role name. Creation uses the authenticated
@@ -303,10 +299,56 @@ ours-fleet loops reload <Role>
 ours-fleet loops run-now|disable|enable <Role> <Loop>
 ours-fleet rm <Name>
 ours-fleet doctor [--harness H]
+ours-fleet service check|refresh [--json]   service definitions vs this release (refresh never starts or restarts)
+ours-fleet managed-cli setup [--enable <Agent>]... | status [--json]   native harness policy for the task workflow
 ours-fleet version [--json]         build identity, capabilities, installs on PATH
 ours-fleet init
 ```
 
+### Fleet task commands from a harness command sandbox
+
+A Codex or Claude command sandbox refuses the supervisor socket, so a managed
+`ours-fleet` call fails with `connect EPERM` before it parses anything. Fleet
+prepares the native harness policy for the packaged Coordinator task workflow;
+you do not write Codex rules or Claude sandbox settings by hand:
+
+```sh
+ours-fleet managed-cli setup --enable FleetCoordinator   # adds managed_cli: [task-workflow] to that Agent
+ours-fleet managed-cli status                            # static setup, session policy, observed commands
+```
+
+The opt-in is an explicit Agent key and changes no permission. Setup starts no
+session or model, is repeated at every agent start, and `ours-install` runs it
+for you. It prepares `task create|start|finish|block|unblock|review|list|show`,
+`room show|members` and template/plan/help inspection for one pinned
+configuration, and nothing else; `task start`/`task finish` are real authority.
+Qualified end to end on Linux with Codex (native and ACP) and Claude ACP; macOS
+is prepared the same way but not yet qualified. Scope, boundaries, unsupported
+combinations and the evidence are in
+[docs/validation/managed-cli-permissions.md](docs/validation/managed-cli-permissions.md).
+
+### Service definitions after an update
+
+`ours-fleet init`, `web install` and the watchdog installer write user service
+definitions (systemd units on Linux, LaunchAgents on macOS) that start the exact
+release tree they were written from. An update installs a new tree, but a running
+service keeps its code, and an unrefreshed definition starts the previous release
+again after the next reboot while agents and the CLI use the new one.
+
+```sh
+ours-fleet service check     # read-only; exit 1 when a definition or running service uses another release
+ours-fleet service refresh   # re-point existing definitions at this release
+```
+
+`refresh` changes only the release paths in definitions Fleet generated. It keeps
+environment, profile, ports and drop-ins, runs `daemon-reload`, and never creates,
+enables, starts, stops or restarts a service. Definitions that Fleet did not
+generate, or whose `ExecStart` a drop-in overrides, are reported and left alone.
+A running supervisor still uses its old code until you restart it
+(`systemctl --user restart ours-fleet.service`); its agents resume through it.
+`ours-install` runs `refresh` after updating Fleet, and `doctor` shows the same
+rows as `check`.
+
 ### Which build am I running?
 
 `--version` prints a semver, and a semver does not identify an artifact: version
@@ -325,9 +367,9 @@ Installs predating the stamp are compared by hashing their `dist/`, so two of
 those are still told apart.
 
 A permanent role brought up via `-c custom.yaml` remembers that file (`.config-path`
-in its state dir) across supervisor-triggered restarts — systemd/launchd re-invoke the
-agent process with no arguments, so without this the role would silently fall back to
-the default `~/fleet.yaml` on its very first crash-restart and fail to resolve.
+in its state dir and its private member registration) across supervisor-triggered
+restarts. Its runner resolves that original configuration instead of falling back
+to the default `~/fleet.yaml`.
 
 ## split configuration field reference
 
@@ -376,9 +418,9 @@ preserve at most one recent late occurrence. The trusted authoring file and
 private sealed role snapshot retain exact prompt text; resolved launch, task,
 room, provenance, and audit presentation surfaces show only bytes and SHA-256.
 
-Every packaged `Developer`, `Critic`, and `LocalCoordinator` Agent Template uses
+Every packaged `Developer`, `Engineer`, `Critic`, and `LocalCoordinator` Agent Template uses
 `monitor.mode: fleet` with `monitor.interrupt: after_tool`. Consequently every
-member of the standard `single`, `pair`, and `team` Room Templates resolves to
+member of the standard `single`, `pair`, `team`, and `engineering` Room Templates resolves to
 that policy. A custom Agent Template or explicit per-member override remains
 authoritative and is merged key by key without rewriting unrelated values.
 
@@ -524,7 +566,7 @@ ours-fleet up
 
 ### Rooms and tasks
 
-Init installs editable `single`, `pair`, and `team` definitions under
+Init installs editable `single`, `pair`, `team`, and `engineering` definitions under
 `~/fleet/room_templates/`, plus every exact-cased Agent, Role, and Brain they
 reference. Inspect them with `ours-fleet template list` and
 `ours-fleet template show team`. After configuring the authenticated owner below:
@@ -533,8 +575,25 @@ reference. Inspect them with `ours-fleet template list` and
 ours-fleet task create --title "Solo task" --template single
 ours-fleet task create --title "Reviewed change" --template pair
 ours-fleet task create --title "Phased delivery" --template team
+ours-fleet task create --title "Gated feature build" --template engineering
 ```
 
+`engineering` pairs a gate-pipeline `Engineer` with the standard `Critic`. The
+Engineer works every non-trivial task through ordered gates — scope and a numbered
+Definition of Done before code, an over-engineering check, spec before
+implementation, test-first, review, a sized security pass, docs, and evidence-backed
+DoD verification — invoking an installed gate-pipeline skill when one is present and
+walking the same gates by hand otherwise. The seat is labelled `Engineer`, so a
+gated seat is never mistaken for a plain `Developer`. To make it the default for
+development tasks, set `tasks: { default_room_template: engineering }` in
+`fleet.yaml`.
+
+The `engineering` starter expresses a prompt-level workflow mandate; Fleet does not enforce
+the gates at runtime or install pipeline skills. The Engineer label identifies that mandate,
+not a completed review. When migrating an existing install, a newly added Engineer uses
+the existing Developer template's brain selection and keeps the packaged restrictive permissions.
+Existing customized Engineer files are preserved.
+
 The default `team` gives only its LocalCoordinator Agent Template a 15-minute
 continuity loop. Each idle-only pass uses authenticated assigned-room evidence,
 posts at most one missing interval update or status request, and reports `STALLED`
@@ -588,8 +647,9 @@ non-owner-controlled parent fail closed before host setup and are rechecked unde
 per-setup init lock before publication.
 
 The generated task experiences are fixed consequences, not extra questions: `single`
-uses `Developer`; `pair` uses `Developer` with an independent `Critic`; and `team` uses
-task-local `LocalCoordinator`, `Developer`, and `Critic`. The persistent
+uses `Developer`; `pair` uses `Developer` with an independent `Critic`; `team` uses
+task-local `LocalCoordinator`, `Developer`, and `Critic`; and `engineering` uses the
+gate-pipeline `Engineer` with an independent `Critic`. The persistent
 `FleetCoordinator` uses the separate packaged `Coordinator` contract and coordination
 model.
 
@@ -666,6 +726,29 @@ continuation is serialized per Task and remains alive until convergence or an
 Owner-action blocker. Re-running `task start <id>` safely resumes the same durable
 provisioning operation after the blocker is corrected or a process restarts.
 
+Live health is distinct from durable lifecycle. `task show TASK --json` adds a
+`readiness` observation for active tasks (`ready`, `degraded`, or `unknown`); human
+and authenticated Owner task-show output display the same observation. Task start/work
+continue to reject unavailable health with `task_not_ready`. A same-role untracked
+seat or a changed recorded launch cannot satisfy an original slot. Each control,
+liveness, and production Cowork probe is bounded; members are checked sequentially,
+so total latency grows with room size. These are point-in-time observations, not
+proof that a timed-out session is dead or permission to respawn it.
+
+Before deliberate recovery, Fleet Coordinator must inspect existing room seats and
+the exact old launch's termination record and worklog under `recovery/temporary`.
+Keep original slot records and archives intact; record verified old/new identity
+and launch provenance privately. Never restore archived identity state or reuse
+consumed invites. A same-role seat is only a possible replacement, not proven ownership.
+
+A replacement's empty inbox does not establish that no work is pending. Paginate
+scoped room/operator history to the end, retain the cursor privately, authenticate
+historical Owner instructions from identity metadata, and compare replies, worklogs,
+and already-completed actions before resuming. Ask the Owner when authority or
+completion is uncertain. Transfer only necessary non-secret context; never replay
+instructions blindly. Observation does not adopt seats, launch replacements, change
+lifecycle, or modify retained recovery evidence.
+
 Set `room.anonymous: true` on a room template, or pass `--anonymous` to
 `task create`, `task start`, `task work`, or `room create`, to create an
 anonymous Cowork room. `--no-anonymous` explicitly overrides an anonymous
@@ -1348,8 +1431,9 @@ The command override is exact: Fleet does not append `--profile`, `--search`, or
 
 One-off/permanent spawn selects a Brain that owns model, reasoning, native permission,
 sandbox, profile, launcher, search, monitor consent, native config, and additional roots.
-Use `env.OURS_PORT`/`env.OURS_CONFIG` for a
-role-specific ours daemon, or configure the host default in `~/.ours/config.json`.
+All roles use the shared gateway profile `~/.ours-client/profile.json`.
+`OURS_CONFIG` selects an alternate whole profile. Legacy port/token/state-dir
+overrides are rejected. See the [gateway setup guide](https://github.com/adapt-toolkit/ours-network/blob/prerelease/packages/installer/GATEWAY_SETUP.md).
 
 ## Agent isolation
 
@@ -1750,3 +1834,130 @@ outcome: inspect state before retrying, because there is no automatic retry or
 exactly-once guarantee. Contact acceptance alone does not prove peer verification
 or message delivery. File tools resolve paths in the invoking CLI process or
 Fleet web server's filesystem context, with that process's access permissions.
+
+Task workspace ownership, retention, safe deletion and legacy migration are documented in [Task workspaces](docs/task-workspaces.md).
+
+### Active task readiness after interruption
+
+Task and room list states, and `taskProvisioningOutcome`, describe durable lifecycle
+and provisioning progress; they are not live health checks. Retrying `task start`
+or `task work` on an active task checks the current Cowork room identity and seats,
+member launch ownership, supervisor liveness, and authenticated session status
+before reporting success. Waiting for provisioning completion also checks live
+readiness. This is a point-in-time observation, not proof of an agent-authored reply.
+
+A `task_not_ready` result distinguishes confirmed degradation from unknown health
+(for example, an unavailable control socket). Ask Fleet Coordinator to inspect room
+and member status and choose supported recovery. These checks do not restart agents,
+recreate identities, redeem invites, or rewrite lifecycle state. Temporary room agents
+remain transient across host reboot; retained launch records do not restore them.
+
+See [predefined Brain models and runtime requirements](presets/README.md) for the verified model/effort matrix and regeneration instructions.
+
+### YAML room layouts
+
+Room layouts describe room composition with shared or fresh participant sessions and independent room closure.
+See [Room layouts](docs/room-layouts.md) for YAML examples and CLI commands.
+
+
+### Dedicated notification service
+
+Configure the web backend with `OURS_NOTIFICATIONS_ORIGIN` and a Fleet-scoped `OURS_NOTIFICATIONS_PRODUCER_TOKEN`. It reads each local supervisor ledger incrementally with persistent checkpoints under web state, correlating owner browser/channel prompts with terminal completion. Monitor/startup turns do not notify. First installation skips existing history; no agent restart or conversation controller is needed. Persist web state across deployment/restarts. Reads are bounded to 256 KiB per role per tick, and oversized model/media records are skipped across chunks. Expose `/notifications` through the generic authenticated prefix gateway with a server-side user token and `stripBrowserContext: true`; producer tokens stay server-side. All browser sessions of this single-owner console map to one stable notification account. See [ours-notifications](https://github.com/adapt-toolkit/ours-notifications) for configuration/API/release details.
+
+New agent notifications and confirmed role retirement use `/fleet/chats/agents/:roleId`, with each ID escaped once and matching message anchors retained. Deploy the app, notification service, and producers together: old query-based conversation links are intentionally unsupported. Existing pending payload URLs are replayed unchanged for idempotency; obsolete cleanup targets remain stored without being sent or treated as proof of absence. Task management notification paths are unchanged.
+
+
+Existing-host enrollment: `ours-fleet workspace-enroll --file <private-file> --preserve-profile` requires Messenger to advertise preservation support before any enrollment POST. It omits Name/Surname and leaves existing/absent profile untouched. Existing Fleet models and agents are retained; the installer must skip init when its configuration exists. Signed root proof, tunnel setup and device QR issuance remain the normal enrollment flow. Older Messenger fails closed and requires its preservation-capable release.
+
+### Connect an installed host to the App
+
+Install Ours network first. In the App's tunnel step, copy the single command and
+paste it on the intended host, including in an SSH session on a VPS:
+
+```sh
+ours-fleet setup-tunnel <encoded-v2-grant>
+```
+
+The base64url argument contains only the existing v2 grant: `version: 2`, allowed
+`appOrigin`, one-use `code`, and `expiresAt`. It names the workspace indirectly
+through a server-held grant; it includes no broad Cloudflare credential or
+installer script. The grant can appear in shell history and process listings:
+keep the command private and remove it from history after use. Base64 is encoding,
+not encryption. The server enforces its short expiry and one-time redemption.
+Fleet never prints the grant; it checks host prerequisites before redeeming it
+over HTTPS POST, with the code in the body rather than a URL. The response supplies
+only the existing scoped connector and signed-root enrollment data; authorization,
+account-origin checks and private connector token-file storage remain enforced.
+
+Optional private transports remain available: `setup-tunnel --file /private/grant`
+requires an owned regular file with mode 600; `setup-tunnel --stdin` reads a secure
+pipe with a 32KiB limit and refuses a terminal. Legacy v1 payloads, which contain
+long-lived scoped credentials, are accepted only through file/stdin, never as
+command arguments. Use only one payload transport.
+
+When this host already has a registration, Fleet inspects the one-use grant without
+consuming it. The same workspace reruns without a deletion prompt or retirement.
+An account-origin change for that workspace requires `--migrate-app-origin`; a
+changed server identity is refused. An older App without inspection support falls
+back to asking before redemption. An unavailable inspection service preserves the
+grant and setup. Fleet verifies the redeemed destination against the inspection.
+
+For another workspace, setup describes the existing workspace, tunnel hostname and
+account origin and asks `[y/N]`. No answer or `no` preserves the setup and grant; a
+noninteractive caller must pass `--replace-registration`, otherwise it exits with
+an error. A legacy binding without a server identity must rerun its own workspace
+first. The original Human root signs retirement. Fleet waits for the account's
+durable cleanup receipt before stopping the old service and revoking its linked
+devices. If a migrated database has no old registration, the signed command confirms
+absence; the service has no old provider resources to delete. Installation identities,
+profile, agents, history, stable host ID and local pairing are preserved.
+
+Replacement recovery is saved in an owned private `workspace/replacement.json`
+after root, host, service and server-contact preconditions pass. The App must
+explicitly support deadline-enforced retirement; an older App without that
+capability preserves the existing setup. `setup-tunnel --resume` retries its nonce
+and saved operation deadline (24 hours less a five-minute clock margin).
+If the enrollment challenge expires, obtain a fresh App command for the same target
+and pass `--replace-registration`; completed retirement is retained. The old server
+identity is pinned: only its own invitation can reconnect it.
+
+`setup-tunnel --abandon-replacement` removes the private recovery payload only when
+a fresh private receipt confirms no deletion and the operation was never dispatched
+or was terminally rejected. A lost transport response remains uncertain. Expired
+operations require a fresh receipt proving the old binding still exists after the
+deadline plus five minutes and an explicit server guarantee that the deadline is enforced;
+older recovery records without that guarantee must be resumed. Abandoning preserves
+the existing binding, connector and installation data. A terminally rejected operation
+requires abandonment and a new App command, rather than reusing its nonce.
+After that deadline, a fresh command for the same target can also resume with a
+new operation nonce after checking the enforced expiry. This confirms signed
+absence if an old successful receipt was lost and later pruned.
+
+If the App accepted the successor proof before Fleet wrote its local binding,
+a fresh command for that target retains the original private connector from the
+recovery record. If that successor cannot be recovered, remove it in the App,
+then use `setup-tunnel --discard-retired-replacement` and a fresh App command.
+Discard is allowed only after retirement and local cleanup, while the old local
+binding remains. It removes only the recovery record. This host has no working
+registration until the new setup completes; the old service was stopped and its
+linked devices revoked.
+
+Renewal commands contain no existing live connector credential. Fleet keeps the
+current private connector byte for byte, and accepts renewal only for its recorded
+workspace, server, origin and tunnel hostname. Restore a missing or unsafe connector,
+or remove and re-create that workspace in the App before setting it up again.
+
+After service and signed tunnel-target confirmation, setup prints both a QR and
+ordinary private single-use connection code. The App checks readiness automatically
+and immediately opens the code field. If setup or code output fails after binding,
+fix the reported problem and run `ours-fleet setup-tunnel --resume`; its private
+pending record remains until the code is printed, including confirmed nondefault
+ports. `ours-fleet link-device` still generates another code for additional browsers
+or expired codes. `--check` checks prerequisites without consuming a grant.
+
+Prerelease rollout requires this Fleet capability to be published first, then the
+installer's normal generated version/integrity lock updated, then installer and
+App released. The currently pinned Fleet nightly.41 does not support v2 grants.
+These source changes do not publish, merge, or deploy any component.
+
+See [ACP file sending](docs/acp-files.md) for the same-chat `send_file` flow, available to every Agent by default, and its supported sessions.

package/dist/account-origin.d.ts

@@ -0,0 +1,2 @@
+export declare const accountOrigins: readonly ["https://app.ours.network", "https://app.ours-tunnel.com"];
+export declare function validateAccountOrigin(value: unknown): string;

package/dist/account-origin.js

@@ -0,0 +1,6 @@
+export const accountOrigins = ['https://app.ours.network', 'https://app.ours-tunnel.com'];
+export function validateAccountOrigin(value) {
+    if (typeof value !== 'string' || !accountOrigins.some(origin => origin === value))
+        throw Error('Unsupported account origin');
+    return value;
+}

package/dist/agent-ours/bridge.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { openChatFile } from '../file-delivery/reader.js';
 import { createHash } from 'node:crypto';
 import { connect } from 'node:net';
 import { access, mkdir, open, readFile } from 'node:fs/promises';
@@ -6,6 +7,9 @@ import { constants } from 'node:fs';
 import { basename, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { MAX_CHUNK_BYTES, MAX_FRAME_BYTES, Wire } from './wire.js';
+/** A current-chat refusal the agent may see; it names a reason, never a path or content. */
+class ChatFileError extends Error {
+}
 /** Runs inside exactly the harness OS sandbox. Only this process opens agent paths. */
 export async function runBridge(descriptorPath) {
     const descriptor = JSON.parse(await readFile(descriptorPath, 'utf8'));
@@ -71,7 +75,7 @@ export async function runBridge(descriptorPath) {
                         value = false;
                     }
                 }
-                else if (op === 'read-open' || op === 'write-open') {
+                else if (op === 'read-open' || op === 'write-open' || op === 'export-open') {
                     if (handles.size >= 32 ||
                         typeof args.handle !== 'string' ||
                         handles.has(args.handle) ||
@@ -80,12 +84,20 @@ export async function runBridge(descriptorPath) {
                     const path = resolve(args.path);
                     if (op === 'write-open')
                         await mkdir(dirname(path), { recursive: true });
-                    const file = await open(path, op === 'write-open' ? 'w' : 'r');
-                    handles.set(args.handle, { file, call, write: op === 'write-open' });
-                    value =
-                        op === 'write-open'
-                            ? path
-                            : { filename: basename(path), size: (await file.stat()).size };
+                    if (op === 'export-open') {
+                        const opened = await openChatFile(process.cwd(), args.path).catch((error) => { throw new ChatFileError(error.message); });
+                        const stat = await opened.file.stat();
+                        handles.set(args.handle, { file: opened.file, call, write: false, original: { size: stat.size, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs } });
+                        value = { filename: basename(opened.path), size: stat.size, path: opened.path };
+                    }
+                    else {
+                        const file = await open(path, op === 'write-open' ? 'w' : 'r');
+                        handles.set(args.handle, { file, call, write: op === 'write-open' });
+                        value =
+                            op === 'write-open'
+                                ? path
+                                : { filename: basename(path), size: (await file.stat()).size };
+                    }
                 }
                 else {
                     const row = handles.get(args.handle);
@@ -105,6 +117,11 @@ export async function runBridge(descriptorPath) {
                             value = null;
                         }
                         else if (op === 'read' && !row.write) {
+                            if (row.original) {
+                                const stat = await row.file.stat();
+                                if (!stat.isFile() || stat.nlink !== 1 || stat.size !== row.original.size || stat.mtimeMs !== row.original.mtimeMs || stat.ctimeMs !== row.original.ctimeMs)
+                                    throw new ChatFileError('CHAT_FILE_CHANGED');
+                            }
                             const buffer = Buffer.alloc(MAX_CHUNK_BYTES);
                             const { bytesRead } = await row.file.read(buffer);
                             value = bytesRead ? buffer.subarray(0, bytesRead).toString('base64') : null;
@@ -129,8 +146,8 @@ export async function runBridge(descriptorPath) {
                 }
                 await wire.send({ kind: 'fs-result', id: raw.id, value });
             }
-            catch {
-                await wire.send({ kind: 'fs-result', id: raw.id, error: 'FILE_OPERATION_FAILED' });
+            catch (error) {
+                await wire.send({ kind: 'fs-result', id: raw.id, error: error instanceof ChatFileError ? error.message : 'FILE_OPERATION_FAILED' });
             }
         })
             .catch(fail);

package/dist/agent-ours/correspondence.d.ts

@@ -0,0 +1,10 @@
+/** Read-only operations exposed by the identity-owning supervisor. */
+export interface AgentHistoryQuery {
+    peer_cid: string;
+    limit?: number;
+    before_seq?: number;
+}
+export interface SupervisorCorrespondence {
+    contacts(): Promise<unknown>;
+    history(request: AgentHistoryQuery): Promise<unknown>;
+}

package/dist/agent-ours/correspondence.js

@@ -0,0 +1 @@
+export {};

package/dist/agent-ours/file-rpc.d.ts

@@ -11,11 +11,23 @@ export declare class FileCallbacks implements FileExecutionContext {
     private rpc;
     canRead(path: string, extra: ToolRequestExtra): Promise<boolean>;
     read(path: string, extra: ToolRequestExtra): Promise<{
+        path?: string | undefined;
         filename: any;
         size: any;
         body: ReadableStream<Uint8Array<ArrayBufferLike>>;
         close: () => Promise<void>;
     }>;
+    /** Current-chat source: integrity-checked by the bridge, with its real path. */
+    readChatFile(path: string, extra: ToolRequestExtra): Promise<{
+        path?: string | undefined;
+        filename: any;
+        size: any;
+        body: ReadableStream<Uint8Array<ArrayBufferLike>>;
+        close: () => Promise<void>;
+    } & {
+        path: string;
+    }>;
+    private openRead;
     write(path: string, body: ReadableStream<Uint8Array>, extra: ToolRequestExtra): Promise<{
         path: string;
         size: number;