feat(host): back up hosted and compute channels and restore backups as new channels (#435)

* feat(host): back up hosted and compute channels and restore backups as new channels

`ace backup` now takes a hosted or cloud compute channel's pi state from its service with a new
`backup` transfer action, which reads one consistent snapshot without freezing the channel.
`ace restore` verifies a backup and adds it as a new local channel with a new ID and lane prefix.

Why: packages/channel/src/transfer.ts#function backupSnapshot | the read stays one transaction on the channel's DurableSqlite, which serializes every pi read and write, so a backup needs no freeze
Why: apps/host/src/backup.ts#function restore | a restored copy always gets a new ID and lane prefix so it can never run as the original channel
Why: apps/host/src/backup.ts#function exported | the service is asked before the destination exists, so a refusal or an older service leaves nothing behind

* chore: confirm and record lane notes for hosted backups

* lane: sync hosted-backup memory

Author: iamnbutler

.lane/memory/apps/host/src/backup.ts/01M4ZYZJRBTSD6WJVT8HEH8XQ0-a-restored-copy-always-gets.md

@@ -0,0 +1,12 @@
+---
+id: 01M4ZYZJRBTSD6WJVT8HEH8XQ0
+anchor: function restore
+created: 2026-10-15T14:20:42Z
+norm: '1'
+sig: 05c78f711a9a9228
+body_hash: 61b995cf9ff2906b
+raw_hash: a42fcbbc15619cac
+lines: 119-158
+---
+
+a restored copy always gets a new ID and lane prefix so it can never run as the original channel

.lane/memory/apps/host/src/backup.ts/01M4ZYZJRPVAT5B4AKS3TAM4N1-the-service-is-asked-before.md

@@ -0,0 +1,12 @@
+---
+id: 01M4ZYZJRPVAT5B4AKS3TAM4N1
+anchor: function exported
+created: 2026-10-15T14:20:42Z
+norm: '1'
+sig: b4af02e0f6ffc6ee
+body_hash: ed863c361f4c6e35
+raw_hash: e6c5fea64fdd5bb4
+lines: 52-69
+---
+
+the service is asked before the destination exists, so a refusal or an older service leaves nothing behind

.lane/memory/apps/host/src/cli.ts/01M4YY5SXJFQK8VXT78X1E0KAE-every-command-but-serve-must.md

@@ -4,9 +4,9 @@ anchor: function main
 created: 2026-10-15T04:47:23Z
 norm: '1'
 sig: 7d5d3f63a3bddde4
-body_hash: 6fa49f3beb6a0972
-raw_hash: e2afff512c7cdab5
-vouched: 2026-10-15T06:07:50Z
+body_hash: 415212bf021919a0
+raw_hash: c683df669514ae50
+vouched: 2026-10-15T14:20:47Z
 lines: 253-482
 ---
 

.lane/memory/packages/channel/src/transfer.ts/01M4ZYZJR07D3AKHPK6ZHZF7HB-the-read-stays-one-transacti.md

@@ -0,0 +1,12 @@
+---
+id: 01M4ZYZJR07D3AKHPK6ZHZF7HB
+anchor: function backupSnapshot
+created: 2026-10-15T14:20:42Z
+norm: '1'
+sig: 6fc0ddf258dd3aea
+body_hash: 65320d8ff51c68e2
+raw_hash: 44f3f3a44af33ee7
+lines: 233-236
+---
+
+the read stays one transaction on the channel's DurableSqlite, which serializes every pi read and write, so a backup needs no freeze

AGENTS.md

@@ -79,7 +79,7 @@ bun install
 lane install hooks  # once per clone; captures `Why: <path>[#<anchor>] | <text>` commit trailers as notes
 bun ace --help   # CLI
 bun ace tabs --json  # discover open windows and tabs before targeting a tab rename
-bun ace backup <channel> <new-directory>  # local channel data, including committed WAL entries
+bun ace backup <channel> <new-directory>  # local or hosted channel data; `ace restore` adds it as a new channel
 bun types        # type checks
 bun run ci       # dprint + oxlint
 bun run fix      # apply formatting and lint fixes

apps/host/src/backup.ts

@@ -1,9 +1,25 @@
 import { createHash } from "node:crypto";
-import { chmodSync, createReadStream, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import {
+	chmodSync,
+	copyFileSync,
+	createReadStream,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
 import { join, resolve } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 
+import { openNodeSqliteDatabase } from "@earendil-works/pi-durable/storage/sqlite/node";
+
+import { importSnapshot, type Snapshot } from "@ace/channel/transfer";
+
 import * as catalog from "./catalog";
+import { hostedAuth } from "./client";
+import { refusal } from "./http";
+import { project } from "./manage";
 
 async function checksum(path: string): Promise<string> {
 	const hash = createHash("sha256");
@@ -32,20 +48,45 @@ function snapshot(source: string, target: string): void {
 	}
 }
 
+/** The hosting service's consistent export of a hosted channel's pi state, taken without freezing it. */
+async function exported(record: catalog.Listing): Promise<Snapshot> {
+	const url = record.hosted!;
+	let response: Response;
+	try {
+		response = await fetch(`${url}/channels/${record.id}/transfer`, {
+			method: "POST",
+			headers: { ...(await hostedAuth()), "content-type": "application/json" },
+			body: JSON.stringify({ action: "backup" }),
+		});
+	} catch (error) {
+		throw new Error(`Could not reach ${url}: ${(error as Error).message}.`, { cause: error });
+	}
+	if (response.ok) return await response.json() as Snapshot;
+	if (response.status === 400 && (await response.clone().text()).includes("Unknown transfer")) {
+		throw new Error(`${url} predates hosted channel backups; redeploy it to back this channel up.`);
+	}
+	throw new Error(await refusal(response, "The hosting service"));
+}
+
+function save(path: string, value: unknown): void {
+	writeFileSync(path, `${JSON.stringify(value, null, "\t")}\n`, { mode: 0o600, flag: "wx" });
+}
+
 /** A channel storage snapshot; project files and lane worktrees need their own backup. */
 export async function backup(record: catalog.Listing, directory: string): Promise<string> {
-	if (record.hosted) throw new Error("Hosted channel backups must be taken on the hosting service");
+	// Read before creating the destination, so a refused or unreachable service leaves nothing behind.
+	const hosted = record.hosted ? await exported(record) : undefined;
 	const path = resolve(directory);
 	// An existing destination must never be overwritten or removed by failed-backup cleanup.
 	mkdirSync(path, { mode: 0o700 });
 	try {
 		const source = catalog.paths(record.id);
-		writeFileSync(join(path, "channel.json"), `${JSON.stringify(record, null, "\t")}\n`, {
-			mode: 0o600,
-			flag: "wx",
-		});
+		save(join(path, "channel.json"), record);
 		const names = ["channel.json"];
-		if (existsSync(source.storage)) {
+		if (hosted) {
+			save(join(path, "snapshot.json"), hosted);
+			names.push("snapshot.json");
+		} else if (existsSync(source.storage)) {
 			snapshot(source.storage, join(path, "channel.sqlite"));
 			names.push("channel.sqlite");
 		}
@@ -59,17 +100,59 @@ export async function backup(record: catalog.Listing, directory: string): Promis
 			channel: record.id,
 			home: catalog.home,
 			project: record.project,
-			lanes: source.lanes,
+			...(hosted ? { hosted: record.hosted, digest: hosted.digest } : { lanes: source.lanes }),
 			files,
 		};
 		// Written last: a partial directory is never advertised as a completed backup.
-		writeFileSync(join(path, "backup.json"), `${JSON.stringify(manifest, null, "\t")}\n`, {
-			mode: 0o600,
-			flag: "wx",
-		});
+		save(join(path, "backup.json"), manifest);
 		return path;
 	} catch (error) {
 		rmSync(path, { recursive: true, force: true });
 		throw error;
 	}
 }
+
+/**
+ * A backup as a new local channel. The new ID and lane prefix keep it from ever running as the
+ * original, which may still be live here or on its hosting service.
+ */
+export async function restore(directory: string, dir?: string): Promise<catalog.Listing> {
+	const path = resolve(directory);
+	const manifest = JSON.parse(readFileSync(join(path, "backup.json"), "utf8")) as {
+		format: number;
+		files: { path: string; sha256: string }[];
+	};
+	if (manifest.format !== 1) throw new Error(`Unsupported backup format ${manifest.format}`);
+	for (const file of manifest.files) {
+		if (await checksum(join(path, file.path)) !== file.sha256) {
+			throw new Error(`${file.path} does not match its checksum in backup.json`);
+		}
+	}
+	const original = JSON.parse(readFileSync(join(path, "channel.json"), "utf8")) as catalog.Listing;
+	const record: catalog.Listing = {
+		...catalog.draft(await project(dir || original.project), original.model),
+		name: original.name,
+		named: original.named !== false,
+		summary: original.summary,
+	};
+	const { base, storage } = catalog.paths(record.id);
+	mkdirSync(base, { recursive: true });
+	try {
+		const names = new Set(manifest.files.map((file) => file.path));
+		if (names.has("snapshot.json")) {
+			const db = await openNodeSqliteDatabase(storage);
+			try {
+				await importSnapshot(db, JSON.parse(readFileSync(join(path, "snapshot.json"), "utf8")));
+			} finally {
+				await db.close();
+			}
+		} else if (names.has("channel.sqlite")) {
+			copyFileSync(join(path, "channel.sqlite"), storage);
+		}
+		// Saved last: the catalog lists the channel only once its store is complete.
+		return catalog.save(record);
+	} catch (error) {
+		rmSync(base, { recursive: true, force: true });
+		throw error;
+	}
+}

apps/host/src/cli.ts

@@ -5,7 +5,7 @@ import { parseArgs } from "node:util";
 import type { ChannelInfo, ChatId, Event, Request } from "@ace/channel/protocol";
 
 import { appUrl, token } from "./auth";
-import { backup } from "./backup";
+import { backup, restore } from "./backup";
 import * as catalog from "./catalog";
 import { Connection, request } from "./client";
 import { config } from "./config";
@@ -32,7 +32,8 @@ const HELP = `ace — channels on this host
   ace rename <channel> <name>                   rename without changing its lanes
   ace tabs [--port <port>] [--json]              list open windows and their current channel's tabs
   ace tab rename <window> <channel> <tab> <name>  rename one tab; an empty name restores its default
-  ace backup <channel> <directory>              snapshot local channel data into a new directory
+  ace backup <channel> <directory>              snapshot a local or hosted channel's data into a new directory
+  ace restore <directory> [--project <dir>]      restore a backup as a new local channel
   ace say <channel> [--chat <id>] <text…>        post without invoking the agent
   ace ask <channel> [--chat <id>] [--model <provider/id>] [--detach] <text…>
   ace watch <channel> [--chat <id>]
@@ -332,6 +333,13 @@ async function main() {
 			}
 			return;
 		}
+		case "restore": {
+			if (positionals.length !== 2) {
+				throw new Error("ace restore <backup-directory> [--project <dir>]");
+			}
+			const record = await restore(ref!, flags.project);
+			return console.log(`${record.name}\t${record.id}`);
+		}
 		case "models": {
 			for (const m of await models()) console.log(`${m.provider}/${m.modelId}`);
 			return;

docs/architecture.md

@@ -189,8 +189,9 @@ Reachable peers forward the live listing; directory-only fallback listings clear
 animating from a stale cache, even for hosted channels.
 
 Channel data survives app replacement and upgrades. `ace backup` takes a verified SQLite snapshot
-of a local channel while it runs, alongside its catalog record. Project files and lane worktrees
-have their own repository backup. Stored format changes require migrations; see [data](data.md).
+of a local channel while it runs, or a hosted or compute channel's transfer snapshot from its
+service without freezing it, alongside its catalog record. `ace restore` adds a backup as a new
+local channel with a new ID. Project files and lane worktrees have their own repository backup. Stored format changes require migrations; see [data](data.md).
 
 Opening a folder adds a project to the host's `projects.json`, independently of channel creation
 or model credentials. This is a list of local folders, not channel history. Channels start only in

docs/data.md

@@ -27,31 +27,64 @@ started before Ace used it. SQLite may have
 committed data in `channel.sqlite-wal`, so copying only a live `channel.sqlite` is not a backup.
 The socket, worker PID, and logs are process state, not durable channel content.
 
-## Back up a local channel
+## Back up a channel
 
 Run `bun ace backup <channel> <new-directory>` from the checkout, or `ace backup` (`ace-canary backup`
-for Canary) from the command the app installs. The destination's parent must exist; the destination itself must be new. Backups include
-archived channels and work without starting dormant workers or loading provider credentials.
+for Canary) from the command the app installs. It works for local, hosted, and cloud compute
+channels this host owns. The destination's parent must exist; the destination itself must be new.
+Backups include archived channels and work without freezing the channel or stopping its work. Failed backups remove only their newly created
+output, and the directory and files are private to the current OS user. Store backups with the
+same care as the original chats and tool output.
 
-The command uses SQLite's [VACUUM INTO](https://www.sqlite.org/lang_vacuum.html#vacuum_with_an_into_clause)
-to capture a consistent snapshot, including committed WAL entries, while a worker continues
-running. It opens the source read-only, checks the output's integrity, and writes:
+Every backup writes:
 
-- `channel.json`: the channel's identity, owner, project, optional initial model, and when its
-  transcript last grew.
-- `channel.sqlite`: all pi state at the snapshot point, if the channel has been opened before.
+- `channel.json`: the channel's catalog record: identity, owner, project, optional initial model,
+  when its transcript last grew, and for a hosted channel its service URL.
+- The channel's pi state at the snapshot point, if it has any (below).
 - `backup.json`: format version, source paths, creation time, and SHA-256 checksums. This file is
-  written last to mark a complete backup. Failed backups remove only their newly created output.
-
-The directory and files are private to the current OS user. Store backups with the same care as
-the original chats and tool output. Hosted channels need backups from their hosting service;
-their local catalog entry is insufficient.
+  written last to mark a complete backup.
+
+**Local channels.** The command uses SQLite's
+[VACUUM INTO](https://www.sqlite.org/lang_vacuum.html#vacuum_with_an_into_clause) to capture a
+consistent snapshot, including committed WAL entries, while a worker continues running. It opens
+the source read-only, checks the output's integrity, and writes `channel.sqlite`. It needs no
+provider credentials and does not start dormant workers.
+
+**Hosted and cloud compute channels.** The host asks the hosting service for the channel's pi
+state with `POST /channels/:id/transfer` `{ "action": "backup" }`, authenticated with the team's
+`ACE_SECRET`, and writes the answer as `snapshot.json`. This is the same version 1 snapshot format
+moves use: every pi table, with a SHA-256 digest of its canonical encoding, which `backup.json`
+also records. The service reads it in one transaction on the channel's Durable Object, where all
+pi reads and writes run one at a time, so the snapshot is consistent without freezing the channel;
+clients stay connected and runs continue. A snapshot is limited to 32 MiB, and a larger channel is
+refused with that reason. A service deployed before this action existed is reported as needing a
+redeploy. Inactive copies left by an unfinished move are refused, since they are not the channel.
+
+A backup taken during a run records the run as unfinished, as a local snapshot does.
 
 Project files, lane worktrees (including uncommitted and untracked changes), repository Git data,
-opened-project preferences, and Keychain items need their own backups. A channel snapshot keeps
-the original working-directory paths; it is not a way to move lanes to another machine.
+opened-project preferences, and Keychain items need their own backups. A cloud compute channel's
+workspace files are in its container and are covered by its
+[checkpoint](https://github.com/githubnext/ace/issues/413), not by `ace backup`. A channel snapshot
+keeps the original working-directory paths; it is not a way to move lanes to another machine.
+
+## Restore as a new channel
+
+`ace restore <backup-directory> [--project <dir>]` verifies every file against `backup.json`, then
+adds the backup as a new local channel on this host, in the recorded project or `--project`. A
+hosted snapshot is imported and checked against its digest; a local `channel.sqlite` is copied. The
+copy has a new ID and a new lane branch prefix, so it can never run as the original channel, which
+may still be live here or on its service. Its pi metadata keeps the original name, so refer to it by
+ID while both exist. The backup itself is left unchanged, and a failed restore removes only the new
+channel's directory.
 
-## Recover on the same machine
+The restored chats keep the original working-directory and lane paths. If the backup was taken
+during a run, the copy resumes that run when it first opens, and pi reports interrupted tools that
+cannot safely be rerun. Stop the original channel's work first if both would use the same lanes.
+
+## Recover in place on the same machine
+
+To return a local channel to a snapshot under its original ID:
 
 1. Keep the backup untouched and verify its files against the SHA-256 values in `backup.json`.
 2. Stop Ace Helper in Settings and stop any command-line host for this profile. Ensure the
@@ -66,7 +99,8 @@ the original working-directory paths; it is not a way to move lanes to another m
    pi reports interrupted tools that cannot safely be rerun. Do not run a second copy of the same
    snapshot against the same lane paths.
 
-Automated restore and moving backups across machines are not implemented.
+A hosted channel is not replaced in place; restore its backup as a new channel. Moving backups
+across machines is not implemented.
 
 ## Upgrade contract
 
@@ -144,3 +178,14 @@ build they reopened shared and unshared respectively, and the unshared channel's
 revisions matched its backup. Turning desktop tools off on the channel without stored settings
 kept it shared across a worker restart. A new channel stored `shared: false` at creation, refused a
 teammate's agent invocation, and kept the setting across a restart.
+
+The October 15, 2026 hosted backup check ran local `wrangler dev` copies of `services/channel` and
+`services/compute` (containers off) with a loopback source host. A hosted channel with this host's
+workspace and a compute channel each held messages and real `openai/gpt-5-mini` runs, the hosted
+one including a `bash` tool result. `ace backup` saved both while they were active; a third backup
+taken mid-run kept the run's tasks as `waiting` and `running` while the live run finished and a
+message posted during it was admitted. `ace restore` imported each as a new local channel whose
+pi tables hashed to the backup digests. The restored copies replayed the same history and answered
+from it with a real model, and the mid-run copy reported the interrupted tool and reran it. The live
+channels kept answering afterwards, and a thaw request found both active, not frozen. With the
+previous service build, `ace backup` reported that the service needs a redeploy and left no output.

packages/channel/src/transfer.ts

@@ -93,8 +93,9 @@ const SEED = JSON.stringify({
 	durable_schema: [[1, SCHEMA]],
 	durable_metadata: [[1, "2", 1]],
 });
-// Durable Objects keep their KV API in `__cf_kv`; SQLite keeps its own `sqlite_*` tables.
-const INTERNAL = /^(sqlite_|_cf_|__cf_)/i;
+// Durable Objects keep their KV API in `__cf_kv`, local `wrangler dev` adds `__miniflare_do_name`,
+// and SQLite keeps its own `sqlite_*` tables.
+const INTERNAL = /^(sqlite_|_cf_|__cf_|__miniflare_)/i;
 
 function encode(value: unknown): Cell {
 	if (value === null || typeof value === "string") return value;
@@ -151,7 +152,11 @@ async function sha256(bytes: Uint8Array): Promise<string> {
 async function seal(body: Omit<Snapshot, "digest">): Promise<Snapshot> {
 	const bytes = new TextEncoder().encode(canonical(body));
 	if (bytes.byteLength > MAX_SNAPSHOT) {
-		throw new Error(`Channel snapshot exceeds ${MAX_SNAPSHOT} bytes; moving it is not supported`);
+		throw new Error(
+			`The channel is larger than the ${
+				MAX_SNAPSHOT / 1024 / 1024
+			} MiB snapshot limit, so it cannot be moved or backed up`,
+		);
 	}
 	return { ...body, digest: await sha256(bytes) };
 }
@@ -221,6 +226,15 @@ export async function exportSnapshot(db: SqliteDatabase, channel: string): Promi
 	});
 }
 
+/**
+ * One consistent read of a channel database, including unfinished work: a backup records the
+ * channel as it is, and a restored copy resumes that work when it opens.
+ */
+export async function backupSnapshot(db: SqliteDatabase, channel: string): Promise<Snapshot> {
+	pinned();
+	return db.transaction((tx) => read(tx, channel));
+}
+
 function validate(snapshot: Snapshot): void {
 	if (snapshot?.format !== "ace-channel-snapshot" || snapshot.version !== 1) {
 		throw new Error("Not a version 1 Ace channel snapshot");