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

package/README.md

@@ -1856,6 +1856,58 @@ pipe with a 32KiB limit and refuses a terminal. Legacy v1 payloads, which contai
 long-lived scoped credentials, are accepted only through file/stdin, never as
 command arguments. Use only one payload transport.
 
+When this host already has a registration, Fleet inspects the one-use grant without
+consuming it. The same workspace reruns without a deletion prompt or retirement.
+An account-origin change for that workspace requires `--migrate-app-origin`; a
+changed server identity is refused. An older App without inspection support falls
+back to asking before redemption. An unavailable inspection service preserves the
+grant and setup. Fleet verifies the redeemed destination against the inspection.
+
+For another workspace, setup describes the existing workspace, tunnel hostname and
+account origin and asks `[y/N]`. No answer or `no` preserves the setup and grant; a
+noninteractive caller must pass `--replace-registration`, otherwise it exits with
+an error. A legacy binding without a server identity must rerun its own workspace
+first. The original Human root signs retirement. Fleet waits for the account's
+durable cleanup receipt before stopping the old service and revoking its linked
+devices. If a migrated database has no old registration, the signed command confirms
+absence; the service has no old provider resources to delete. Installation identities,
+profile, agents, history, stable host ID and local pairing are preserved.
+
+Replacement recovery is saved in an owned private `workspace/replacement.json`
+after root, host, service and server-contact preconditions pass. The App must
+explicitly support deadline-enforced retirement; an older App without that
+capability preserves the existing setup. `setup-tunnel --resume` retries its nonce
+and saved operation deadline (24 hours less a five-minute clock margin).
+If the enrollment challenge expires, obtain a fresh App command for the same target
+and pass `--replace-registration`; completed retirement is retained. The old server
+identity is pinned: only its own invitation can reconnect it.
+
+`setup-tunnel --abandon-replacement` removes the private recovery payload only when
+a fresh private receipt confirms no deletion and the operation was never dispatched
+or was terminally rejected. A lost transport response remains uncertain. Expired
+operations require a fresh receipt proving the old binding still exists after the
+deadline plus five minutes and an explicit server guarantee that the deadline is enforced;
+older recovery records without that guarantee must be resumed. Abandoning preserves
+the existing binding, connector and installation data. A terminally rejected operation
+requires abandonment and a new App command, rather than reusing its nonce.
+After that deadline, a fresh command for the same target can also resume with a
+new operation nonce after checking the enforced expiry. This confirms signed
+absence if an old successful receipt was lost and later pruned.
+
+If the App accepted the successor proof before Fleet wrote its local binding,
+a fresh command for that target retains the original private connector from the
+recovery record. If that successor cannot be recovered, remove it in the App,
+then use `setup-tunnel --discard-retired-replacement` and a fresh App command.
+Discard is allowed only after retirement and local cleanup, while the old local
+binding remains. It removes only the recovery record. This host has no working
+registration until the new setup completes; the old service was stopped and its
+linked devices revoked.
+
+Renewal commands contain no existing live connector credential. Fleet keeps the
+current private connector byte for byte, and accepts renewal only for its recorded
+workspace, server, origin and tunnel hostname. Restore a missing or unsafe connector,
+or remove and re-create that workspace in the App before setting it up again.
+
 After service and signed tunnel-target confirmation, setup prints both a QR and
 ordinary private single-use connection code. The App checks readiness automatically
 and immediately opens the code field. If setup or code output fails after binding,

package/dist/application/role-removal-service.js

@@ -1,3 +1,4 @@
+import { retireNotificationTarget } from '../notifications/target-cleanup.js';
 import { cpSync, existsSync, mkdirSync, readdirSync, renameSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { loadConfig, ROLE_NAME_RE } from '../config.js';
@@ -87,6 +88,7 @@ export class RoleRemovalService {
             await this.options.ops.backend.uninstall(preview.role);
             if (existsSync(sourceState))
                 renameSync(sourceState, join(recoveryPath, 'orphan-state'));
+            await retireNotificationTarget(`/fleet/chats?chat=${encodeURIComponent(preview.role)}`).catch(() => { });
             this.options.ops.log(`removed orphaned backend/state '${preview.role}'`);
         }
         return { ...preview, removed: true, recoveryPath };

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
-  "version": "1.2.0-nightly.45",
-  "buildId": "9af6d0fa4b7e",
-  "commit": "f59c69b6662ae09b5e72ea2c4c0a958729e1928f",
+  "version": "1.2.0-nightly.46",
+  "buildId": "a75b12e57308",
+  "commit": "f608ced10209f4b9ecf9dc9b573d8cab46136a68",
   "dirty": true,
-  "builtAt": "2026-10-04T12:42:35.826Z",
+  "builtAt": "2026-10-04T23:11:11.430Z",
   "capabilities": [
     "managed-cli.setup-v1",
     "workspace.enroll.preserve-profile-v1",

package/dist/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
+import { beginWorkspaceReplacement, abandonWorkspaceReplacement, discardRetiredWorkspaceReplacement, clearWorkspaceReplacement, confirmWorkspaceReplacement, finishWorkspaceReplacement, readWorkspaceBinding, readWorkspaceReplacement, requiresWorkspaceReplacement, refreshWorkspaceReplacement } from './workspace-replacement.js';
 import { completeTunnelSetup } from './tunnel-setup-completion.js';
-import { readTunnelSetupFile, readTunnelSetupStdin, readTunnelSetupArgument, redeemTunnelSetup } from './tunnel-setup-input.js';
+import { readTunnelSetupFile, readTunnelSetupStdin, readTunnelSetupArgument, redeemTunnelSetup, inspectTunnelSetup, verifyTunnelSetupTarget } from './tunnel-setup-input.js';
 import { ensureMinimalSetup } from './minimal-setup.js';
-import { confirmWorkspaceTarget } from './workspace-enrollment.js';
+import { confirmWorkspaceTarget, checkWorkspaceConnector } from './workspace-enrollment.js';
 import { clearPendingTunnelSetup, readPendingTunnelSetup, requiredPortAfterExpiry, savePendingTunnelSetup, setupTunnelPreflight } from './setup-tunnel-preflight.js';
 import { availableWebPort } from './web/available-port.js';
 import QRCode from 'qrcode';
@@ -1609,9 +1610,23 @@ webCommand.command('uninstall').description('stop and uninstall the owner web se
 });
 async function workspaceEnrollmentCommand(opts, setupTunnel = false, argument) {
     try {
+        if (opts.discardRetiredReplacement) {
+            if (!setupTunnel || argument !== undefined || opts.file || opts.stdin || opts.check || opts.resume || opts.migrateAppOrigin || opts.replaceRegistration || opts.configuration || opts.abandonReplacement)
+                throw Error('--discard-retired-replacement takes no payload or other setup options');
+            discardRetiredWorkspaceReplacement();
+            process.stdout.write('Retired replacement recovery discarded. This host has no working registration: the old service was stopped and linked devices revoked. After removing the failed successor in the App, use a fresh command to complete a new registration. Installation data and the old local binding are preserved.\n');
+            return;
+        }
+        if (opts.abandonReplacement) {
+            if (!setupTunnel || argument !== undefined || opts.file || opts.stdin || opts.check || opts.resume || opts.migrateAppOrigin || opts.replaceRegistration || opts.configuration)
+                throw Error('--abandon-replacement takes no payload or other setup options');
+            await abandonWorkspaceReplacement();
+            process.stdout.write('Unsent or rejected replacement abandoned; existing local setup preserved. Obtain a fresh App command for another setup.\n');
+            return;
+        }
         if (setupTunnel && opts.check && opts.resume)
             throw Error('Use either --check or --resume');
-        if (setupTunnel && (opts.check || opts.resume) && (argument !== undefined || opts.file || opts.stdin || opts.migrateAppOrigin))
+        if (setupTunnel && (opts.check || opts.resume) && (argument !== undefined || opts.file || opts.stdin || opts.migrateAppOrigin || opts.replaceRegistration))
             throw Error('--check and --resume take no payload or migration flag');
         if (setupTunnel && opts.check) {
             await setupTunnelPreflight();
@@ -1621,10 +1636,22 @@ async function workspaceEnrollmentCommand(opts, setupTunnel = false, argument) {
         }
         let pending;
         if (setupTunnel && opts.resume) {
-            pending = readPendingTunnelSetup();
-            if (opts.configuration && resolvePath(opts.configuration) !== pending.configuration)
-                throw Error(`This setup started with configuration ${pending.configuration}; resume it without --configuration`);
-            await setupTunnelPreflight();
+            const replacement = readWorkspaceReplacement();
+            if (replacement) {
+                if (opts.configuration && resolvePath(opts.configuration) !== replacement.configuration)
+                    throw Error('Resume replacement with its original configuration');
+                await setupTunnelPreflight();
+                const result = await finishWorkspaceReplacement(replacement);
+                pending = { appOrigin: replacement.payload.appOrigin, origin: result.origin, hostWorkspaceId: result.hostWorkspaceId, rootCid: result.rootCid, challenge: replacement.payload.challenge, configuration: replacement.configuration };
+                savePendingTunnelSetup(pending);
+                clearWorkspaceReplacement();
+            }
+            else {
+                pending = readPendingTunnelSetup();
+                if (opts.configuration && resolvePath(opts.configuration) !== pending.configuration)
+                    throw Error(`This setup started with configuration ${pending.configuration}; resume it without --configuration`);
+                await setupTunnelPreflight();
+            }
         }
         else {
             if (argument === undefined && !opts.file && !opts.stdin)
@@ -1634,18 +1661,49 @@ async function workspaceEnrollmentCommand(opts, setupTunnel = false, argument) {
             if (opts.stdin && process.stdin.isTTY)
                 throw Error('--stdin requires a pipe; use an owned private --file instead');
             const input = setupTunnel ? (argument !== undefined ? readTunnelSetupArgument(argument) : opts.stdin ? await readTunnelSetupStdin() : readTunnelSetupFile(opts.file)) : undefined;
+            const previous = setupTunnel ? readWorkspaceBinding() : undefined;
+            const replacement = setupTunnel ? readWorkspaceReplacement() : undefined;
+            if (replacement && !opts.replaceRegistration)
+                throw Error('An unfinished replacement exists. Run setup-tunnel --resume, use a fresh command for the same target with --replace-registration, or --abandon-replacement when retirement was never sent or definitively rejected. If retirement and cleanup completed but the successor cannot be recovered, remove the successor in the App and use --discard-retired-replacement');
+            if (replacement && resolvePath(opts.configuration ?? defaultConfigPath()) !== replacement.configuration)
+                throw Error('Replacement requires its original configuration');
+            const target = previous && !replacement ? await inspectTunnelSetup(input) : undefined;
+            const different = previous && !replacement && (!target || requiresWorkspaceReplacement(previous, target, opts.migrateAppOrigin));
+            if (different && !(await confirmWorkspaceReplacement(previous, opts.replaceRegistration))) {
+                if (!process.stdin.isTTY)
+                    throw Error('Replacement confirmation required; existing setup and grant preserved');
+                return;
+            }
             if (setupTunnel) {
                 await setupTunnelPreflight();
                 await checkWorkspaceConfiguration(opts.configuration ?? defaultConfigPath());
             }
-            const payload = setupTunnel ? await redeemTunnelSetup(input) : readWorkspacePayload(opts.file);
+            let payload = setupTunnel ? await redeemTunnelSetup(input) : readWorkspacePayload(opts.file);
+            verifyTunnelSetupTarget(target, payload);
+            const replace = previous && !replacement && requiresWorkspaceReplacement(previous, { workspaceId: payload.challenge.workspaceId, serverCid: payload.serverCid, appOrigin: payload.appOrigin }, opts.migrateAppOrigin);
+            if (replacement) {
+                refreshWorkspaceReplacement(replacement, payload, opts.configuration ?? defaultConfigPath());
+                payload = replacement.payload;
+            }
+            checkWorkspaceConnector(payload);
             if (setupTunnel)
                 await ensureMinimalSetup(opts.configuration ?? defaultConfigPath());
-            const result = await enrollWorkspace(payload, opts.configuration, { migrateAppOrigin: opts.migrateAppOrigin, preserveProfile: setupTunnel || opts.preserveProfile });
+            let result;
+            if (replacement) {
+                result = await finishWorkspaceReplacement(replacement);
+            }
+            else if (replace) {
+                const record = await beginWorkspaceReplacement(previous, payload, opts.configuration ?? defaultConfigPath());
+                result = await finishWorkspaceReplacement(record);
+            }
+            else
+                result = await enrollWorkspace(payload, opts.configuration, { migrateAppOrigin: opts.migrateAppOrigin, preserveProfile: setupTunnel || opts.preserveProfile });
             pending = { appOrigin: payload.appOrigin, origin: result.origin, hostWorkspaceId: result.hostWorkspaceId, rootCid: result.rootCid, challenge: payload.challenge, configuration: resolvePath(opts.configuration ?? defaultConfigPath()) };
-            // The proof is one-time: keep what the remaining steps need so they can be finished without a new command.
-            if (setupTunnel)
+            // Keep both the replacement capability and the proof until the next recovery record is durable.
+            if (setupTunnel) {
                 savePendingTunnelSetup(pending);
+                clearWorkspaceReplacement();
+            }
         }
         try {
             await finishWorkspaceService(pending, opts.resume ? pending.configuration : opts.configuration, setupTunnel);
@@ -1739,7 +1797,10 @@ cOpt(program.command('setup-tunnel').argument('[payload]', 'minimal one-use v2 A
     .option('--file <path>', 'owned private App grant or legacy payload file (chmod 600)')
     .option('--stdin', 'read the private App grant or legacy payload from a pipe')
     .option('--check', 'only verify host prerequisites; changes nothing and needs no payload')
-    .option('--resume', 'finish a setup that stopped after this host was bound; needs no new payload')
+    .option('--resume', 'finish an interrupted replacement or setup; needs no new payload')
+    .option('--discard-retired-replacement', 'forget a failed successor after retirement and local cleanup; remove it in the App first')
+    .option('--abandon-replacement', 'discard an unsent or definitively rejected replacement after checking its private receipt')
+    .option('--replace-registration', 'confirm retirement of the existing account registration when the new one differs')
     .option('--migrate-app-origin', 'explicitly migrate the same workspace to its new account origin after verified signed proof')
     .action(async (payload, opts) => workspaceEnrollmentCommand(opts, true, payload));
 program.command('link-device').description('create a single-use workspace device connection code (expires in five minutes)')

package/dist/notifications/fleet-producer.d.ts

@@ -10,6 +10,7 @@ export declare class FleetNotificationProducer {
     private readonly queues;
     private readonly timer;
     private readonly existing;
+    private cleanup?;
     constructor(roots: string[], stateDir: string, config: ProducerConfig, warn?: (line: string) => void);
     private names;
     poll(): void;

package/dist/notifications/fleet-producer.js

@@ -1,7 +1,42 @@
-import { closeSync, existsSync, lstatSync, openSync, readSync, readdirSync, statSync } from 'node:fs';
+import { roomsDir } from '../rooms-tasks/room-state.js';
+import { drainNotificationTargetCleanup } from './target-cleanup.js';
+import { closeSync, existsSync, lstatSync, openSync, readSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { createHash } from 'node:crypto';
 import { NotificationOutbox } from './outbox.js';
+/** Unlike a UI inventory, unread classification must not treat unreadable records as absence. */
+function taskRoleAssociations() {
+    const dir = roomsDir(), result = new Map();
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return result;
+        throw error;
+    }
+    for (const name of files.filter(name => name.endsWith('.json'))) {
+        const file = join(dir, name), stat = lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+            throw Error('Unreadable room association');
+        const room = JSON.parse(readFileSync(file, 'utf8'));
+        if (!room || typeof room.room_id !== 'string' || !Array.isArray(room.member_seats))
+            throw Error('Invalid room association');
+        if (room.task_id === undefined)
+            continue;
+        if (typeof room.task_id !== 'string' || !/^[A-Za-z0-9_-]{1,120}$/.test(room.task_id))
+            throw Error('Invalid task association');
+        for (const seat of room.member_seats) {
+            if (typeof seat.role_name !== 'string')
+                throw Error('Invalid member association');
+            if (result.has(seat.role_name) && result.get(seat.role_name) !== room.task_id)
+                throw Error('Ambiguous task association');
+            result.set(seat.role_name, room.task_id);
+        }
+    }
+    return result;
+}
 /** Read durable supervisor ledgers without restarting agents or attaching a
  * conversation controller. Each tick reads at most 256 KiB per role, from its
  * checkpoint; it never loads a complete transcript or requests model history. */
@@ -13,6 +48,7 @@ export class FleetNotificationProducer {
     queues = new Map();
     timer;
     existing = new Set();
+    cleanup;
     constructor(roots, stateDir, config, warn = () => { }) {
         this.roots = roots;
         this.stateDir = stateDir;
@@ -34,6 +70,49 @@ export class FleetNotificationProducer {
         }
     }
     poll() {
+        this.cleanup ??= drainNotificationTargetCleanup(this.config, undefined, undefined, { beforeDelete: async (url) => {
+                const name = new URL(url, 'https://ours.invalid').searchParams.get('chat');
+                if (!name || !/^[A-Za-z0-9_-]+$/.test(name))
+                    return false;
+                // A recreated or retained role still has a valid target. Filesystem errors cannot prove removal.
+                for (const root of this.roots) {
+                    try {
+                        lstatSync(join(root, name));
+                        return false;
+                    }
+                    catch (error) {
+                        if (error.code !== 'ENOENT')
+                            throw error;
+                    }
+                }
+                for (const root of this.roots) {
+                    const roleDir = join(root, name), queue = this.queues.get(roleDir);
+                    if (queue) {
+                        await queue.retire();
+                        this.queues.delete(roleDir);
+                    }
+                    else {
+                        const file = join(this.stateDir, createHash('sha256').update(roleDir).digest('hex') + '.json');
+                        if (existsSync(file)) {
+                            const queue = new NotificationOutbox(file, this.config, async () => { throw Error('retired target'); });
+                            try {
+                                await queue.retire();
+                            }
+                            finally {
+                                await queue.close();
+                            }
+                        }
+                    }
+                }
+                return true;
+            } }).catch(() => { }).finally(() => { this.cleanup = undefined; });
+        let taskRoles;
+        try {
+            taskRoles = taskRoleAssociations();
+        }
+        catch {
+            this.warn('Notification task association unavailable; delivering unclassified events');
+        }
         for (const root of this.roots)
             for (const roleId of this.names(root)) {
                 const roleDir = join(root, roleId), dir = join(roleDir, '.conversation');
@@ -108,7 +187,7 @@ export class FleetNotificationProducer {
                         if (['message.chunk', 'message.replace'].includes(event.kind) && event.promptId && event.messageId && current.prompts.includes(prompt))
                             current.messages[prompt] = event.messageId;
                         if (event.kind === 'turn.completed' && event.promptId && current.prompts.includes(prompt)) {
-                            if (!outbox.enqueue(`${roleId}:${event.sessionGeneration}:${event.seq}`, { url: `/fleet/chats?chat=${encodeURIComponent(roleId)}&detail=1#fleet-message-${encodeURIComponent(current.messages[prompt] ?? event.promptId)}` }))
+                            if (!outbox.enqueue(`${roleId}:${event.sessionGeneration}:${event.seq}`, { ...(taskRoles ? { taskId: taskRoles.get(roleId) ?? null } : {}), url: `/fleet/chats?chat=${encodeURIComponent(roleId)}&detail=1#fleet-message-${encodeURIComponent(current.messages[prompt] ?? event.promptId)}` }))
                                 break;
                             current.prompts = current.prompts.filter(p => p !== prompt);
                             delete current.messages[prompt];
@@ -125,5 +204,5 @@ export class FleetNotificationProducer {
             }
     }
     async drain() { await Promise.all([...this.queues.values()].map(q => q.drain())); }
-    async close() { clearInterval(this.timer); await Promise.all([...this.queues.values()].map(q => q.close())); }
+    async close() { clearInterval(this.timer); await this.cleanup; await Promise.all([...this.queues.values()].map(q => q.close())); }
 }

package/dist/notifications/outbox.d.ts

@@ -3,6 +3,7 @@ export interface NotificationInput {
     title: string;
     body: string;
     url: string;
+    taskId?: string | null;
 }
 export interface ProducerConfig {
     /** Service base URL. With a gateway credential it is the server gateway's notifications route. */
@@ -29,6 +30,7 @@ export declare class NotificationOutbox {
     cursor?: number;
     checkpoint?: unknown;
     private running?;
+    private retired;
     private timer;
     constructor(file: string, config: ProducerConfig, project: (value: unknown, id: string) => Promise<NotificationInput>, warn?: (message: string) => void);
     private persist;
@@ -37,6 +39,8 @@ export declare class NotificationOutbox {
     enqueue(id: string, value: unknown, cursor?: number | undefined): boolean;
     drain(): Promise<void>;
     private drainOnce;
+    /** Wait for the current send before clearing queued sends and retiring its target. */
+    retire(): Promise<void>;
     close(): Promise<void>;
 }
 export {};

package/dist/notifications/outbox.js

@@ -66,6 +66,7 @@ export class NotificationOutbox {
     cursor;
     checkpoint;
     running;
+    retired = false;
     timer;
     constructor(file, config, project, warn = () => { }) {
         this.file = file;
@@ -106,6 +107,8 @@ export class NotificationOutbox {
     advance(cursor) { this.persist(this.entries, cursor); }
     saveCheckpoint(checkpoint) { this.persist(this.entries, this.cursor, checkpoint); }
     enqueue(id, value, cursor = this.cursor) {
+        if (this.retired)
+            return false;
         if (this.entries.some(e => e.id === id)) {
             if (cursor !== this.cursor)
                 this.advance(cursor);
@@ -117,10 +120,14 @@ export class NotificationOutbox {
         return true;
     }
     drain() {
+        if (this.retired)
+            return Promise.resolve();
         return this.running ??= this.drainOnce().finally(() => { this.running = undefined; });
     }
     async drainOnce() {
         for (const entry of [...this.entries].slice(0, 32)) {
+            if (this.retired)
+                break;
             try {
                 const value = entry.payload ?? await this.project(entry.value, entry.id);
                 // Freeze the canonical projection before any network attempt. A crash
@@ -145,5 +152,7 @@ export class NotificationOutbox {
             }
         }
     }
+    /** Wait for the current send before clearing queued sends and retiring its target. */
+    async retire() { this.retired = true; clearInterval(this.timer); await this.running; this.persist([]); }
     async close() { clearInterval(this.timer); await this.running; }
 }

package/dist/notifications/target-cleanup.d.ts

@@ -0,0 +1,8 @@
+import { type ProducerConfig } from './outbox.js';
+/** Queue only after the owning lifecycle has established deletion, never on a failed inventory read. */
+export declare function retireNotificationTarget(url: string, config?: ProducerConfig | undefined, dir?: string, request?: typeof fetch): Promise<void>;
+/** Persisted retries also run from the ordinary web notification producer after restart. */
+export declare function drainNotificationTargetCleanup(config: ProducerConfig, dir?: string, request?: typeof fetch, options?: {
+    retain?: boolean;
+    beforeDelete?: (url: string) => Promise<boolean>;
+}): Promise<void>;

package/dist/notifications/target-cleanup.js

@@ -0,0 +1,41 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { replaceFileAtomically } from '../atomic-file.js';
+import { stateRoot } from '../paths.js';
+import { producerConfig } from './outbox.js';
+const cleanupDir = () => join(stateRoot(), 'notifications', 'removed-targets');
+/** Queue only after the owning lifecycle has established deletion, never on a failed inventory read. */
+export async function retireNotificationTarget(url, config = producerConfig(), dir = cleanupDir(), request = fetch) {
+    if (!config)
+        return;
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    replaceFileAtomically(join(dir, createHash('sha256').update(url).digest('hex') + '.json'), JSON.stringify({ url }) + '\n', 0o600);
+    await drainNotificationTargetCleanup(config, dir, request, { retain: true });
+}
+/** Persisted retries also run from the ordinary web notification producer after restart. */
+export async function drainNotificationTargetCleanup(config, dir = cleanupDir(), request = fetch, options = {}) {
+    if (!existsSync(dir))
+        return;
+    for (const file of readdirSync(dir).filter(file => /^[a-f0-9]{64}\.json$/.test(file)).slice(0, 32)) {
+        try {
+            const path = join(dir, file), value = JSON.parse(readFileSync(path, 'utf8'));
+            if (typeof value.url !== 'string' || !value.url.startsWith('/fleet/chats?'))
+                continue;
+            if (options.beforeDelete && !(await options.beforeDelete(value.url))) {
+                rmSync(path, { force: true });
+                continue;
+            }
+            const response = await request(config.origin + '/api/v1/delete-target', { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10000),
+                headers: { ...(config.gatewayCredential ? { 'X-Ours-Api-Token': config.gatewayCredential, 'X-Ours-Notifications-Producer': config.token } : { Authorization: `Bearer ${config.token}` }), 'Content-Type': 'application/json' }, body: JSON.stringify(value) });
+            await response.body?.cancel();
+            if (!response.ok)
+                break;
+            if (!options.retain)
+                rmSync(path, { force: true });
+        }
+        catch {
+            break; /* No credentials or response bodies are included in logs. */
+        }
+    }
+}

package/dist/ops.js

@@ -1,3 +1,4 @@
+import { retireNotificationTarget } from './notifications/target-cleanup.js';
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, unlinkSync, } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID, createHash } from 'node:crypto';
@@ -257,6 +258,7 @@ export async function rmRole(cfg, name, deps) {
     rmSync(agentDir(name), { recursive: true, force: true });
     if (generatedSource && existsSync(role.sourceFile)) {
         unlinkSync(role.sourceFile);
+        await retireNotificationTarget(`/fleet/chats?chat=${encodeURIComponent(name)}`).catch(() => { });
         deps.log(`removed ${role.sourceFile}`);
     }
     deps.log(`removed '${name}' (its ours identity is left intact)`);

package/dist/tunnel-setup-input.d.ts

@@ -6,3 +6,14 @@ export declare function readTunnelSetupStdin(input?: AsyncIterable<Buffer | stri
 export declare function readTunnelSetupArgument(input: string): string;
 /** Redeem the grant by HTTPS POST; long-lived connector credentials remain off argv and URLs. */
 export declare function redeemTunnelSetup(input: string, request?: typeof fetch): Promise<WorkspacePayload>;
+/** Inspect only public destination metadata; this never consumes a one-use grant. */
+export declare function inspectTunnelSetup(input: string, request?: typeof fetch): Promise<{
+    workspaceId: string;
+    serverCid: string;
+    appOrigin: string;
+} | undefined>;
+export declare function verifyTunnelSetupTarget(target: {
+    workspaceId: string;
+    serverCid: string;
+    appOrigin: string;
+} | undefined, payload: WorkspacePayload): void;

package/dist/tunnel-setup-input.js

@@ -80,3 +80,45 @@ export async function redeemTunnelSetup(input, request = fetch) {
         throw Error('Tunnel setup response origin mismatch');
     return payload;
 }
+/** Inspect only public destination metadata; this never consumes a one-use grant. */
+export async function inspectTunnelSetup(input, request = fetch) {
+    let version;
+    try {
+        version = JSON.parse(Buffer.from(input.trim(), 'base64url').toString()).version;
+    }
+    catch { }
+    if (version === 1) {
+        const p = decodeWorkspacePayload(input);
+        return { workspaceId: p.challenge.workspaceId, serverCid: p.serverCid, appOrigin: p.appOrigin };
+    }
+    const grant = decodeTunnelSetupGrant(input);
+    let response;
+    try {
+        response = await request(grant.appOrigin + '/account-api/workspace-install-inspect', { method: 'POST', redirect: 'error', credentials: 'omit', signal: AbortSignal.timeout(15000), headers: { Origin: grant.appOrigin, 'Content-Type': 'application/json' }, body: JSON.stringify({ code: grant.code }) });
+    }
+    catch {
+        throw Error('Could not inspect the account setup command; existing setup and grant preserved');
+    }
+    if (response.status === 404 || response.status === 405) {
+        await response.body?.cancel();
+        return;
+    }
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw Error('Setup command inspection failed; existing setup and grant preserved');
+    }
+    let target;
+    try {
+        target = await response.json();
+    }
+    catch {
+        throw Error('Invalid setup command inspection response');
+    }
+    if (!target || Object.keys(target).sort().join(',') !== 'serverCid,workspaceId' || typeof target.workspaceId !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(target.workspaceId) || typeof target.serverCid !== 'string' || !/^[a-f0-9]{64}$/i.test(target.serverCid))
+        throw Error('Invalid setup command inspection response');
+    return { ...target, appOrigin: grant.appOrigin };
+}
+export function verifyTunnelSetupTarget(target, payload) {
+    if (target && (target.workspaceId !== payload.challenge.workspaceId || target.serverCid.toUpperCase() !== payload.serverCid.toUpperCase() || target.appOrigin !== payload.appOrigin))
+        throw Error('Redeemed setup command differs from inspected destination; existing setup preserved');
+}

package/dist/web/workspace-devices.d.ts

@@ -25,5 +25,7 @@ export declare class WorkspaceDeviceStore {
     valid(id: string): boolean;
     list(): WorkspaceDevice[];
     revoke(id: string): void;
+    /** Retire account links without changing the installation's stable host ID or other data. */
+    revokeAll(): void;
     close(): void;
 }

package/dist/web/workspace-devices.js

@@ -80,5 +80,18 @@ export class WorkspaceDeviceStore {
     valid(id) { return Boolean(this.db.prepare('SELECT id FROM devices WHERE id=? AND revokedAt IS NULL AND expiresAt>?').get(id, this.now())); }
     list() { return this.db.prepare('SELECT id,label,createdAt,lastUsedAt,expiresAt,revokedAt FROM devices ORDER BY createdAt DESC LIMIT 256').all().map(row => ({ id: String(row.id), label: String(row.label), createdAt: Number(row.createdAt), lastUsedAt: Number(row.lastUsedAt), expiresAt: Number(row.expiresAt), revokedAt: row.revokedAt === null ? null : Number(row.revokedAt) })); }
     revoke(id) { this.db.prepare('UPDATE devices SET revokedAt=? WHERE id=? AND revokedAt IS NULL').run(this.now(), id); this.db.prepare('DELETE FROM enrollments WHERE issuer=?').run(id); }
+    /** Retire account links without changing the installation's stable host ID or other data. */
+    revokeAll() {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            this.db.prepare('UPDATE devices SET revokedAt=? WHERE revokedAt IS NULL').run(this.now());
+            this.db.exec('DELETE FROM enrollments');
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
     close() { this.db.close(); }
 }

package/dist/workspace-enrollment.d.ts

@@ -6,7 +6,7 @@ export interface WorkspacePayload {
     rootName: string;
     name: string;
     surname: string;
-    connectorToken: string;
+    connectorToken?: string;
     invitation: string;
     serverCid: string;
     challenge: {
@@ -17,7 +17,11 @@ export interface WorkspacePayload {
     };
 }
 export declare function readWorkspacePayload(file: string): WorkspacePayload;
-export declare function decodeWorkspacePayload(input: string): WorkspacePayload;
+export declare function decodeWorkspacePayload(input: string, options?: {
+    allowExpired?: boolean;
+}): WorkspacePayload;
+/** Credential-free renewal is allowed only on the host already holding this private connector. */
+export declare function checkWorkspaceConnector(payload: WorkspacePayload): void;
 type DaemonClient = Pick<OursClient, 'listIdentities' | 'chooseIdentity' | 'addContact' | 'listContacts' | 'sendCommand' | 'removeContact' | 'releaseLease' | 'close'>;
 /** How tunnel setup reaches this host's daemon; replaced only by tests. */
 export type AttachDaemonClient = (options: AttachOursClientOptions) => Promise<DaemonClient>;
@@ -29,6 +33,7 @@ export declare function checkWorkspaceConfiguration(configuration?: string, atta
 export declare function enrollWorkspace(payload: WorkspacePayload, configuration?: string, options?: {
     migrateAppOrigin?: boolean;
     preserveProfile?: boolean;
+    replacingWorkspace?: string;
     attach?: AttachDaemonClient;
     contactWaitMs?: number;
     afterInvitation?: () => void;
@@ -51,4 +56,27 @@ export declare function configureWorkspacePort(payload: Pick<WorkspacePayload, '
  * so the setup can be finished later. A removal that fails is reported and does not undo the setup.
  */
 export declare function confirmWorkspaceTarget(payload: Pick<WorkspacePayload, 'appOrigin' | 'challenge'>, hostWorkspaceId: string, rootCid: string, port: number, cleanupFailed?: (error: unknown) => void): Promise<void>;
+/** Retire exactly the original registration using the same signed Human root that bound it. */
+export declare function unregisterWorkspace(previous: {
+    workspaceId: string;
+    hostWorkspaceId: string;
+    appOrigin: string;
+    serverCid: string;
+    proofRootCid?: string;
+}, payload: WorkspacePayload, operationNonce: string, attach?: AttachDaemonClient, options?: {
+    request?: typeof fetch;
+    waitMs?: number;
+    checkOnly?: boolean;
+    beforeSend?: () => void;
+    operationExpiresAt?: number;
+    onReceipt?: (status: {
+        deleted?: boolean;
+        retired?: boolean;
+        absent?: boolean;
+        rejected?: boolean;
+        expired?: boolean;
+        deadlineEnforced?: boolean;
+        oldBindingPresent?: boolean;
+    }) => void;
+}): Promise<string>;
 export {};

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

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet",
-  "version": "1.2.0-nightly.45",
+  "version": "1.2.0-nightly.46",
   "description": "Harness-agnostic fleet of persistent, identity-bound AI agents. Declarative fleet.yaml, managed native/ACP sessions, supervision, and ours.network messaging.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",