@ours.network/fleet 1.2.0-nightly.45 → 1.2.0-nightly.47

package/dist/workspace-enrollment.js

@@ -17,7 +17,7 @@ export function readWorkspacePayload(file) {
         throw Error('Setup payload requires an owned private regular file (chmod 600)');
     return decodeWorkspacePayload(readFileSync(path, 'utf8'));
 }
-export function decodeWorkspacePayload(input) {
+export function decodeWorkspacePayload(input, options = {}) {
     let p;
     try {
         p = JSON.parse(Buffer.from(input.trim(), 'base64url').toString());
@@ -25,13 +25,43 @@ export function decodeWorkspacePayload(input) {
     catch {
         throw Error('Invalid workspace payload');
     }
-    if (p.version !== 1 || !['https://app.ours.network', 'https://app.ours-tunnel.com'].includes(p.appOrigin) || !/^[a-z0-9][a-z0-9-]{2,60}\.ours-tunnel\.com$/.test(p.hostname) || !/^[a-z0-9-]{2,30}@[a-z0-9-]{2,30}$/.test(p.rootName) || !/^[a-f0-9]{64}$/i.test(p.serverCid) || !p.challenge || !['nonce', 'accountId', 'workspaceId'].every(k => /^[\w-]{43}$/.test(String(p.challenge[k]))) || p.challenge.expiresAt <= Date.now() || p.challenge.expiresAt > Date.now() + 16 * 60000)
+    if (p.version !== 1 || !['https://app.ours.network', 'https://app.ours-tunnel.com'].includes(p.appOrigin) || !/^[a-z0-9][a-z0-9-]{2,60}\.ours-tunnel\.com$/.test(p.hostname) || !/^[a-z0-9-]{2,30}@[a-z0-9-]{2,30}$/.test(p.rootName) || !/^[a-f0-9]{64}$/i.test(p.serverCid) || !p.challenge || !['nonce', 'accountId', 'workspaceId'].every(k => /^[\w-]{43}$/.test(String(p.challenge[k]))) || (!options.allowExpired && p.challenge.expiresAt <= Date.now()) || !Number.isSafeInteger(p.challenge.expiresAt) || p.challenge.expiresAt > Date.now() + 16 * 60000)
         throw Error('Workspace payload is invalid or expired');
-    for (const k of ['connectorToken', 'invitation', 'name', 'surname'])
+    for (const k of ['connectorToken', 'invitation', 'name', 'surname']) {
+        if (k === 'connectorToken' && p[k] === undefined)
+            continue;
         if (typeof p[k] !== 'string' || !p[k] || p[k].length > 8192 || /[\x00-\x1f\x7f]/.test(p[k]))
             throw Error('Invalid workspace payload');
+    }
     return p;
 }
+/** Credential-free renewal is allowed only on the host already holding this private connector. */
+export function checkWorkspaceConnector(payload) {
+    if (payload.connectorToken !== undefined)
+        return;
+    const reject = () => { throw Error('This command renews an existing host without a connector credential. Restore its owned private connector file, or remove and re-create the workspace in the App before setting it up again'); };
+    const dir = join(stateRoot(), 'workspace');
+    let previous;
+    try {
+        previous = JSON.parse(readFileSync(join(dir, 'binding.json'), 'utf8'));
+    }
+    catch {
+        reject();
+    }
+    if (previous.workspaceId !== payload.challenge.workspaceId || validateAccountOrigin(previous.appOrigin ?? 'https://app.ours.network') !== payload.appOrigin || (previous.serverCid && previous.serverCid.toUpperCase() !== payload.serverCid.toUpperCase()))
+        reject();
+    try {
+        const file = join(dir, 'connector'), stat = lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0 || stat.size > 8193 || !readFileSync(file, 'utf8').trim())
+            reject();
+        const tunnel = JSON.parse(readFileSync(join(dir, 'tunnel.json'), 'utf8'));
+        if (tunnel.origin !== `https://${payload.hostname}` || tunnel.tokenFile !== file)
+            reject();
+    }
+    catch {
+        reject();
+    }
+}
 const GENERATED_VERSION = 'ours.network/fleet/v2';
 /** The rooms section tunnel setup writes for the enrolled Human root. */
 const generatedRooms = (rootCid, inviteFile) => ({ rooms: { owner: { provider: 'messenger-server', expected_cid: rootCid, public_invite_file: inviteFile, role: 'Owner' }, defaults: { attach_owner: true, close_when_task_done: true } } });
@@ -131,12 +161,17 @@ async function asHumanRoot(attach, root, purpose, use) {
     }
 }
 /** The signed workspace binding, sent by the Human root itself: the same command Messenger sends when it runs as the root. */
-async function proveWithHumanRoot(attach, root, payload, hostWorkspaceId, contactWaitMs) {
+async function proveWithHumanRoot(attach, root, payload, hostWorkspaceId, contactWaitMs, reuseContact = false) {
     const serverCid = payload.serverCid.toUpperCase();
     await asHumanRoot(attach, root, 'proof', async (client) => {
-        const peer = await client.addContact({ invite: payload.invitation });
-        if (peer.cid.toUpperCase() !== serverCid)
-            throw Error('Enrollment server identity mismatch');
+        // Retirement may already have redeemed this one-time invitation. Its exact signed
+        // handoff authorizes the new challenge; do not consume the invitation again.
+        const ready = reuseContact && (await client.listContacts()).contacts.some(contact => same(contact.container_id, serverCid));
+        if (!ready) {
+            const peer = await client.addContact({ invite: payload.invitation });
+            if (peer.cid.toUpperCase() !== serverCid)
+                throw Error('Enrollment server identity mismatch');
+        }
         const deadline = Date.now() + contactWaitMs;
         while (!(await client.listContacts()).contacts.some(contact => contact.container_id.toUpperCase() === serverCid)) {
             if (Date.now() >= deadline)
@@ -175,6 +210,8 @@ function managedRootOwner(configuration, rooms, root) {
  * Reads only; an existing Owner is compared with this host's own Messenger identity.
  */
 export async function checkWorkspaceConfiguration(configuration = defaultConfigPath(), attach = attachOursClient) {
+    if (new WebAccessStore().read().mode === 'none')
+        throw Error('Workspace enrollment requires protected web access; enable pairing or password before setup');
     const paths = preflightInitPaths(configuration);
     if (!paths.manifestExisted) {
         if (paths.rootExisted)
@@ -182,6 +219,12 @@ export async function checkWorkspaceConfiguration(configuration = defaultConfigP
         return;
     }
     const loaded = loadConfig(paths.configPath, { yamlMode: 'strict', deferredOwnerInviteFile: workspaceOwnerInvite() });
+    const inviteFile = loaded.rooms?.owner.public_invite_file || workspaceOwnerInvite();
+    if (existsSync(inviteFile)) {
+        const stat = lstatSync(inviteFile);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || stat.nlink !== 1 || (stat.mode & 0o077) !== 0)
+            throw Error('Retained Owner invitation file must be owned and private');
+    }
     if (!loaded.rooms)
         return;
     if (loaded.rooms.defaults?.attach_owner === false)
@@ -205,6 +248,7 @@ export async function enrollWorkspace(payload, configuration = defaultConfigPath
     const request = hostMessenger();
     if (new WebAccessStore().read().mode === 'none')
         throw Error('Workspace enrollment requires protected web access; enable pairing or password before setup');
+    checkWorkspaceConnector(payload);
     const dir = join(stateRoot(), 'workspace');
     mkdirSync(dir, { recursive: true, mode: 0o700 });
     const appOrigin = validateAccountOrigin(payload.appOrigin);
@@ -212,10 +256,10 @@ export async function enrollWorkspace(payload, configuration = defaultConfigPath
     let migrating = false;
     if (existsSync(previousFile)) {
         const previous = JSON.parse(readFileSync(previousFile, 'utf8'));
-        if (previous.workspaceId !== payload.challenge.workspaceId)
+        if (previous.workspaceId !== payload.challenge.workspaceId && options.replacingWorkspace !== previous.workspaceId)
             throw Error('This host is already associated with another workspace');
         const priorOrigin = validateAccountOrigin(previous.appOrigin ?? 'https://app.ours.network');
-        migrating = priorOrigin !== appOrigin;
+        migrating = priorOrigin !== appOrigin && options.replacingWorkspace !== previous.workspaceId;
         if (migrating && !options.migrateAppOrigin)
             throw Error('Account origin change requires explicit --migrate-app-origin and a fresh setup payload');
         if (migrating && previous.serverCid && previous.serverCid.toUpperCase() !== payload.serverCid.toUpperCase())
@@ -233,7 +277,7 @@ export async function enrollWorkspace(payload, configuration = defaultConfigPath
         throw Error('Bound Messenger identity unavailable');
     // An installation that ran Messenger as the Human root and now runs it as the person's own identity keeps its managed Owner entry, moved to that identity.
     const moved = Boolean(loaded.rooms) && !lost && !!identity.root && !same(loaded.rooms.owner.expected_cid, identity.cid) && managedRootOwner(resolve(configuration), loaded.rooms, identity.root)
-        && JSON.parse(readFileSync(previousFile, 'utf8')).serverCid?.toUpperCase() === payload.serverCid.toUpperCase();
+        && (options.replacingWorkspace !== undefined || JSON.parse(readFileSync(previousFile, 'utf8')).serverCid?.toUpperCase() === payload.serverCid.toUpperCase());
     if (options.preserveProfile && identity.preserveProfile !== true)
         throw Error('Existing-host setup requires Messenger profile-preservation support; update the host Messenger before retrying');
     if (loaded.rooms && !lost && !moved && loaded.rooms.owner.expected_cid.toLowerCase() !== identity.cid.toLowerCase())
@@ -249,9 +293,32 @@ export async function enrollWorkspace(payload, configuration = defaultConfigPath
     devices.close();
     const { name, surname, ...proofPayload } = payload;
     let result, ownerCid;
+    // A replacement can stop after its one-time proof but before local files commit. Read the
+    // account's existing signed receipt first; a verified proof must not be sent a second time.
+    let proofAlreadyConfirmed = false;
+    if (options.replacingWorkspace) {
+        let response;
+        try {
+            response = await fetch(appOrigin + '/account-api/workspace-proof', { method: 'POST', credentials: 'omit', redirect: 'error', signal: AbortSignal.timeout(15000), headers: { Origin: appOrigin, 'Content-Type': 'application/json' }, body: JSON.stringify({ ...payload.challenge, hostWorkspaceId, rootCid: identity.root?.cid ?? identity.cid }) });
+        }
+        catch {
+            throw Error('Replacement proof status could not be confirmed. Run setup-tunnel --resume');
+        }
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw Error('Replacement proof status was rejected; request a fresh App command with --replace-registration');
+        }
+        try {
+            proofAlreadyConfirmed = (await response.json()).verified === true;
+        }
+        catch {
+            throw Error('Invalid replacement proof receipt');
+        }
+    }
     if (identity.root) {
         // The Human root signs the binding; the person's own Messenger identity is the room Owner and issues the Owner invitation.
-        await proveWithHumanRoot(attach, identity.root, payload, hostWorkspaceId, options.contactWaitMs ?? 10000);
+        if (!proofAlreadyConfirmed)
+            await proveWithHumanRoot(attach, identity.root, payload, hostWorkspaceId, options.contactWaitMs ?? 10000, options.replacingWorkspace !== undefined);
         const invite = await request('invites', { mode: 'public' });
         if (typeof invite.blob !== 'string' || !invite.blob)
             throw Error('Malformed workspace enrollment response');
@@ -261,6 +328,13 @@ export async function enrollWorkspace(payload, configuration = defaultConfigPath
         result = { submitted: true, rootCid: identity.root.cid, ownerInvite: invite.blob };
         ownerCid = identity.cid;
     }
+    else if (proofAlreadyConfirmed) {
+        const invite = await request('invites', { mode: 'public' });
+        if (typeof invite.blob !== 'string' || !invite.blob)
+            throw Error('Malformed workspace enrollment response');
+        result = { submitted: true, rootCid: identity.cid, ownerInvite: invite.blob };
+        ownerCid = identity.cid;
+    }
     else {
         result = await request('workspace/enroll', options.preserveProfile ? { ...proofPayload, hostWorkspaceId, preserveProfile: true } : { ...payload, hostWorkspaceId });
         if (!result.submitted || !/^[a-f0-9]{64}$/i.test(result.rootCid) || typeof result.ownerInvite !== 'string')
@@ -303,7 +377,8 @@ export async function enrollWorkspace(payload, configuration = defaultConfigPath
         document.setIn(['rooms', 'owner', 'expected_cid'], ownerCid);
         replaceFileAtomically(configuration, document.toString(), 0o600);
     }
-    replaceFileAtomically(join(dir, 'connector'), payload.connectorToken + '\n', 0o600);
+    if (payload.connectorToken !== undefined)
+        replaceFileAtomically(join(dir, 'connector'), payload.connectorToken + '\n', 0o600);
     const origin = `https://${payload.hostname}`;
     replaceFileAtomically(join(dir, 'tunnel.json'), JSON.stringify({ origin, tokenFile: join(dir, 'connector') }) + '\n', 0o600);
     replaceFileAtomically(previousFile, JSON.stringify({ workspaceId: payload.challenge.workspaceId, hostWorkspaceId, appOrigin, serverCid: payload.serverCid.toUpperCase(), ...(identity.root ? { proofRootCid: identity.root.cid } : {}) }) + '\n', 0o600);
@@ -371,3 +446,121 @@ export async function confirmWorkspaceTarget(payload, hostWorkspaceId, rootCid,
     await configureWorkspacePort(payload, hostWorkspaceId, rootCid, port);
     await removeEnrollmentContact().catch(cleanupFailed);
 }
+/** Retire exactly the original registration using the same signed Human root that bound it. */
+export async function unregisterWorkspace(previous, payload, operationNonce, attach = attachOursClient, options = {}) {
+    const appOrigin = validateAccountOrigin(previous.appOrigin);
+    const messenger = hostMessenger();
+    const identity = await messengerIdentity(messenger, attach);
+    if (identity.preserveProfile !== true)
+        throw Error('Existing-host replacement requires Messenger profile-preservation support; existing local setup preserved');
+    const root = identity.root ?? await humanRoot(attach, identity.cid);
+    if (previous.proofRootCid && !same(root.cid, previous.proofRootCid))
+        throw Error('Original workspace proof root differs from this installation; existing local setup preserved');
+    const devices = new WorkspaceDeviceStore();
+    const hostWorkspaceId = devices.workspaceId;
+    devices.close();
+    if (hostWorkspaceId !== previous.hostWorkspaceId)
+        throw Error('Original workspace host ID differs from this installation; existing local setup preserved');
+    const deadlineField = options.operationExpiresAt === undefined ? {} : { operationExpiresAt: options.operationExpiresAt };
+    const receiptInput = { workspaceId: previous.workspaceId, hostWorkspaceId, operationNonce, rootCid: root.cid, ...deadlineField };
+    const request = options.request ?? fetch;
+    const receipt = async () => {
+        let response;
+        try {
+            response = await request(appOrigin + '/account-api/workspace-unregister-receipt', { method: 'POST', credentials: 'omit', redirect: 'error', signal: AbortSignal.timeout(15000), headers: { Origin: appOrigin, 'Content-Type': 'application/json' }, body: JSON.stringify(receiptInput) });
+        }
+        catch {
+            throw Error('Registration retirement could not be confirmed; local setup preserved. Run setup-tunnel --resume to retry');
+        }
+        if (response.status === 404) {
+            await response.body?.cancel();
+            return {};
+        }
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw Error(`Registration retirement receipt failed (HTTP ${response.status}); local setup preserved`);
+        }
+        try {
+            return await response.json();
+        }
+        catch {
+            throw Error('Invalid registration retirement receipt; local setup preserved');
+        }
+    };
+    let status = await receipt();
+    options.onReceipt?.(status);
+    if (options.checkOnly) {
+        if (status.deleted !== true && !(status.deleted === false && status.deadlineEnforced === true))
+            throw Error('Account service does not support replacing a registration yet; existing setup preserved');
+        // No invitation is consumed and no command is sent during preparation.
+        // A different server cannot be reconnected with the successor's invitation.
+        if (status.deleted !== true && status.rejected !== true && !same(previous.serverCid, payload.serverCid)) {
+            const check = async (client) => { if (!(await client.listContacts()).contacts.some(contact => same(contact.container_id, previous.serverCid)))
+                throw Error('Original enrollment server contact is unavailable; existing setup preserved'); };
+            if (identity.root)
+                await asHumanRoot(attach, root, 'retirement-preflight', check);
+            else
+                await check({ listContacts: () => messenger('contacts') });
+        }
+        return root.cid;
+    }
+    const requireRetryable = () => { if (status.rejected === true)
+        throw Error('The account service definitively rejected this retirement operation. Run setup-tunnel --abandon-replacement, then obtain a fresh App command and start again'); };
+    requireRetryable();
+    if (status.deleted !== true) {
+        if (payload.challenge.expiresAt <= Date.now())
+            throw Error('Replacement command expired before retirement; existing setup preserved. Obtain a fresh App command');
+        const retire = async (client) => {
+            const serverCid = previous.serverCid.toUpperCase();
+            let contacts = await client.listContacts();
+            if (!contacts.contacts.some(contact => same(contact.container_id, serverCid))) {
+                if (!same(payload.serverCid, serverCid))
+                    throw Error('Original enrollment server contact is unavailable. Reconnect it or remove the registration in the original account first; existing local setup preserved');
+                const peer = await client.addContact({ invite: payload.invitation });
+                if (!same(peer.cid, serverCid))
+                    throw Error('Original enrollment server identity mismatch; existing local setup preserved');
+                const deadline = Date.now() + (options.waitMs ?? 10000);
+                while (!(contacts = await client.listContacts()).contacts.some(contact => same(contact.container_id, serverCid))) {
+                    if (Date.now() >= deadline)
+                        throw Error('Original enrollment contact is not ready; local setup preserved. Run setup-tunnel --resume');
+                    await new Promise(resolve => setTimeout(resolve, 100));
+                }
+            }
+            const replacement = appOrigin === validateAccountOrigin(payload.appOrigin) && same(serverCid, payload.serverCid) && previous.workspaceId !== payload.challenge.workspaceId
+                ? { workspaceId: payload.challenge.workspaceId, accountId: payload.challenge.accountId, nonce: payload.challenge.nonce } : undefined;
+            // Persist uncertainty before invoking the transport: a lost response must
+            // never make an in-flight retirement safe to abandon.
+            options.beforeSend?.();
+            const outcome = await client.sendCommand({ contact: serverCid, command: 'unregister-workspace', arguments: { type: 'ours.app.unregister-workspace.v1', workspaceId: previous.workspaceId, hostWorkspaceId, operationNonce, ...deadlineField, ...(replacement ? { replacement } : {}) } });
+            if (!('sent' in outcome) || !outcome.sent)
+                throw Error('Registration retirement was not sent; local setup preserved');
+        };
+        if (identity.root)
+            await asHumanRoot(attach, root, 'unregister', retire);
+        else {
+            // Messenger already holds the root lease. Its first-party endpoint signs
+            // as that bound root; acquiring a second daemon lease would fail.
+            await retire({
+                listContacts: () => messenger('contacts'),
+                addContact: args => messenger('contacts/add', args),
+                sendCommand: async (args) => {
+                    const answer = await messenger('workspace/unregister', { serverCid: args.contact, rootCid: root.cid, ...args.arguments });
+                    if (answer.submitted !== true || typeof answer.rootCid !== 'string' || !same(answer.rootCid, root.cid))
+                        throw Error('Registration retirement answered for a different root; local setup preserved');
+                    return { sent: true };
+                },
+            });
+        }
+    }
+    const deadline = Date.now() + (options.waitMs ?? 30000);
+    while (status.deleted !== true || status.retired !== true) {
+        if (Date.now() >= deadline)
+            throw Error('Registration retirement is not confirmed; local setup preserved. Run setup-tunnel --resume with the same operation, or --abandon-replacement once the server confirms terminal rejection');
+        await new Promise(resolve => setTimeout(resolve, 500));
+        status = await receipt();
+        requireRetryable();
+    }
+    if (status.absent)
+        process.stderr.write('The account service has no record of the old registration. No old provider resources were deleted by this service.\n');
+    return root.cid;
+}

package/dist/workspace-replacement.d.ts

@@ -0,0 +1,66 @@
+import { enrollWorkspace, unregisterWorkspace, type AttachDaemonClient, type WorkspacePayload } from './workspace-enrollment.js';
+export interface WorkspaceBinding {
+    workspaceId: string;
+    hostWorkspaceId: string;
+    appOrigin: string;
+    serverCid?: string;
+    proofRootCid?: string;
+}
+export declare function readWorkspaceBinding(): WorkspaceBinding | undefined;
+export declare function sameWorkspaceBinding(previous: WorkspaceBinding, payload: WorkspacePayload): boolean;
+/** A workspace ID is never retired to rerun or migrate that same workspace. */
+export declare function requiresWorkspaceReplacement(previous: WorkspaceBinding, target: {
+    workspaceId: string;
+    appOrigin: string;
+    serverCid: string;
+}, migrateAppOrigin?: boolean): boolean;
+/** Ask before redeeming the one-use grant, whose destination is deliberately opaque. */
+export declare function confirmWorkspaceReplacement(previous: WorkspaceBinding, explicit?: boolean, effects?: {
+    write?: (value: string) => void;
+    interactive?: boolean;
+    ask?: () => Promise<string>;
+}): Promise<boolean>;
+export interface PendingWorkspaceReplacement {
+    version: 1 | 2;
+    previous: WorkspaceBinding & {
+        serverCid: string;
+    };
+    payload: WorkspacePayload;
+    configuration: string;
+    operationNonce: string;
+    rootCid?: string;
+    retired?: boolean;
+    cleaned?: boolean;
+    dispatchAttempted?: boolean;
+    operationExpiresAt?: number;
+}
+export declare function saveWorkspaceReplacement(record: PendingWorkspaceReplacement): void;
+export declare function readWorkspaceReplacement(): PendingWorkspaceReplacement | undefined;
+export declare function clearWorkspaceReplacement(): void;
+/** Explicit recovery after the user removes an unsuccessful successor in the App. */
+export declare function discardRetiredWorkspaceReplacement(): void;
+export declare function beginWorkspaceReplacement(previous: WorkspaceBinding, payload: WorkspacePayload, configuration: string, effects?: {
+    preflight?: typeof unregisterWorkspace;
+    attach?: AttachDaemonClient;
+}): Promise<PendingWorkspaceReplacement>;
+/** Abandon only after a private receipt confirms no deletion and dispatch was unsent or terminally rejected. */
+export declare function abandonWorkspaceReplacement(effects?: {
+    inspect?: typeof unregisterWorkspace;
+    attach?: AttachDaemonClient;
+}): Promise<void>;
+/** A failed/expired one-time command can be renewed only for its pinned successor. */
+export declare function refreshWorkspaceReplacement(record: PendingWorkspaceReplacement, payload: WorkspacePayload, configuration: string): void;
+/** Only tunnel files and account-issued device capabilities belong to this registration. */
+export declare function clearReplacedWorkspaceLocalState(): Promise<void>;
+/** Persist every irreversible boundary; the original binding stays until enrollment writes its successor. */
+export declare function finishWorkspaceReplacement(record: PendingWorkspaceReplacement, effects?: {
+    unregister?: typeof unregisterWorkspace;
+    inspect?: typeof unregisterWorkspace;
+    cleanup?: () => Promise<void>;
+    enroll?: typeof enrollWorkspace;
+    attach?: AttachDaemonClient;
+}): Promise<{
+    origin: string;
+    hostWorkspaceId: string;
+    rootCid: string;
+}>;

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.