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

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.13`, 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/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.