@ours.network/fleet 1.2.0-nightly.5 → 1.2.0-nightly.50

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/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.

package/docs/room-layouts.md

@@ -0,0 +1,227 @@
+# YAML Room Layouts
+
+Room Layout describes room goals, participants and their shared or independent
+sessions. Rooms and agents have independent lifecycles.
+
+Place a layout at `fleet/room_layouts/<name>.yaml` beside the split configuration
+for `fleet.yaml`. Agent Templates remain in `fleet/agent_templates/`.
+
+```yaml
+version: 1
+participants:
+  product: {agent_template: Product}
+  developer: {agent_template: Developer}
+  qa: {agent_template: QA}
+rooms:
+  discovery:
+    goal: Clarify the problem and acceptance criteria
+    members: [product, developer, qa]
+  design:
+    goal: Review implementation choices
+    members: [developer, qa]
+  amigos:
+    goal: Resolve a concrete acceptance question
+    members: [product, developer, qa]
+    roles: {product: product, developer: developer, qa: qa}
+```
+
+Participant `instance_scope` controls instance reuse:
+
+- `layout` (default): repeating a participant key reuses its exact running instance
+  and session within this layout run.
+- `room`: each room using the key gets its own identity and session, lazily created
+  when that room opens. Repeated opens of the same active room reuse that instance.
+
+For example, one shared process doctor and one independent critic per room:
+
+```yaml
+version: 1
+participants:
+  doctor: {agent_template: ProcessDoctor, instance_scope: layout}
+  critic: {agent_template: Critic, instance_scope: room}
+rooms:
+  discovery:
+    goal: Agree on the problem
+    members: [doctor, critic]
+  design:
+    goal: Review the design
+    members: [doctor, critic]
+```
+
+Different keys using the same Agent Template still create independent instances.
+See the [shared](../examples/room-layouts/shared.yaml) and
+[fresh](../examples/room-layouts/fresh.yaml) examples, and the mixed
+[scoped](../examples/room-layouts/scoped.yaml) example. All choices can coexist.
+Fresh agents receive their room context. Supply relevant evidence through ordinary
+room messages or existing project documents when needed.
+
+A participant without `agent_template` requires a binding. `layout instance`
+returns a local exact reference (supervisor, agent, launch, CID and session).
+Pass participant-to-reference YAML to `create --bindings`. A stopped or replaced instance is rejected. Cross-Fleet bindings require
+an explicit owner grant, as described below.
+Room-scoped participants require `agent_template`; an explicit binding for them
+is rejected before creating resources. Bindings for layout-scoped participants
+keep their existing behavior.
+
+```sh
+ours-fleet layout validate work
+ours-fleet layout create work --id example
+ours-fleet layout open example design
+ours-fleet layout open example discovery
+ours-fleet layout open example amigos
+ours-fleet layout close-room example amigos
+ours-fleet layout status example
+ours-fleet layout close example
+```
+
+Any declared room may open first. `create` only saves the definition and resolved
+Agent Templates; `open` lazily starts missing participants and admits all members
+before sending their room context. The membership notification is informational. Existing room rules govern when
+an agent contributes. Each room opens through an explicit command.
+
+`close-room` archives a room and keeps agents available to other rooms. `close`
+archives opened rooms and stops only temporary participants created by this layout
+instance. Explicitly bound participants survive. Cleanup processes existing resources. A 3-Amigos room is an ordinary room with
+complementary members.
+Room-scoped instances follow the same cleanup rules: closing a room does not
+retire them, and a closed room cannot reopen. A new layout run creates new instances.
+
+Private state keeps the authorable definition unchanged. Its `participants` map
+uses the original key for shared instances and `<room>:<participant>` for
+room-scoped instances, with `participant` and `room` metadata. Declared but unopened
+rooms have no running instance. Status and task read models distinguish these
+entries and resolve their original Agent Template. Existing snapshots without
+`instance_scope` retain their original keys and require no migration. Snapshots
+using `room` require a Fleet version that supports this field; they are not a
+downgrade format for older Fleet versions.
+
+Supported room fields: `goal`, `members`, optional `roles`, `contract`,
+`quiet_membership`, `anonymous`. `contract` is briefing text.
+Top-level fields: `version: 1`, optional `description`, `participants`, `rooms`.
+Participant fields: optional `agent_template`, `instance_scope: layout|room`.
+Unknown fields, ambiguous YAML and invalid member references are rejected.
+Existing templates and tasks keep their behavior.
+
+Local Fleet control uses the existing authenticated control socket,
+agent runtime, `spawnTemp` and session queue. Cross-Fleet bindings delegate
+membership operations to their owning Fleet as described below. Private state
+snapshots template definitions; public status hides their environment values.
+Existing owner settings apply; owner CID/invite fingerprint are pinned. Unknown
+mutation outcomes stop new work for inspection rather than blindly replaying a
+spawn or room creation. `close` and `close-room` can still clean known resources.
+Cleanup continues after individual errors and does not stop replacement or borrowed
+instances. Confirmed stopped workers need no live control socket. An unknown
+original outcome remains recorded, and cleanup reports incomplete until inspected;
+it never claims that unknown resources were found or removed. Retrying cleanup
+checks known resources and skips completed cleanup. Reopening an active layout room
+checks its native state, CID and required seats and reports drift without repairing it.
+
+
+Shared sessions retain available conversation context, not guaranteed perfect
+recall or isolation between rooms. Compaction and model judgment still matter.
+Rooms keep their existing turn scheduling.
+
+Each layout instance creates distinct native room names, so several instances can
+open the same declared room key. Participant roles must differ from the attached
+owner role; a collision is rejected before creating resources.
+
+Definitions are loaded for authoring commands. Retained instances use their saved
+layout and Agent Templates. Status and cleanup operate on saved resources even
+when the source YAML is broken or removed. New agent launches continue to use
+Fleet's normal configuration and launch checks.
+
+## Borrowing an instance from another Fleet on the same host
+
+Fleet A can open rooms using standalone temporary or persistent agents supervised
+by Fleet B under another OS user. Both must select the same daemon instance and
+Cowork gateway. An agent's original Fleet keeps its session, identity and lifecycle
+control. This extends layout bindings; it does not add bindings to legacy
+`room create` / RoomTemplate provisioning.
+
+On the agent owner's Fleet B, use its existing web server and grant access to an
+exact live standalone instance:
+
+```sh
+ours-fleet web serve --port 49272 --no-open
+# In another terminal belonging to Fleet B's owner:
+ours-fleet layout share Architect --temporary --participant architect \
+  --server-url http://127.0.0.1:49272 --output ./architect.binding.yaml
+```
+
+The command prints the grant ID and output path. It creates a binding YAML and
+an adjacent `.token` file, both owner-only. The private owner record stores a
+SHA-256 token digest, not the token. `share` never overwrites an existing export.
+Transfer both files explicitly to Fleet A's user through your existing secure
+file-transfer method, keeping the receiving credential file owned by that user
+with mode `0600`. Do not share Fleet B's console session, client profile, daemon
+credential, private state directory or supervisor socket. This feature creates
+no additional server; Fleet B's existing web server must remain available.
+
+Export each specialist under its logical layout participant key, then merge the
+YAML mappings into one bindings document. Keep every adjacent token filename
+unique. Relative credential paths resolve against the bindings file's directory.
+The reusable layout contains participant factories or empty participant mappings,
+never concrete credentials or running-instance references:
+
+```yaml
+version: 1
+participants:
+  architect: {}
+  developer: {}
+  doctor: {}
+rooms:
+  product: {goal: Scope, members: [architect, doctor]}
+  design: {goal: Design, members: [architect, developer, doctor]}
+  delivery: {goal: Delivery, members: [developer, doctor]}
+```
+
+On Fleet A:
+
+```sh
+ours-fleet layout create project --id project-run --bindings ./bindings.yaml
+ours-fleet layout open project-run product
+ours-fleet layout open project-run design
+ours-fleet layout open project-run delivery
+ours-fleet layout close-room project-run product
+ours-fleet layout close project-run
+```
+
+The exact CID, launch and harness session are reused. Reopening an active room
+checks existing membership without delivering duplicate context. Closing rooms
+archives Cowork history and never stops borrowed instances. After acceptance,
+the original Fleet B owner explicitly retires its standalone temporary specialists
+using the existing lifecycle commands. Persistent specialists keep their ordinary
+lifecycle. Mixed local-created and borrowed participants are supported.
+
+An exported reference adds `remote` to the existing instance reference:
+
+```yaml
+remote:
+  url: http://127.0.0.1:49272
+  grant_id: 11111111-1111-4111-8111-111111111111
+  credential_file: architect.binding.yaml.token
+  daemon_instance_id: 22222222-2222-4222-8222-222222222222
+```
+
+The grant authorizes only `verify`, `join`, and `assign` for that exact instance.
+Room admission validates the requested room ID and CID against shared Cowork and
+uses an invite issued by Cowork on the owner side; caller-supplied contact invites
+are rejected before contact mutation. Context delivery also requires its active seat, expected room CID and role in
+Cowork. It cannot inspect inventory, spawn, stop, reconfigure, export identities,
+or authenticate browser console routes. It grants the holder room admission and
+room-context delivery, so transfer it only to the intended room creator.
+
+Owner-side revocation does not stop the agent or remove existing memberships:
+
+```sh
+ours-fleet layout revoke-binding <grant-id>
+```
+
+Stopped/replaced sessions, a different daemon, revoked grants or unavailable
+owner transport produce errors; no replacement is spawned. A lost response to a
+membership/context mutation retains the existing layout `uncertain` marker.
+Inspect the native room and owning Fleet before retrying; no mutation is blindly
+replayed. Only direct loopback HTTP origins (`127.0.0.1`) are supported;
+redirects, external hosts and forwarded requests are rejected. No cross-host
+support, discovery protocol, mission service, or room conversation limits are
+introduced.

package/docs/task-workspaces.md

@@ -0,0 +1,130 @@
+# Task workspaces and artifact retention
+
+New Tasks allocate a private workspace at
+`$OURS_FLEET_HOME/.ours-fleet/workspaces/tasks/<task-id>` (the user's home is the
+default for `OURS_FLEET_HOME`). New standalone Rooms use
+`.ours-fleet/workspaces/rooms/<room-id>`. A linked Room shares its Task's workspace.
+The absolute path, owner kind/ID and random ownership token are stored in the
+record before directory allocation; `.fleet-workspace.json` proves ownership.
+The path is visible in Task/Room JSON from both CLI and API. A folder of the same
+name without the matching marker is never adopted.
+
+Every newly managed member starts at that exact workspace, including retries.
+An explicit template/member `cwd` remains in the sealed input execution plan as
+source context, but the owned workspace overrides the effective launch cwd.
+Copy or clone required source into the workspace; Fleet does not move or delete
+the configured source directory. Briefings explain this rule. Use separate
+per-agent branches/directories inside the workspace for concurrent edits.
+
+All execution artifacts, dependency checkouts and worktrees belong inside the
+workspace. Clone each repository there first, then use `git worktree add` with
+destinations inside the same workspace. Git's native worktree registry is the
+registry of record. Fleet audits `.git`, `commondir` and reverse `gitdir` links
+before deletion; both the common repository and all registered worktrees must
+be inside the workspace. An external repository's worktree inside the workspace,
+or an internal repository's worktree outside it, blocks deletion. No broad
+`git worktree prune`, branch deletion, reset or modification of unrelated Git
+metadata is performed. Removing the owned repositories also removes their
+complete internal worktree registries, including dirty and stale owned entries.
+
+| Operation | Workspace and execution artifacts | Member runtime evidence |
+| --- | --- | --- |
+| Complete, fail, cancel | Retained while Task is recorded | Retained in Fleet recovery archives |
+| Linked Room retirement or deletion | Task workspace retained | Retained |
+| Internal standalone Room retirement | Room workspace retained | Retained |
+| Explicit Task deletion | Removed after member retirement | All proven owned retired launches removed |
+| Explicit standalone Room deletion | Removed after member retirement | All proven owned retired launches removed |
+
+Internal room close means retirement, not destructive Task deletion.
+The existing CLI `room close ID ID` remains a deprecated alias for explicit
+`room delete ID ID`: it deletes standalone room-owned artifacts, but always
+retains a linked Task workspace. Its repeated-ID confirmation is unchanged. To remove a Task's
+artifacts, explicitly delete the Task. Cancellation is not deletion. Automatic
+compatibility cleanup of legacy closed Rooms skips records with owned workspaces.
+These choices reconcile close/remove wording with the requirement that completed,
+recorded Tasks retain all artifacts.
+
+Fleet's active member state (briefings, logs, session state and WORKLOG) remains
+under `.ours-fleet/tmp` while supervisors run, then in
+`.ours-fleet/recovery/temporary`. The launch stores the workspace descriptor.
+Explicit deletion first proves managed agents retired, then identifies all
+matching archived launches, including failed and replaced attempts, using the
+workspace descriptor plus role and termination/launch evidence. It preflights
+these archives and atomically transfers them to `.fleet-retired-agents` in the
+workspace before removal. Unrelated archives are not adopted by a name prefix.
+Explicit deletion also erases legacy archives with exact launch/action or room
+provenance, matching private supervisor journals and admission/launch descriptors,
+and the exact retired-launch rows in the global termination journal. It never
+infers ownership from an Agent's shared `cwd`. Artifact removal uses a durable
+manifest, ownership fingerprints and per-entry rename/removal checkpoints, so
+an interrupted deletion can resume without deleting a replacement at the old path.
+Task deletion acceptance receipts exist only during cleanup and are erased after
+settlement (including retry after a crash between Task unlink and receipt cleanup).
+Shared Fleet command audit and lifecycle delivery ledgers have exactly attributed
+target labels, configuration and command arguments removed; unrelated entries are
+preserved. Delivery/deduplication metadata and a content-free erased-resource ID
+registry remain so a running writer cannot resurrect erased content. Infrastructure
+logs without structured ownership, backups, and copies already delivered to other
+identities are external retention boundaries; this is not a claim to erase every
+external copy.
+
+Provisioning serializes Task operation then Room close locks, including bounded
+seat waits, so concurrent retries cannot publish competing members and deletion
+cannot race a member launch. Local published Rooms are reused if the Task link
+write was interrupted. Workspace allocation publishes a marked staging directory;
+restart reuses the durable token. Deletion renames the validated workspace to a
+token-specific sibling tombstone before removal. A crash during removal resumes
+that exact tombstone; the Task record is unlinked last. Before collecting archives,
+Task deletion durably checkpoints verified retirement evidence. Retries verify
+any remaining original archive and still refuse replacement live member state
+or a recreated identity even after the archive has been consumed. Failed deletion
+remains retryable with its recorded error.
+
+Deletion rejects traversal, foreign recorded paths, changed markers and symlinked
+workspace ancestors. Ordinary artifact symlinks are unlinked without following
+their targets. Git control symlinks and foreign pointers are refused. As with
+Fleet's other filesystem lifecycle operations, a hostile same-UID process that
+mutates paths during validation requires OS isolation; application checks are
+not a security boundary against that process. Fleet enforces launch cwd and
+safe deletion; unrestricted agents can still write outside cwd, so the artifact
+placement rule also requires agent compliance and/or filesystem isolation.
+
+## Compatibility and limits
+
+Records from before this feature without `workspace` remain unmanaged. Existing
+agents retain their cwd and exact briefing/fingerprint so restart matching works.
+Fleet never claims an old cwd, an outcome artifact path, or a legacy recovery
+archive as owned merely because it was mentioned by a Task. Create a new managed
+Task and explicitly copy desired artifacts to migrate; deleting a legacy Task
+continues its previous lifecycle and does not delete arbitrary old files.
+
+Changing `OURS_FLEET_HOME` does not silently rebase recorded absolute ownership
+paths. Restore the original state root or explicitly migrate records and files
+with the supervisors stopped; mismatched paths fail closed. Archive transfer
+uses same-filesystem rename and reports a recoverable failure across mounts.
+
+Cowork's remote create operation has no idempotency key in this interface. A crash
+after remote creation but before local Room publication is an existing uncertain
+remote result; this change deduplicates locally recorded rooms and does not claim
+to solve that remote transaction window. Inspect remote room ownership before
+retrying ambiguous remote creation. No services or installed Fleet code are
+changed by building or testing this feature.
+
+
+## Broken provisioning and deletion recovery
+
+Deletion accepts every lifecycle state. Missing temporary directories, identities,
+remote rooms and already-erased artifacts are settled outcomes. Retry the same
+explicit delete after an interruption. A missing local member CID is recovered
+only from a matching authenticated seat in the pinned room (exact invite and
+role, uniquely matched), or a supervisor journal tied to the selected daemon,
+temporary instance and recorded creation action. These sources must agree.
+The recovered CID is persisted before retirement consumes the evidence.
+
+A contradictory CID, replacement launch, ambiguous seat, unreadable/corrupt
+record, or unreachable authority is not evidence of absence. Cleanup retains its
+cursor and reports the conflict instead of deleting an unrelated resource or
+claiming complete erasure. An identity with no recoverable authenticated binding
+requires restoring its actual ownership evidence; a name-only force removal is
+not supported. Room deletion removes the linked Task's dead room/member links and preserves its workspace; use explicit
+Task deletion when the request includes the associated Task and its artifacts.