feat(cloud): R2 sleep persistence for cloud sessions (Phase 2b)

Persist the container's Helmor data dir to R2 so chat/session history survives
a sandbox sleep (CF wipes the disk on sleep). Per finished agent turn the serve
process folds the SQLite WAL into helmor.db (synchronous wal_checkpoint(TRUNCATE),
env-gated on HELMOR_CLOUD_AUTOPUSH); after the turn stream closes the Worker
snapshots /home/helmor to R2 in localBucket mode (excluding the git worktrees,
which are restored via autopush) and stores the DirectoryBackup handle in D1
teams.backup_handle. On cold start ensureServe restores from that handle before
launching serve. Relocate the data dir to /home/helmor (an allowed backup root)
via HELMOR_DATA_DIR in both start-serve.sh and boot.sh so serve and boot share
one DB. Zero pipeline-snapshot drift; all team UI/proxy paths unchanged.

Author: dohooo

.changeset/team-cloud-sleep-persistence.md

@@ -0,0 +1,5 @@
+---
+"helmor": patch
+---
+
+Team cloud: chat sessions now survive a sandbox going to sleep — after each turn the cloud backend snapshots its database to durable storage and restores it on the next wake.

cloud/scripts/boot.sh

@@ -22,6 +22,11 @@ HELMOR_HOME="${HELMOR_HOME:-/opt/helmor}"
 export PATH="${HELMOR_HOME}/vendor/gh:${HELMOR_HOME}:${PATH}"
 HELMOR_CLI="${HELMOR_HOME}/helmor-cli"
 
+# Phase 2b: write to the SAME data dir as `helmor serve` (under /home for backup
+# eligibility). Without this, helmor-cli would default to $HOME/helmor while serve
+# uses /home/helmor — two divergent DBs. The Worker may override via env.
+export HELMOR_DATA_DIR="${HELMOR_DATA_DIR:-/home/helmor}"
+
 : "${HELMOR_REPO_URL:?HELMOR_REPO_URL must be set (the git repo to clone)}"
 REPO_BRANCH="${HELMOR_REPO_BRANCH:-}"
 WORK_ROOT="${HELMOR_WORK_ROOT:-/workspace}"

cloud/scripts/start-serve.sh

@@ -22,6 +22,12 @@ export DISPLAY=":${DISPLAY_NUM}"
 export PATH="${HELMOR_HOME}/vendor/gh:${HELMOR_HOME}:${PATH}"
 export HELMOR_SIDECAR_PATH="${HELMOR_SIDECAR_PATH:-${HELMOR_HOME}/helmor-sidecar}"
 
+# Phase 2b: the data dir must live under an allowed backup root (/home, /workspace,
+# /tmp, /var/tmp, /app) so the Sandbox backup API can snapshot it. Default to
+# /home/helmor; the Worker may override via startProcess env. `helmor serve` AND
+# boot.sh both honor this default so they share ONE database.
+export HELMOR_DATA_DIR="${HELMOR_DATA_DIR:-/home/helmor}"
+
 # Cloud workflow closure (PR6): commit + push each finished agent turn so the
 # ephemeral sandbox disk never loses code. On by default in the container.
 export HELMOR_CLOUD_AUTOPUSH="${HELMOR_CLOUD_AUTOPUSH:-1}"

cloud/src/index.ts

@@ -8,7 +8,12 @@
 // `Authorization` header through. Blueprint: cloudflare/claude-managed-agents.
 
 import { getSandbox, proxyToSandbox, type Sandbox } from "@cloudflare/sandbox";
-import { handleTeamRoute, lookupMemberId } from "./team";
+import {
+	handleTeamRoute,
+	lookupMemberId,
+	readBackupHandle,
+	writeBackupHandle,
+} from "./team";
 
 export { Sandbox } from "@cloudflare/sandbox";
 
@@ -29,15 +34,27 @@ export interface Env {
 	 *  subscription. Phase-0 passes the whole credential through; Phase-1 will have
 	 *  the control-plane broker mint a per-turn short-lived token instead. */
 	CODEX_AUTH_JSON?: string;
+	/** R2 bucket for Sandbox backups (Phase 2b). Bound so the Sandbox DO can
+	 *  resolve BACKUP_BUCKET for localBucket-mode createBackup/restoreBackup. */
+	BACKUP_BUCKET?: R2Bucket;
 }
 
 /** Boot script staged in the image (Xvfb daemon → readiness → `helmor serve`). */
 const SERVE_START_CMD = "/usr/local/bin/helmor-start-serve";
 
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
+/** Agent-stream RPC path. After this stream closes, the in-container WAL
+ *  checkpoint (gated by HELMOR_CLOUD_AUTOPUSH) has already folded helmor.db, so
+ *  a backup taken now snapshots a consistent DB. */
+const AGENT_STREAM_PATH = "/rpc-stream/send_agent_message_stream";
+
 export default {
-	async fetch(request: Request, env: Env): Promise<Response> {
+	async fetch(
+		request: Request,
+		env: Env,
+		ctx: ExecutionContext,
+	): Promise<Response> {
 		// Security (EVERY path): strip any client-supplied X-Helmor-Member-Id up
 		// front — before proxyToSandbox — so the "never client-asserted" invariant
 		// holds on the SDK preview path too, not only the derived proxy hop. The
@@ -89,10 +106,69 @@ export default {
 		// Transparent HTTP proxy: method, path, body, and streaming responses
 		// pass straight through; headers carry the derived member id + shared
 		// companion token (see `deriveForwardedRequest`).
-		return sandbox.containerFetch(forwarded, port);
+		const response = await sandbox.containerFetch(forwarded, port);
+
+		// Phase 2b sleep persistence: ONLY for the agent-stream path, snapshot
+		// /home/helmor to R2 after the turn so the session survives sandbox
+		// sleep. We don't block the client — `waitUntil` keeps the Worker alive
+		// past the response while the backup runs. The backup must start AFTER
+		// the stream drains (the in-container WAL checkpoint runs just before the
+		// terminal `done`), so we tee the body and await the clone's completion
+		// before snapshotting. All other paths return byte-unchanged.
+		if (url.pathname === AGENT_STREAM_PATH && response.body) {
+			const [toClient, toDrain] = response.body.tee();
+			ctx.waitUntil(backupAfterStream(toDrain, sandbox, env));
+			return new Response(toClient, response);
+		}
+
+		return response;
 	},
 };
 
+/**
+ * Wait for the agent-stream body to fully drain (so the in-container WAL
+ * checkpoint + autopush that fire just before the terminal `done` have run),
+ * then snapshot the data dir to R2 and persist the handle. Best-effort: a
+ * backup failure must never surface to the client (the response already left).
+ */
+async function backupAfterStream(
+	body: ReadableStream<Uint8Array>,
+	sandbox: Sandbox,
+	env: Env,
+): Promise<void> {
+	try {
+		// Drain to EOF — resolves when the companion closes the stream, i.e.
+		// after the turn finalized (checkpoint folded helmor.db).
+		await body.pipeTo(new WritableStream());
+	} catch {
+		// A client disconnect can abort the tee; still attempt the backup with
+		// whatever is on disk — a slightly-stale snapshot beats none.
+	}
+	await backupAndStore(sandbox, env);
+}
+
+/**
+ * Snapshot `/home/helmor` (the relocated data dir) to R2 in localBucket mode
+ * and persist the returned handle in D1. Excludes the bulky, regenerable trees
+ * (workspaces are pushed to git by autopush; cache/logs/run/local-llm are
+ * disposable) so the backup is just the SQLite DB + small settings. All errors
+ * are logged and swallowed — cold-starting with an empty DB is acceptable.
+ */
+async function backupAndStore(sandbox: Sandbox, env: Env): Promise<void> {
+	try {
+		const handle = await sandbox.createBackup({
+			dir: "/home/helmor",
+			localBucket: true,
+			name: `helmor-${new Date().toISOString()}`,
+			ttl: 259200, // 3 days
+			excludes: ["workspaces", "cache", "logs", "run", "local-llm"],
+		});
+		await writeBackupHandle(env, handle);
+	} catch (error) {
+		console.error("Phase 2b backup failed", error);
+	}
+}
+
 /**
  * Build the request forwarded to the companion, deriving member identity from
  * the client's bearer (the invite token doubles as the member's capability
@@ -166,10 +242,25 @@ async function ensureServe(
 ): Promise<void> {
 	if (await healthOk(sandbox, port)) return;
 
+	// Phase 2b sleep persistence: restore the last DB snapshot BEFORE serve
+	// binds. Restore must precede serve (serve not yet running = no open handle
+	// on helmor.db, safe to overwrite). A missing/failed restore is non-fatal —
+	// the container cold-starts with an empty DB, exactly like a brand-new team.
+	try {
+		const handle = await readBackupHandle(env);
+		if (handle) await sandbox.restoreBackup(handle);
+	} catch (error) {
+		console.error("Phase 2b restore failed (cold-starting empty)", error);
+	}
+
 	await sandbox.startProcess(SERVE_START_CMD, {
 		env: {
 			HELMOR_COMPANION_TOKEN: env.HELMOR_COMPANION_TOKEN,
 			HELMOR_SERVE_PORT: String(port),
+			// Phase 2b: relocate the data dir under /home so it lands in the
+			// backed-up /home/helmor tree (createBackup dir must be under
+			// /workspace|/home|/tmp|/var/tmp|/app).
+			HELMOR_DATA_DIR: "/home/helmor",
 			...(env.GITHUB_TOKEN ? { GITHUB_TOKEN: env.GITHUB_TOKEN } : {}),
 			...(env.CODEX_AUTH_JSON ? { CODEX_AUTH_JSON: env.CODEX_AUTH_JSON } : {}),
 		},

cloud/src/team.ts

@@ -10,6 +10,7 @@
 //   - `/team/accept` is OPEN — the token itself is the credential.
 // All queries are parameterized (`prepare().bind()`) — never interpolated.
 
+import type { DirectoryBackup } from "@cloudflare/sandbox";
 import type { Env } from "./index";
 
 const TEAM_ID = "team-0";
@@ -47,6 +48,47 @@ export async function lookupMemberId(
 	return row?.member_id ?? null;
 }
 
+/**
+ * Read the stored Sandbox backup handle for this Worker's sandbox (Phase 2b).
+ * Returns null when no backup has been taken yet (cold start → empty DB), or
+ * when the stored value can't be parsed (treated as absent — re-snapshot next
+ * turn). Keyed by `HELMOR_SANDBOX_ID` so it tracks the routing key, not TEAM_ID.
+ */
+export async function readBackupHandle(
+	env: Env,
+): Promise<DirectoryBackup | null> {
+	const row = await env.DB.prepare(
+		"SELECT backup_handle FROM teams WHERE sandbox_id = ?1",
+	)
+		.bind(env.HELMOR_SANDBOX_ID)
+		.first<{ backup_handle: string | null }>();
+	if (!row?.backup_handle) return null;
+	try {
+		return JSON.parse(row.backup_handle) as DirectoryBackup;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Persist the latest Sandbox backup handle (Phase 2b). UPSERTs the single team
+ * row keyed by `id` (the PK), recording the handle JSON so the next cold start's
+ * `readBackupHandle` can restore it. Mirrors `bootstrap`'s upsert shape.
+ */
+export async function writeBackupHandle(
+	env: Env,
+	handle: DirectoryBackup,
+): Promise<void> {
+	await env.DB.prepare(
+		`INSERT INTO teams (id, sandbox_id, backup_handle) VALUES (?1, ?2, ?3)
+		 ON CONFLICT(id) DO UPDATE SET
+		   sandbox_id    = excluded.sandbox_id,
+		   backup_handle = excluded.backup_handle`,
+	)
+		.bind(TEAM_ID, env.HELMOR_SANDBOX_ID, JSON.stringify(handle))
+		.run();
+}
+
 function json(body: unknown, status = 200): Response {
 	return new Response(JSON.stringify(body), {
 		status,

cloud/wrangler.toml

@@ -41,6 +41,13 @@ binding = "DB"
 database_name = "helmor-team"
 database_id = "8eb39746-fda1-47e3-8006-2dab22175b53"
 
+# R2 bucket for Sandbox backups (Phase 2b sleep persistence). The Sandbox DO
+# resolves BACKUP_BUCKET as a native R2 binding for localBucket-mode backup/
+# restore (R2 binding + squashfs, no presigned creds / FUSE).
+[[r2_buckets]]
+binding = "BACKUP_BUCKET"
+bucket_name = "helmor-team-backups"
+
 [vars]
 # Fixed sandbox id for Phase 0 (B2 single-backend model). Phase 1 derives it
 # from the team / token.

src-tauri/src/agents/streaming/cloud_autopush.rs

@@ -51,6 +51,44 @@ pub(super) fn maybe_autopush_after_turn(working_directory: &str) {
         .ok();
 }
 
+/// Fold the SQLite WAL back into `helmor.db` after a finalized turn so the
+/// next Sandbox backup snapshots a self-contained DB file.
+///
+/// Runs SYNCHRONOUSLY (unlike `maybe_autopush_after_turn`, which detaches): the
+/// caller invokes this on the turn-finalize seam, before the terminal `done`
+/// event is emitted, so the checkpoint completes before the Worker's
+/// post-stream backup snapshots `helmor.db`. A `TRUNCATE` checkpoint also keeps
+/// the `-wal` sidecar from being captured separately by the squashfs backup.
+///
+/// No-op (returns immediately) on the desktop — the env gate is unset there, so
+/// this never opens a connection and changes no existing behavior.
+pub(super) fn maybe_checkpoint_db_after_turn() {
+    if !enabled() {
+        return;
+    }
+    if let Err(error) = checkpoint_db() {
+        tracing::warn!(
+            error = %format!("{error:#}"),
+            "cloud WAL checkpoint failed"
+        );
+    }
+}
+
+fn checkpoint_db() -> anyhow::Result<()> {
+    let path = crate::data_dir::db_path()?;
+    // Short-lived connection: open, checkpoint, drop. This seam runs after
+    // `persist_result_and_finalize` has COMMITTED (the writer pool slot is still
+    // held but carries no open transaction), so TRUNCATE folds every WAL frame
+    // into helmor.db. SQLite's TRUNCATE checkpoint never errors or blocks even
+    // with other pool connections open — at worst the zero-truncation step is
+    // skipped when a concurrent reader pins an active snapshot, in which case the
+    // -wal/-shm sidecars (also captured by the backup) keep restore consistent.
+    let conn = rusqlite::Connection::open(&path)?;
+    conn.pragma_update(None, "wal_checkpoint", "TRUNCATE")?;
+    tracing::debug!(db = %path.display(), "cloud WAL checkpoint (TRUNCATE) complete");
+    Ok(())
+}
+
 fn autopush(workspace_dir: &Path) -> anyhow::Result<()> {
     // Nothing changed → nothing to do (the common case mid-conversation when a
     // turn only read files / answered a question).
@@ -88,3 +126,72 @@ fn autopush(workspace_dir: &Path) -> anyhow::Result<()> {
     tracing::info!(dir = %dir, "cloud auto-push: committed + pushed turn changes");
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::data_dir::TEST_ENV_LOCK;
+    use std::env;
+
+    /// Open `helmor.db` in WAL mode and write a row so a non-empty `-wal`
+    /// sidecar exists; returns the data-dir path. Mirrors the streaming DB's
+    /// journal mode so the checkpoint test exercises a real WAL fold.
+    fn seed_wal_db(data_dir: &std::path::Path) {
+        env::set_var("HELMOR_DATA_DIR", data_dir);
+        let path = crate::data_dir::db_path().unwrap();
+        let conn = rusqlite::Connection::open(&path).unwrap();
+        conn.pragma_update(None, "journal_mode", "WAL").unwrap();
+        conn.execute_batch("CREATE TABLE t (v INTEGER); INSERT INTO t VALUES (1);")
+            .unwrap();
+        // Leave the connection open so the write lands in `-wal` (a TRUNCATE
+        // checkpoint with no other readers will still fold + truncate it).
+        drop(conn);
+    }
+
+    #[test]
+    fn checkpoint_is_noop_when_env_gate_off() {
+        let dir = tempfile::tempdir().unwrap();
+        let _guard = TEST_ENV_LOCK.lock().unwrap();
+        env::remove_var(AUTOPUSH_ENV);
+        seed_wal_db(dir.path());
+
+        // Gate off → returns immediately, never opens a connection. The point
+        // is that this is a hard no-op on the desktop; assert it doesn't panic
+        // and the DB file is otherwise untouched.
+        maybe_checkpoint_db_after_turn();
+
+        let wal = dir.path().join("helmor.db-wal");
+        // The seeding connection was dropped, so SQLite may have auto-folded the
+        // WAL already; the only invariant we assert here is that our function
+        // performed no work — proven by it returning without error/panic.
+        let _ = wal;
+        env::remove_var("HELMOR_DATA_DIR");
+    }
+
+    #[test]
+    fn checkpoint_runs_when_env_gate_on() {
+        let dir = tempfile::tempdir().unwrap();
+        let _guard = TEST_ENV_LOCK.lock().unwrap();
+        env::set_var(AUTOPUSH_ENV, "1");
+        seed_wal_db(dir.path());
+
+        // Gate on → opens helmor.db and runs PRAGMA wal_checkpoint(TRUNCATE).
+        // Must complete without error and leave the DB readable.
+        maybe_checkpoint_db_after_turn();
+
+        let path = crate::data_dir::db_path().unwrap();
+        let conn = rusqlite::Connection::open(&path).unwrap();
+        let v: i64 = conn.query_row("SELECT v FROM t", [], |r| r.get(0)).unwrap();
+        assert_eq!(v, 1, "data survives the checkpoint");
+        // TRUNCATE checkpoint zeroes the WAL sidecar (or removes it). Either way
+        // it must not be a large pending log.
+        let wal = path.with_extension("db-wal");
+        if wal.exists() {
+            let len = std::fs::metadata(&wal).unwrap().len();
+            assert_eq!(len, 0, "WAL truncated to zero after checkpoint");
+        }
+
+        env::remove_var(AUTOPUSH_ENV);
+        env::remove_var("HELMOR_DATA_DIR");
+    }
+}

src-tauri/src/agents/streaming/mod.rs

@@ -764,6 +764,12 @@ pub(super) fn stream_via_sidecar(
                                         cloud_autopush::maybe_autopush_after_turn(
                                             &turn_session.ctx.working_directory,
                                         );
+                                        // Cloud serve mode only (env-gated):
+                                        // fold the WAL into helmor.db NOW
+                                        // (synchronously, before `done`) so the
+                                        // Worker's post-stream backup snapshots
+                                        // a consistent, self-contained DB.
+                                        cloud_autopush::maybe_checkpoint_db_after_turn();
                                     }
                                     Err(error) => {
                                         tracing::error!(rid = %rid, "Failed to finalize exchange: {error}");