@cjhyy/code-shell-server 0.9.35 → 0.9.37

package/dist/mobile-remote/room-manager.js

@@ -1,4 +1,5 @@
-import { chmodSync, closeSync, existsSync, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, readdirSync, renameSync, writeFileSync, appendFileSync, rmSync, } from "node:fs";
+import { chmodSync, closeSync, existsSync, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, readdirSync, renameSync, writeFileSync, appendFileSync, rmSync, } from "node:fs";
+import { readRoomHistoryPage, scanRoomHistory, } from "./room-history.js";
 import { randomUUID } from "node:crypto";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 /**
@@ -24,6 +25,17 @@ function isContained(root, target) {
     const rel = relative(root, target);
     return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
 }
+function syncRoomDirectory(path) {
+    if (process.platform === "win32")
+        return;
+    const fd = openSync(path, "r");
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 function readBoundedUtf8File(path, maxBytes) {
     const fd = openSync(path, "r");
     try {
@@ -105,7 +117,14 @@ function parseRoomMessage(value) {
         raw.type.length > 128) {
         return undefined;
     }
-    for (const field of ["text", "tool", "summary", "reason", "toolId"]) {
+    for (const field of [
+        "text",
+        "tool",
+        "summary",
+        "reason",
+        "toolId",
+        "transcriptSource",
+    ]) {
         const item = raw[field];
         if (item !== undefined && (typeof item !== "string" || item.includes("\0")))
             return undefined;
@@ -235,6 +254,7 @@ export class RoomManager {
     /** User turns are echoed immediately for responsive room UX. When a
      * transcript follower later sees the same CLI-written user line, this queue
      * suppresses that duplicate. */
+    transcriptSources = new Map();
     pendingTranscriptUserEchoes = new Map();
     /**
      * Rooms whose agent events must be buffered instead of handled immediately.
@@ -251,12 +271,19 @@ export class RoomManager {
      * JSONL. Seeded lazily from disk on the first append after startup; dropped
      * when the room's messages are deleted so the next append re-derives it.
      */
+    messageStampByRoom = new Map();
+    messageStamp(id) {
+        const stat = lstatSync(this.msgPath(id));
+        return [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
+    }
     lastSeqByRoom = new Map();
     /** Throttled lastActiveAt bookkeeping — see touchLastActive. */
     pendingLastActive = new Map();
     lastActiveWrittenAt = new Map();
     now;
     rootRealPath;
+    rootIdentity;
+    failedWrites = new Set();
     /** Drop all pending AskUser entries for a room. Called when its agent goes
      *  away (exit/close) so a request that can no longer be answered doesn't leak
      *  in the map (small memory leak) and its approval card doesn't hang until the
@@ -281,6 +308,7 @@ export class RoomManager {
             throw new Error(`invalid room storage root: ${opts.rootDir}`);
         }
         this.rootRealPath = realpathSync(opts.rootDir);
+        this.rootIdentity = `${rootInfo.dev}:${rootInfo.ino}`;
         if (process.platform !== "win32")
             chmodSync(opts.rootDir, 0o700);
     }
@@ -288,7 +316,8 @@ export class RoomManager {
         const info = lstatSync(this.opts.rootDir);
         if (info.isSymbolicLink() ||
             !info.isDirectory() ||
-            realpathSync(this.opts.rootDir) !== this.rootRealPath) {
+            realpathSync(this.opts.rootDir) !== this.rootRealPath ||
+            `${info.dev}:${info.ino}` !== this.rootIdentity) {
             throw new Error(`invalid room storage root: ${this.opts.rootDir}`);
         }
     }
@@ -318,7 +347,7 @@ export class RoomManager {
         const path = join(this.roomDir(id), name);
         if (existsSync(path)) {
             const info = lstatSync(path);
-            if (info.isSymbolicLink() || !info.isFile())
+            if (info.isSymbolicLink() || !info.isFile() || info.nlink !== 1)
                 throw new Error(`invalid room file: ${path}`);
         }
         return path;
@@ -337,7 +366,15 @@ export class RoomManager {
                 encoding: "utf-8",
                 mode: 0o600,
             });
+            const fd = openSync(temporary, "r");
+            try {
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
             renameSync(temporary, target);
+            syncRoomDirectory(this.roomDir(id));
         }
         finally {
             try {
@@ -354,6 +391,7 @@ export class RoomManager {
         if (Buffer.byteLength(serialized, "utf8") > MAX_ROOM_MESSAGE_BYTES) {
             throw new Error("room message exceeds the size limit");
         }
+        const created = !existsSync(target);
         const fd = openSync(target, "a+", 0o600);
         try {
             if (process.platform !== "win32")
@@ -367,6 +405,13 @@ export class RoomManager {
                     prefix = "\n";
             }
             appendFileSync(fd, `${prefix}${serialized}\n`, "utf-8");
+            fsyncSync(fd);
+            if (created)
+                syncRoomDirectory(this.roomDir(id));
+        }
+        catch (error) {
+            this.failedWrites.add(id);
+            throw error;
         }
         finally {
             closeSync(fd);
@@ -408,6 +453,7 @@ export class RoomManager {
             linkedSessionMode: input.linkedSessionMode,
         };
         mkdirSync(this.roomDir(id), { recursive: true, mode: 0o700 });
+        syncRoomDirectory(this.opts.rootDir);
         this.writeRoomMeta(id, meta);
         // Audit anchor: the first line records how the room was opened (cwd +
         // permission mode), so messages.jsonl is self-describing for "what could
@@ -466,14 +512,20 @@ export class RoomManager {
         // host's event loop: a long-lived room progressively slowed down new
         // messages, heartbeats and every other WebSocket client. (Measured: ~32s to
         // write 2,000 short messages.)
+        if (this.failedWrites.has(id))
+            throw new Error("room persistence failed; reopen after inspecting its history");
         const cached = this.lastSeqByRoom.get(id);
         if (cached !== undefined) {
+            if (this.messageStampByRoom.get(id) !== this.messageStamp(id)) {
+                this.failedWrites.add(id);
+                throw new Error("room history changed outside this writer; inspect it before reopening");
+            }
             const next = cached + 1;
             this.lastSeqByRoom.set(id, next);
             return next;
         }
-        const msgs = this.getMessages(id, 0);
-        const next = msgs.length === 0 ? 1 : msgs[msgs.length - 1].seq + 1;
+        const path = this.msgPath(id);
+        const next = existsSync(path) ? scanRoomHistory(path, parseRoomMessage) + 1 : 1;
         this.lastSeqByRoom.set(id, next);
         return next;
     }
@@ -484,6 +536,7 @@ export class RoomManager {
         const msg = { seq, ts, ...partial };
         try {
             this.appendRoomMessage(id, msg);
+            this.messageStampByRoom.set(id, this.messageStamp(id));
         }
         catch (error) {
             // Sequence assignment is a commit effect, not an attempt counter. A
@@ -601,8 +654,29 @@ export class RoomManager {
                 closeSync(fd);
         }
     }
+    getHistoryPage(id, request = {}) {
+        if (!this.getRoom(id))
+            throw new Error("room is missing or its metadata is corrupt");
+        return readRoomHistoryPage(this.roomDir(id), id, request, parseRoomMessage);
+    }
     latestSeq(id) {
-        return this.getMessages(id).at(-1)?.seq ?? 0;
+        if (this.failedWrites.has(id))
+            throw new Error("room persistence failed");
+        const cached = this.lastSeqByRoom.get(id);
+        if (cached !== undefined)
+            return cached;
+        const path = this.msgPath(id);
+        return existsSync(path) ? scanRoomHistory(path, parseRoomMessage) : 0;
+    }
+    hasTranscriptHistory(id) {
+        let found = false;
+        const file = this.msgPath(id);
+        if (existsSync(file))
+            scanRoomHistory(file, parseRoomMessage, (message) => {
+                if (message.transcriptSource)
+                    found = true;
+            });
+        return found;
     }
     beginTranscriptFollow(id) {
         if (this.getRoom(id))
@@ -614,9 +688,30 @@ export class RoomManager {
     /** Persist normalized transcript-tail messages through the same seq/history/
      * broadcast path as resident-agent output. */
     ingestTranscriptMessages(id, messages) {
-        if (!this.transcriptFollowedRooms.has(id) || !this.getRoom(id))
+        if (!messages.length)
             return;
+        if (!this.transcriptFollowedRooms.has(id) || !this.getRoom(id))
+            throw new Error("transcript room is not active");
+        let sources = this.transcriptSources.get(id);
+        if (!sources) {
+            sources = new Set();
+            const path = this.msgPath(id);
+            if (existsSync(path))
+                scanRoomHistory(path, parseRoomMessage, (message) => {
+                    if (message.transcriptSource)
+                        sources.add(message.transcriptSource);
+                });
+            this.transcriptSources.set(id, sources);
+        }
         for (const message of messages) {
+            const source = message.transcriptSource;
+            if (source !== undefined &&
+                (typeof source !== "string" ||
+                    source.length > 200 ||
+                    !/^[0-9a-f-]{36}:[0-9]+:[0-9]+$/.test(source)))
+                throw new Error("invalid transcript source coordinate");
+            if (source && sources.has(source))
+                continue;
             if (message.from === "user" && typeof message.text === "string") {
                 const text = stripRoomAttachmentBlock(message.text);
                 const pending = this.pendingTranscriptUserEchoes.get(id);
@@ -628,15 +723,16 @@ export class RoomManager {
                     pending.shift();
                 if (pending?.length === 0)
                     this.pendingTranscriptUserEchoes.delete(id);
-                // `send` already persisted and broadcast this exact user turn. The
-                // transcript remains authoritative for agent/tool output, but must not
-                // render a second copy of the prompt.
                 if (!matched)
                     this.append(id, { ...message, text });
+                else if (source)
+                    this.append(id, { from: "system", type: "transcript_echo", transcriptSource: source });
             }
             else {
                 this.append(id, message);
             }
+            if (source)
+                sources.add(source);
         }
     }
     /**

package/dist/panels/management.js

@@ -396,6 +396,12 @@ export function createPanelManagement(options) {
                 source,
                 expectedRevision: current?.revision ?? null,
                 compatibility: compatibility(preview),
+                ...(current
+                    ? {
+                        installedVersion: current.app.version,
+                        installedPermissions: [...current.app.permissions],
+                    }
+                    : {}),
             };
             reviews.set(reviewToken, {
                 owner: context.ownerId,
@@ -458,7 +464,12 @@ export function createPanelManagement(options) {
                 preview: publicPreview,
                 expectedRevision: currentRevision,
                 compatibility: compatibility(preview),
-                ...(current ? { installedVersion: current.app.version } : {}),
+                ...(current
+                    ? {
+                        installedVersion: current.app.version,
+                        installedPermissions: [...current.app.permissions],
+                    }
+                    : {}),
             };
             reviews.set(value.reviewToken, {
                 owner: context.ownerId,

package/dist/panels/runtime-services.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { chmod, link, lstat, mkdir, open, opendir, realpath, rename, rm, writeFile, } from "node:fs/promises";
 import { basename, dirname, extname, isAbsolute, join, resolve, sep } from "node:path";
-import { acquireLockOnPath } from "@cjhyy/code-shell-core/internal";
+import { acquireLockOnPath, acquireWorkspaceWriteLock } from "@cjhyy/code-shell-core/internal";
 import { DEFAULT_PANEL_APP_STORAGE_QUOTA_BYTES, panelAppStorageSnapshot, panelAppStorageChange, applyPanelAppStorageChange, panelAppStorageKey, panelAppStoragePath, preparePanelAppStorage, readPanelAppStorage, writePanelAppStorage, } from "./storage-store.js";
 const MAX_READ_BYTES = 480 * 1024;
 const MAX_WRITE_BYTES = 384 * 1024;
@@ -390,7 +390,15 @@ export class PanelRuntimeServices {
             const parent = await this.openPath(root, dirname(path), true);
             const stableTarget = join(parent.path, basename(path));
             const temporary = join(parent.path, `.${basename(path)}.${randomUUID()}.tmp`);
+            let releaseWorkspaceLock;
+            let outcome;
             try {
+                await parent.verify();
+                releaseWorkspaceLock = await acquireWorkspaceWriteLock(parent.path, basename(path));
+                await parent.verify();
+                await this.root(scope);
+                await authorized(scope);
+                await parent.verify();
                 let modifiedAt = null, currentRevision = null, mode = 0o644;
                 let existing;
                 try {
@@ -459,17 +467,34 @@ export class PanelRuntimeServices {
                     await rename(temporary, stableTarget);
                 await chmod(stableTarget, mode).catch(() => { });
                 const metadata = await lstat(stableTarget);
-                return {
-                    path,
-                    size: bytes.length,
-                    modifiedAt: metadata.mtimeMs,
-                    revision: revision(bytes),
+                outcome = {
+                    ok: true,
+                    value: {
+                        path,
+                        size: bytes.length,
+                        modifiedAt: metadata.mtimeMs,
+                        revision: revision(bytes),
+                    },
                 };
             }
+            catch (error) {
+                outcome = { ok: false, error };
+            }
+            await rm(temporary, { force: true }).catch(() => { });
+            try {
+                await releaseWorkspaceLock?.();
+            }
+            catch (error) {
+                if (!outcome.ok)
+                    throw new AggregateError([outcome.error, error], `${String(outcome.error)}; ${String(error)}`, { cause: error });
+                throw error;
+            }
             finally {
-                await rm(temporary, { force: true }).catch(() => { });
                 await parent.close();
             }
+            if (!outcome.ok)
+                throw outcome.error;
+            return outcome.value;
         });
     }
 }

package/dist/panels/types.d.ts

@@ -57,11 +57,13 @@ export interface PanelReview {
     source: PanelGitSource;
     expectedRevision: string | null;
     compatibility: PanelCompatibility;
-}
-/** Trusted native hosts may review local sources without exposing paths to Web routes. */
-export interface PanelProjectReview extends Omit<PanelReview, "source"> {
+    /** The installed package selected for this project, when its manifest is available. */
     installedVersion?: string;
+    /** Reviewed permissions of that same installed package; an empty array is a known baseline. */
+    installedPermissions?: PanelAppPreview["permissions"];
 }
+/** Trusted native hosts may review local sources without exposing paths to Web routes. */
+export type PanelProjectReview = Omit<PanelReview, "source">;
 export interface PanelOperationContext {
     ownerId: string;
     authorize: () => boolean | Promise<boolean>;

package/dist/project-runtime/account-adoption.d.ts

@@ -0,0 +1,34 @@
+import { fsyncSync } from "node:fs";
+import { type CloudAccountBinding } from "./account-binding.js";
+export interface CloudAccountAdoptionOptions {
+    dataDir: string;
+    /** A new private directory outside the source. Authority evidence contains password hashes. */
+    evidenceDirectory: string;
+    accountOrigin: string;
+    accountId: string;
+    /** Both identities must be explicitly reviewed from the existing offline installation. */
+    installationId: string;
+    ownerId: string;
+    legacyUsername: string;
+    /** Fault seam; no user request can configure these hooks. */
+    io?: {
+        fsync?: typeof fsyncSync;
+    };
+}
+/** Read-only operator review; private runtime passwords and Hub hashes are excluded. */
+export declare function inspectCloudAccountAdoption(dataDir: string): {
+    installationId: string;
+    owners: any;
+    accountBinding: CloudAccountBinding | null;
+    projects: {
+        id: string;
+        status: import("./registry.js").ProjectStatus;
+        generation: number;
+    }[];
+    pending: boolean;
+};
+/** Offline, explicit adoption. Never rolls back or guesses authority from a username. */
+export declare function adoptCloudAccount(options: CloudAccountAdoptionOptions): {
+    binding: CloudAccountBinding;
+    evidenceDirectory: string;
+};

package/dist/project-runtime/account-adoption.js

@@ -0,0 +1,280 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants, closeSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { HubAuthStore } from "../hub/auth-store.js";
+import { CLOUD_ADOPTION_PENDING, isCloudAccountBinding, isCloudAccountOrigin, } from "./account-binding.js";
+import { ProjectRegistry } from "./registry.js";
+const sha = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
+const FORMAT = "codeshell.cloud-account-adoption";
+const SOURCES = [
+    "project-control/registry.json",
+    "project-control/initialized",
+    "hub/auth.json",
+];
+function privateBytes(file, maximum = 1024 * 1024) {
+    const before = lstatSync(file);
+    if (!before.isFile() ||
+        before.isSymbolicLink() ||
+        before.nlink !== 1 ||
+        before.mode & 0o077 ||
+        before.size > maximum)
+        throw new Error("Adoption evidence must be a bounded private regular file.");
+    const fd = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const after = fstatSync(fd);
+        if (after.dev !== before.dev ||
+            after.ino !== before.ino ||
+            after.nlink !== 1 ||
+            after.size !== before.size)
+            throw new Error("Adoption source changed while opening.");
+        const bytes = readFileSync(fd);
+        if (bytes.length !== before.size || bytes.length > maximum)
+            throw new Error("Adoption source changed while reading.");
+        return bytes;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function ordinaryDirectory(path) {
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.mode & 0o077)
+        throw new Error("Adoption requires private ordinary directories.");
+    return stat;
+}
+/** Read-only operator review; private runtime passwords and Hub hashes are excluded. */
+export function inspectCloudAccountAdoption(dataDir) {
+    const source = realpathSync(dataDir);
+    if (source !== resolve(dataDir))
+        throw new Error("Adoption source must be canonical.");
+    ordinaryDirectory(source);
+    for (const name of SOURCES)
+        privateBytes(join(source, name));
+    const registry = new ProjectRegistry(source, Date.now, { offlineAccountAdoption: true });
+    try {
+        const data = JSON.parse(privateBytes(join(source, SOURCES[0])).toString("utf8"));
+        return {
+            installationId: registry.installationId,
+            owners: data.owners,
+            accountBinding: registry.accountBinding ?? null,
+            projects: registry.all().map(({ id, status, generation }) => ({ id, status, generation })),
+            pending: existsSync(join(source, "project-control", CLOUD_ADOPTION_PENDING)),
+        };
+    }
+    finally {
+        registry.close();
+    }
+}
+/** Offline, explicit adoption. Never rolls back or guesses authority from a username. */
+export function adoptCloudAccount(options) {
+    if (!isCloudAccountOrigin(options.accountOrigin) ||
+        !UUID.test(options.accountId) ||
+        !UUID.test(options.ownerId) ||
+        !UUID.test(options.installationId))
+        throw new Error("Explicit Cloud/Account UUIDs and exact Account origin are required.");
+    const source = realpathSync(options.dataDir);
+    if (source !== resolve(options.dataDir))
+        throw new Error("Adoption source must be canonical.");
+    const sourceStat = ordinaryDirectory(source);
+    const control = join(source, "project-control");
+    const controlStat = ordinaryDirectory(control);
+    ordinaryDirectory(join(source, "hub"));
+    const destination = resolve(options.evidenceDirectory);
+    const parent = realpathSync(dirname(destination));
+    ordinaryDirectory(parent);
+    if (parent !== dirname(destination))
+        throw new Error("Evidence destination must have a canonical parent.");
+    const rel = relative(source, destination);
+    if (!rel || (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`)))
+        throw new Error("Preserve evidence outside the installation.");
+    // Never initialize a missing/wrong installation while performing adoption.
+    for (const name of SOURCES)
+        privateBytes(join(source, name));
+    const flush = options.io?.fsync ?? fsyncSync;
+    const sync = (path) => {
+        const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        try {
+            flush(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    };
+    const save = (file, bytes) => {
+        if (existsSync(file)) {
+            if (!privateBytes(file).equals(bytes))
+                throw new Error("Adoption evidence changed; preserve it for diagnosis.");
+        }
+        else {
+            const fd = openSync(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+            try {
+                writeFileSync(fd, bytes);
+                flush(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        sync(file);
+        sync(dirname(file));
+    };
+    const registry = new ProjectRegistry(source, Date.now, {
+        fsync: flush,
+        offlineAccountAdoption: true,
+    });
+    try {
+        if (registry.installationId !== options.installationId ||
+            registry.all().some((project) => project.status !== "stopped"))
+            throw new Error("Adoption requires the reviewed installation with all projects stopped.");
+        if (!existsSync(destination)) {
+            mkdirSync(destination, { mode: 0o700 });
+            sync(parent);
+        }
+        ordinaryDirectory(destination);
+        const receiptPath = join(destination, "receipt.json");
+        let receipt;
+        if (existsSync(receiptPath)) {
+            receipt = JSON.parse(privateBytes(receiptPath).toString("utf8"));
+            if (receipt.format !== FORMAT ||
+                receipt.version !== 1 ||
+                !isCloudAccountBinding(receipt.binding) ||
+                receipt.source !== source ||
+                receipt.sourceDev !== sourceStat.dev ||
+                receipt.sourceIno !== sourceStat.ino ||
+                receipt.controllerDev !== controlStat.dev ||
+                receipt.controllerIno !== controlStat.ino ||
+                receipt.installationId !== options.installationId ||
+                receipt.binding.accountOrigin !== options.accountOrigin ||
+                receipt.binding.accountId !== options.accountId ||
+                receipt.binding.ownerId !== options.ownerId)
+                throw new Error("Adoption receipt does not match this explicit source and destination.");
+        }
+        else {
+            if (registry.accountBinding)
+                throw new Error("Bound Cloud requires its original adoption receipt.");
+            const originalRegistry = privateBytes(join(source, SOURCES[0]));
+            const data = JSON.parse(originalRegistry.toString("utf8"));
+            const auth = privateBytes(join(source, SOURCES[2]));
+            const authData = JSON.parse(auth.toString("utf8"));
+            const hub = new HubAuthStore({ dataDir: source });
+            if (!hub.isInitialized() ||
+                data.version !== 1 ||
+                data.owners.length !== 1 ||
+                data.owners[0].id !== options.ownerId ||
+                data.owners[0].username !== options.legacyUsername ||
+                authData.account?.username !== options.legacyUsername)
+                throw new Error("Explicit legacy owner must match the sole initialized operator.");
+            const binding = {
+                version: 1,
+                accountOrigin: options.accountOrigin,
+                accountId: options.accountId,
+                ownerId: options.ownerId,
+                managementEpoch: randomUUID(),
+                createdAt: Date.now(),
+            };
+            const bound = { ...data, version: 2, accountBinding: binding };
+            const revoked = { ...authData, sessions: [] };
+            receipt = {
+                format: FORMAT,
+                version: 1,
+                source,
+                sourceDev: sourceStat.dev,
+                sourceIno: sourceStat.ino,
+                controllerDev: controlStat.dev,
+                controllerIno: controlStat.ino,
+                installationId: options.installationId,
+                binding,
+                originals: {},
+                registryAfter: sha(Buffer.from(JSON.stringify(bound, null, 2) + "\n")),
+                authAfter: sha(Buffer.from(JSON.stringify(revoked, null, 2))),
+            };
+            for (const name of SOURCES) {
+                const bytes = privateBytes(join(source, name));
+                receipt.originals[name] = sha(bytes);
+                save(join(destination, name.replaceAll("/", "--")), bytes);
+            }
+            // Original evidence is fully flushed before publishing any adoption barrier.
+            save(receiptPath, Buffer.from(JSON.stringify(receipt, null, 2) + "\n"));
+        }
+        for (const name of SOURCES) {
+            const original = privateBytes(join(destination, name.replaceAll("/", "--")));
+            if (sha(original) !== receipt.originals[name])
+                throw new Error("Adoption evidence checksum mismatch.");
+        }
+        const originalData = JSON.parse(privateBytes(join(destination, SOURCES[0].replaceAll("/", "--"))).toString("utf8"));
+        const originalAuth = JSON.parse(privateBytes(join(destination, SOURCES[2].replaceAll("/", "--"))).toString("utf8"));
+        if (originalData.version !== 1 ||
+            originalData.installationId !== options.installationId ||
+            originalData.owners?.length !== 1 ||
+            originalData.owners[0].id !== options.ownerId ||
+            originalData.owners[0].username !== options.legacyUsername ||
+            originalAuth.account?.username !== options.legacyUsername ||
+            receipt.registryAfter !==
+                sha(Buffer.from(JSON.stringify({ ...originalData, version: 2, accountBinding: receipt.binding }, null, 2) + "\n")) ||
+            receipt.authAfter !==
+                sha(Buffer.from(JSON.stringify({ ...originalAuth, sessions: [] }, null, 2))))
+            throw new Error("Adoption receipt does not preserve the explicitly reviewed legacy authority.");
+        sync(receiptPath);
+        sync(destination);
+        const assertSource = () => {
+            const current = ordinaryDirectory(source), controller = ordinaryDirectory(control);
+            if (current.dev !== receipt.sourceDev ||
+                current.ino !== receipt.sourceIno ||
+                controller.dev !== receipt.controllerDev ||
+                controller.ino !== receipt.controllerIno)
+                throw new Error("Adoption source directory changed.");
+            for (const name of SOURCES) {
+                const value = sha(privateBytes(join(source, name)));
+                const allowed = [
+                    receipt.originals[name],
+                    name === SOURCES[0]
+                        ? receipt.registryAfter
+                        : name === SOURCES[2]
+                            ? receipt.authAfter
+                            : undefined,
+                ];
+                if (!allowed.includes(value))
+                    throw new Error("Adoption source changed; preserve evidence and diagnose before retrying.");
+            }
+        };
+        assertSource();
+        const pending = join(control, CLOUD_ADOPTION_PENDING);
+        const marker = Buffer.from(JSON.stringify({
+            format: FORMAT,
+            version: 1,
+            evidenceDirectory: destination,
+            receipt: sha(privateBytes(receiptPath)),
+        }) + "\n");
+        save(pending, marker);
+        assertSource();
+        if (!registry.accountBinding)
+            registry.bindAccount(receipt.binding);
+        if (JSON.stringify(registry.accountBinding) !== JSON.stringify(receipt.binding) ||
+            sha(privateBytes(join(source, SOURCES[0]))) !== receipt.registryAfter)
+            throw new Error("Cloud adoption binding changed.");
+        sync(join(source, SOURCES[0]));
+        sync(control);
+        assertSource();
+        new HubAuthStore({ dataDir: source }).revokeAllSessions();
+        sync(join(source, SOURCES[2]));
+        sync(join(source, "hub"));
+        assertSource();
+        save(join(destination, "completed.json"), Buffer.from(JSON.stringify({
+            format: FORMAT,
+            receipt: sha(privateBytes(receiptPath)),
+            registry: receipt.registryAfter,
+            auth: receipt.authAfter,
+        }) + "\n"));
+        if (existsSync(pending)) {
+            if (!privateBytes(pending).equals(marker))
+                throw new Error("Adoption pending marker changed.");
+            unlinkSync(pending);
+            sync(control);
+        }
+        return { binding: { ...receipt.binding }, evidenceDirectory: destination };
+    }
+    finally {
+        registry.close();
+    }
+}