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

package/dist/workspace-replacement.js

@@ -0,0 +1,220 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { validateAccountOrigin } from './account-origin.js';
+import { replaceFileAtomically } from './atomic-file.js';
+import { stateRoot } from './paths.js';
+import { decodeWorkspacePayload, enrollWorkspace, unregisterWorkspace, checkWorkspaceConnector } from './workspace-enrollment.js';
+import { WorkspaceDeviceStore } from './web/workspace-devices.js';
+import { webControlPath } from './web/control.js';
+import { WebServiceManager } from './web/service.js';
+const workspaceDir = () => join(stateRoot(), 'workspace');
+const replacementPath = () => join(workspaceDir(), 'replacement.json');
+const opaque = /^[\w-]{43}$/;
+function binding(value) {
+    if (!value || !opaque.test(value.workspaceId) || !opaque.test(value.hostWorkspaceId) || (value.serverCid !== undefined && !/^[a-f0-9]{64}$/i.test(value.serverCid))
+        || (value.proofRootCid !== undefined && !/^[a-f0-9]{64}$/i.test(value.proofRootCid)))
+        throw Error('Existing workspace binding is invalid; restore it before tunnel setup');
+    return { ...value, appOrigin: validateAccountOrigin(value.appOrigin ?? 'https://app.ours.network') };
+}
+export function readWorkspaceBinding() {
+    const file = join(workspaceDir(), 'binding.json');
+    if (!existsSync(file))
+        return;
+    let value;
+    try {
+        value = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw Error('Existing workspace binding is invalid');
+    }
+    return binding(value);
+}
+export function sameWorkspaceBinding(previous, payload) {
+    return previous.workspaceId === payload.challenge.workspaceId && previous.appOrigin === payload.appOrigin && (!previous.serverCid || previous.serverCid.toUpperCase() === payload.serverCid.toUpperCase());
+}
+/** A workspace ID is never retired to rerun or migrate that same workspace. */
+export function requiresWorkspaceReplacement(previous, target, migrateAppOrigin = false) {
+    if (previous.workspaceId !== target.workspaceId) {
+        if (!previous.serverCid)
+            throw Error('Legacy registration has no recorded server identity. Rerun its own workspace setup before replacing it');
+        return true;
+    }
+    if (previous.serverCid && previous.serverCid.toUpperCase() !== target.serverCid.toUpperCase())
+        throw Error('Same-workspace setup must retain the enrollment server identity; existing setup preserved');
+    if (previous.appOrigin !== target.appOrigin && !migrateAppOrigin)
+        throw Error('Account origin change requires explicit --migrate-app-origin; existing setup preserved');
+    return false;
+}
+/** Ask before redeeming the one-use grant, whose destination is deliberately opaque. */
+export async function confirmWorkspaceReplacement(previous, explicit = false, effects = {}) {
+    const write = effects.write ?? (value => { process.stderr.write(value); });
+    let hostname = '';
+    try {
+        const tunnel = JSON.parse(readFileSync(join(workspaceDir(), 'tunnel.json'), 'utf8'));
+        if (typeof tunnel.origin === 'string' && /^https:\/\/[a-z0-9][a-z0-9-]{2,60}\.ours-tunnel\.com$/.test(tunnel.origin))
+            hostname = ` (${new URL(tunnel.origin).hostname})`;
+    }
+    catch { }
+    write(`This host is registered to workspace ${previous.workspaceId}${hostname} at ${previous.appOrigin}.\nReplacing it removes the old account registration and revokes its linked devices. The account service retires tunnel resources it knows; a migrated database may have no old resources to delete. Installation identities, agents and data are preserved.\n`);
+    if (explicit)
+        return true;
+    if (!(effects.interactive ?? process.stdin.isTTY)) {
+        write('Existing setup preserved. Run in a terminal to confirm, or pass --replace-registration to confirm explicitly.\n');
+        return false;
+    }
+    const ask = effects.ask ?? (async () => {
+        const terminal = createInterface({ input: process.stdin, output: process.stderr });
+        try {
+            return await terminal.question('Replace the existing registration if this command names another workspace? [y/N] ');
+        }
+        finally {
+            terminal.close();
+        }
+    });
+    let answer = '';
+    try {
+        answer = await ask();
+    }
+    catch { /* EOF, cancellation and input failure mean no consent. */ }
+    if (/^(y|yes)$/i.test(answer.trim()))
+        return true;
+    write('Existing setup preserved.\n');
+    return false;
+}
+export function saveWorkspaceReplacement(record) {
+    replaceFileAtomically(replacementPath(), JSON.stringify(record) + '\n', 0o600);
+}
+export function readWorkspaceReplacement() {
+    const file = replacementPath();
+    if (!existsSync(file))
+        return;
+    const stat = lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0 || stat.size > 65536)
+        throw Error('Unfinished replacement must be an owned private regular file');
+    let record;
+    try {
+        record = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw Error('Unfinished replacement record is invalid');
+    }
+    if (![1, 2].includes(record.version) || !opaque.test(record.operationNonce) || typeof record.configuration !== 'string' || resolve(record.configuration) !== record.configuration
+        || (record.rootCid !== undefined && !/^[a-f0-9]{64}$/i.test(record.rootCid)) || (record.retired !== undefined && typeof record.retired !== 'boolean')
+        || (record.cleaned !== undefined && typeof record.cleaned !== 'boolean') || (record.dispatchAttempted !== undefined && typeof record.dispatchAttempted !== 'boolean') || (record.version === 2 && (record.dispatchAttempted === undefined || (!Number.isSafeInteger(record.operationExpiresAt) || record.operationExpiresAt <= 0 || record.operationExpiresAt > Date.now() + 86400000 + 60000))) || (record.cleaned && !record.retired) || (record.retired && !record.rootCid))
+        throw Error('Unfinished replacement record is invalid');
+    record.previous = binding(record.previous);
+    if (!record.previous.serverCid)
+        throw Error('Unfinished replacement has no pinned server identity');
+    record.payload = decodeWorkspacePayload(Buffer.from(JSON.stringify(record.payload)).toString('base64url'), { allowExpired: true });
+    return record;
+}
+export function clearWorkspaceReplacement() { rmSync(replacementPath(), { force: true }); }
+/** Explicit recovery after the user removes an unsuccessful successor in the App. */
+export function discardRetiredWorkspaceReplacement() {
+    const record = readWorkspaceReplacement(), current = readWorkspaceBinding();
+    if (!record?.retired || !record.cleaned)
+        throw Error('Only a fully retired and locally cleaned replacement can be discarded; resume or safely abandon this operation');
+    if (!current || current.workspaceId !== record.previous.workspaceId || current.hostWorkspaceId !== record.previous.hostWorkspaceId || current.appOrigin !== record.previous.appOrigin || current.serverCid?.toUpperCase() !== record.previous.serverCid.toUpperCase())
+        throw Error('The successor binding was committed or the binding changed; resume its setup instead of discarding recovery');
+    clearWorkspaceReplacement();
+}
+function checkReplacementService(configuration) {
+    const manager = new WebServiceManager(), service = manager.readMetadata();
+    if (service?.configuration && resolve(service.configuration) !== resolve(configuration))
+        throw Error('Installed web service uses another configuration; existing setup preserved');
+    if (!service && existsSync(webControlPath()))
+        throw Error('Stop the foreground Fleet web service before replacing its registration; existing setup preserved');
+}
+export async function beginWorkspaceReplacement(previous, payload, configuration, effects = {}) {
+    checkWorkspaceConnector(payload);
+    if (!requiresWorkspaceReplacement(previous, { workspaceId: payload.challenge.workspaceId, appOrigin: payload.appOrigin, serverCid: payload.serverCid }))
+        throw Error('The same workspace must never be retired');
+    checkReplacementService(configuration);
+    const record = { version: 2, previous: previous, payload, configuration: resolve(configuration), operationNonce: randomBytes(32).toString('base64url'), dispatchAttempted: false, operationExpiresAt: Date.now() + 86400000 - 5 * 60000 };
+    record.rootCid = await (effects.preflight ?? unregisterWorkspace)(record.previous, payload, record.operationNonce, effects.attach, { checkOnly: true, operationExpiresAt: record.operationExpiresAt });
+    saveWorkspaceReplacement(record);
+    return record;
+}
+/** Abandon only after a private receipt confirms no deletion and dispatch was unsent or terminally rejected. */
+export async function abandonWorkspaceReplacement(effects = {}) {
+    const record = readWorkspaceReplacement();
+    if (!record)
+        throw Error('There is no unfinished replacement');
+    if (record.retired || record.cleaned || record.version !== 2)
+        throw Error('Retirement may already have completed; resume this replacement instead of abandoning it');
+    const current = readWorkspaceBinding();
+    if (!current || current.workspaceId !== record.previous.workspaceId || current.hostWorkspaceId !== record.previous.hostWorkspaceId || current.appOrigin !== record.previous.appOrigin || current.serverCid?.toUpperCase() !== record.previous.serverCid.toUpperCase())
+        throw Error('Workspace binding changed; replacement was not abandoned');
+    let deleted, rejected = false, expired = false, deadlineEnforced = false, oldBindingPresent = false;
+    const root = await (effects.inspect ?? unregisterWorkspace)(record.previous, record.payload, record.operationNonce, effects.attach, { checkOnly: true, operationExpiresAt: record.operationExpiresAt, onReceipt: status => { deleted = status.deleted; rejected = status.rejected === true; expired = status.expired === true; deadlineEnforced = status.deadlineEnforced === true; oldBindingPresent = status.oldBindingPresent === true; } });
+    if (root.toUpperCase() !== record.rootCid?.toUpperCase() || deleted !== false || (record.dispatchAttempted && !(rejected && !expired && Date.now() <= record.operationExpiresAt || oldBindingPresent && deadlineEnforced && Date.now() > record.operationExpiresAt + 5 * 60000)))
+        throw Error('Retirement may already have been sent; run --resume or abandon only after the account service confirms terminal rejection');
+    clearWorkspaceReplacement();
+}
+/** A failed/expired one-time command can be renewed only for its pinned successor. */
+export function refreshWorkspaceReplacement(record, payload, configuration) {
+    if (resolve(configuration) !== record.configuration)
+        throw Error('Replacement requires its original configuration');
+    if (payload.challenge.workspaceId !== record.payload.challenge.workspaceId || payload.challenge.accountId !== record.payload.challenge.accountId
+        || payload.appOrigin !== record.payload.appOrigin || payload.serverCid.toUpperCase() !== record.payload.serverCid.toUpperCase()
+        || payload.hostname !== record.payload.hostname)
+        throw Error('Unfinished replacement requires a fresh command for the same target workspace');
+    record.payload = payload.connectorToken === undefined && record.payload.connectorToken !== undefined ? { ...payload, connectorToken: record.payload.connectorToken } : payload;
+    saveWorkspaceReplacement(record);
+}
+/** Only tunnel files and account-issued device capabilities belong to this registration. */
+export async function clearReplacedWorkspaceLocalState() {
+    const manager = new WebServiceManager();
+    if (manager.readMetadata())
+        await manager.stop();
+    const devices = new WorkspaceDeviceStore();
+    try {
+        devices.revokeAll();
+    }
+    finally {
+        devices.close();
+    }
+    for (const file of ['tunnel.json', 'connector', 'pending-setup.json'])
+        rmSync(join(workspaceDir(), file), { force: true });
+}
+/** Persist every irreversible boundary; the original binding stays until enrollment writes its successor. */
+export async function finishWorkspaceReplacement(record, effects = {}) {
+    const current = readWorkspaceBinding();
+    if (!current || (current.workspaceId === record.previous.workspaceId ? (current.appOrigin !== record.previous.appOrigin || current.serverCid?.toUpperCase() !== record.previous.serverCid.toUpperCase() || current.hostWorkspaceId !== record.previous.hostWorkspaceId) : !sameWorkspaceBinding(current, record.payload)))
+        throw Error('Workspace binding changed during replacement; review it before continuing');
+    // A saved successor binding may predate a refreshed challenge. Enrollment
+    // checks the exact proof receipt: it reuses confirmed proof, or signs the new
+    // challenge, rather than assuming every challenge for this binding is done.
+    if (!record.retired) {
+        checkReplacementService(record.configuration);
+        if (record.version === 2 && Date.now() > record.operationExpiresAt + 5 * 60000) {
+            if (record.payload.challenge.expiresAt <= Date.now())
+                throw Error('Retirement deadline passed. Obtain a fresh App command for the same target and pass --replace-registration to continue');
+            let deleted, enforced = false;
+            const root = await (effects.inspect ?? unregisterWorkspace)(record.previous, record.payload, record.operationNonce, effects.attach, { checkOnly: true, operationExpiresAt: record.operationExpiresAt, onReceipt: status => { deleted = status.deleted; enforced = status.deadlineEnforced === true; } });
+            if (root.toUpperCase() !== record.rootCid?.toUpperCase())
+                throw Error('Original proof root changed; existing recovery preserved');
+            if (deleted === false && enforced) {
+                // The expired command cannot act. Existing consent covers this exact
+                // previous/successor pair, including signed absence after a lost receipt.
+                record.operationNonce = randomBytes(32).toString('base64url');
+                record.operationExpiresAt = Date.now() + 86400000 - 5 * 60000;
+                record.dispatchAttempted = false;
+                saveWorkspaceReplacement(record);
+            }
+        }
+        record.rootCid = await (effects.unregister ?? unregisterWorkspace)(record.previous, record.payload, record.operationNonce, effects.attach, { operationExpiresAt: record.operationExpiresAt, beforeSend: () => { record.dispatchAttempted = true; saveWorkspaceReplacement(record); } });
+        record.retired = true;
+        saveWorkspaceReplacement(record);
+    }
+    if (!record.cleaned) {
+        await (effects.cleanup ?? clearReplacedWorkspaceLocalState)();
+        record.cleaned = true;
+        saveWorkspaceReplacement(record);
+    }
+    if (record.payload.challenge.expiresAt <= Date.now())
+        throw Error('Old registration was retired, but the replacement setup window expired. Get a fresh App command and pass --replace-registration; the retirement will not be repeated');
+    return (effects.enroll ?? enrollWorkspace)(record.payload, record.configuration, { preserveProfile: true, replacingWorkspace: record.previous.workspaceId, attach: effects.attach });
+}

package/docs/acp-files.md

@@ -0,0 +1,146 @@
+# Sending files in an ACP chat
+
+Every managed Agent can attach a file to its current ACP chat with the existing
+Ours `send_file` tool. No Agent setting turns this on and no export directory is
+configured or created:
+
+```json
+{"path":"/home/me/project/build/report.pdf"}
+```
+
+Omitting `contact` sends to the current ACP chat. Supplying a non-empty contact
+keeps ordinary Ours delivery:
+
+```json
+{"contact":"Alice","path":"build/report.pdf"}
+```
+
+Only an absent contact chooses the chat. Null, empty or whitespace-only contacts,
+unknown fields and unknown recipients fail without falling back to chat.
+Current-chat sending accepts `path`, optional `filename` and `mime`; inline
+base64 and Ours reply fields are unsupported.
+
+Each call makes one attempt. Failures are returned to the agent. There is no
+request ID, deduplication, automatic retry or recovery of failed sends. If a user
+asks to resend, another tool call makes a new attempt and can produce another
+attachment. UUIDs identify stored attachments; the stored SHA-256 checks integrity.
+Neither is a retry key.
+
+## Paths
+
+The Agent passes the path of the file it wants to send. Relative paths resolve
+from the Agent's working directory; `..`, absolute paths, hidden directories and
+symlinked parent directories are all accepted. The file does not have to be
+inside the working directory or any particular subtree. It is opened by the
+Fleet bridge inside the Agent's own OS sandbox, so the Agent can send exactly
+what it can already read.
+
+The file itself must pass ordinary integrity checks, each with its own result:
+
+| Result | Meaning |
+| --- | --- |
+| `CHAT_FILE_NOT_FOUND` | nothing exists at the path |
+| `CHAT_FILE_NOT_READABLE` | the Agent's OS user or sandbox cannot read it |
+| `CHAT_FILE_IS_SYMLINK` | the named file is itself a symlink; pass its target |
+| `CHAT_FILE_HARDLINKED` | the file has more than one hard link |
+| `CHAT_FILE_NOT_REGULAR` | a directory, FIFO, socket or device |
+| `FILE_EXCEEDS_20_MIB` | larger than the 20 MiB limit |
+| `CHAT_FILE_CHANGED` / `SOURCE_SIZE_CHANGED` | modified while it was being read; finish writing first |
+| `CHAT_FILE_REQUIRES_LINUX` | the Agent's bridge is not running on Linux |
+| `PRIVATE_STATE_CANNOT_BE_SENT` | Fleet's own credentials, connector profile or stored attachments |
+
+`PRIVATE_STATE_CANNOT_BE_SENT` covers only Fleet's private Ours runtime
+directory, its attachment store and the connector profile and credential files,
+checked on the provided path before approval and on the opened file's real path
+afterwards. It is not configurable and is not a general path policy.
+
+## Supported sessions
+
+Current-chat delivery needs Linux, the managed Ours connector and a Codex or
+Claude ACP session with a tracked active turn. Those Agents need no special
+`harness_options`, MCP restriction or clean configuration home: inherited and
+additional MCP connectors stay as they are, and Fleet's bound bridge is the
+`ours` connector as it already is for every managed Agent.
+
+Any other backend still sees the optional `contact`, and omitting it returns a
+precise result rather than a missing tool:
+
+```
+CURRENT_CHAT_DELIVERY_UNAVAILABLE: sending a file to this chat requires a Codex or Claude ACP session; this Agent runs <harness>/<session>. Pass contact to send through Ours instead
+```
+
+Idle, scheduled, steered, cancelled and replaced turns return
+`CURRENT_CHAT_DELIVERY_UNAVAILABLE`; a second send while one is in progress
+returns `FILE_DELIVERY_BUSY`.
+
+A file is published only for a call that arrives over the Agent's
+capability-authenticated bridge and binds to the turn that is live in that
+Agent's own session. Connector inventory is not consulted, so unrelated or
+similarly named connectors neither enable nor block delivery.
+
+## Permissions
+
+Existing native tool approval and the neutral role permission policy both apply
+before bytes are read. With `approval: allow`, a path inside the role's
+`filesystem` boundary is allowed automatically; a path outside it is put to the
+attached controller like any other out-of-boundary request, and is denied when
+nobody is attached and `unattended: deny`. An `ask` decision needs an attached
+controller; `deny` refuses with `CURRENT_CHAT_DELIVERY_UNAVAILABLE`, and a
+declined request returns `FILE_SEND_DENIED`. A native policy that refuses MCP
+execution (including Codex `never` without a native tool allowance) can still
+refuse before Fleet receives the call.
+
+## Retired configuration
+
+`file_delivery` is retired. An existing block still loads so manifests need no
+edit, and has no effect:
+
+```yaml
+file_delivery:
+  enabled: false        # ignored: delivery stays available
+  directory: deliverables   # ignored: not created, not enforced
+```
+
+Remove it at your convenience. Unknown keys inside it are still rejected.
+
+## Storage and download
+
+Successful sends copy complete bytes into private immutable storage and append a
+server-origin `file.attached` event containing the actual session generation,
+ACP session and managed turn. One export can run at a time. Cancellation or
+steering before publication revokes it; cancellation after publication does not
+undo it. Unpublished stored bytes are never replayed or republished. Storage is
+bounded to 100 files and 200 MiB per role incarnation, including incomplete and
+orphaned copies. Exhausted storage fails; no automatic recovery is performed.
+
+The App renders persisted file cards from these typed events. HTML and images
+also download as files. Downloads require authentication, the matching role
+incarnation, a published conversation event and intact bytes. Deleted, missing,
+changed or orphaned artifacts return unavailable. Remote workspaces fetch bytes
+using their existing device credential, limit the read to 20 MiB and prevent
+saving after a workspace change.
+
+## Release prerequisite and qualification
+
+This source requires the companion MCP implementation's
+`MANAGED_FILE_DELIVERY_VERSION = 1`. Fleet pins published
+`@ours.network/mcp@1.2.0-nightly.14`, which includes it and already treats the
+export-directory hint as optional, so default delivery needs no MCP change. An
+installed MCP package without the capability fails Agent startup with
+`INCOMPATIBLE_MANAGED_FILE_DELIVERY` instead of quietly requiring a contact.
+Changes to the MCP pin require clean installed-package qualification without a
+built MCP overlay.
+
+The deterministic native fixture (`test/file-delivery-native.integration.mjs`)
+uses real ACP adapters, the real managed connector and an isolated daemon. Its
+Agent has no `file_delivery` block and no MCP restriction, and it sends a file
+from a hidden directory outside the working directory. It then downloads the
+generated attachment over the authenticated HTTP route and compares bytes and
+SHA-256, after checking that an anonymous and a forged-cookie request are
+refused. `FLEET_FILE_NATIVE_VARIANT=connectors` adds unrelated MCP connectors
+and requires them to stay usable. A local scripted provider supplies only tool
+intents; approval, read, copy, publication and bytes come from the
+implementation. It does not qualify external-model inference, deployment or
+arbitrary native MCP request-to-ACP tool-call ID mapping. Correlation is the
+authenticated bridge and the actual active Fleet turn, which is revoked by
+cancellation/steering.

package/docs/conversation-stream.md

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

package/docs/fleet-migration.md

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

package/docs/live-voice.md

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