Migrate a project onto a new base image without losing its volumes

Projects were pinned to the image they were first created from. Both
create paths preferred triple-c-snapshot-<id>:latest whenever it
existed, and container_needs_recreation compared the container's live
image against the triple-c.image label — which create_container wrote
from the same image it created from. A tautology that could never fire.
The only escape was Reset, which calls remove_project_volumes and
destroys the login, skills and transcripts.

Measured consequences on this host: real projects are missing socat (so
the auth bridge cannot tunnel) and bubblewrap (so sandbox mode does not
work), plus Mission Control and triple-c-sso-refresh, and sit 61
packages behind the base including ca-certificates, openssl and curl.

Detection. create_container now writes triple-c.base-image-id (the image
ID, not RepoDigests, which local-built and custom images do not have)
and triple-c.create-image. container_needs_recreation takes the expected
create-image and compares against the latter, so the check means
something. base-image-id is deliberately NOT compared: a base bump would
otherwise silently recreate from the snapshot, consuming the "you should
migrate" signal without migrating. Staleness is surfaced, never acted on
automatically.

Migration keeps the volumes. /home/claude and ~/.claude are volumes and
the image's copy is seed-only — permanently masked after first mount —
so the login, ~/.claude.json, skills, transcripts, scheduler tasks, SSH
keys, cargo, uv, ruff and Claude Code itself re-attach untouched. Only
root-level state is rebuilt: apt packages are replayed against the new
base rather than copied, so no stale libc is dragged forward, and
/usr/local, /opt and the non-bind-mounted parts of /workspace are copied
verbatim with tar --skip-old-files so they can never clobber a newer
base binary.

docker diff is not used: on a snapshot-derived container it reports only
changes since the last commit. Raw image-vs-image diffing is filtered
through dpkg ownership because it otherwise lies — 8,677 raw path
differences on a real project reduced to 2 genuinely user-authored
files, both loose /workspace-root files.

Crash safety. snapshot:latest keeps pointing at the old image until the
final commit, so any crash before it self-heals on next start. Later
crashes are caught by reconcile_project_statuses. The rollback pin is a
docker tag: 0.057s and 0 bytes. Rollback restores the system layer only
— volumes are never touched — and the UI says so rather than implying a
time machine.

Fixes an infinite recreation loop shipped with the MCP removal. docker
commit propagates labels to the image, so a container created from a
snapshot inherited its non-empty triple-c.mcp-fingerprint and the
one-shot shim recreated it again on every start, forever. Lineage labels
are now always written explicitly.

Documents the second, separate bug this uncovered: Dockerfile changes
under /home/claude never reach an existing project, migration or not,
because the volume masks them. Anything that must stay upgradable
belongs in /usr/local/bin or /opt, or must be seeded by entrypoint.sh.

145 Rust tests, 227 frontend tests, both builds clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

app/src/hooks/useContainerMigration.test.tsx

@@ -0,0 +1,262 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { useContainerMigration } from "./useContainerMigration";
+import type {
+  ContainerStaleness,
+  MigrationReport,
+  MigrationState,
+  Project,
+} from "../lib/types";
+
+const getContainerStaleness = vi.fn();
+const getMigrationState = vi.fn();
+const migrateProjectToBase = vi.fn();
+const confirmMigration = vi.fn();
+const rollbackMigration = vi.fn();
+const pushToast = vi.fn();
+let progress: string | undefined;
+
+vi.mock("../lib/tauri-commands", () => ({
+  getContainerStaleness: (...a: unknown[]) => getContainerStaleness(...a),
+  getMigrationState: (...a: unknown[]) => getMigrationState(...a),
+  migrateProjectToBase: (...a: unknown[]) => migrateProjectToBase(...a),
+  confirmMigration: (...a: unknown[]) => confirmMigration(...a),
+  rollbackMigration: (...a: unknown[]) => rollbackMigration(...a),
+}));
+
+vi.mock("../store/appState", () => ({
+  useAppState: Object.assign(
+    (selector: (s: unknown) => unknown) =>
+      selector({ pushToast, containerProgress: { p1: progress } }),
+    {
+      getState: () => ({ setContainerProgress: () => {} }),
+    },
+  ),
+}));
+
+const STALE: ContainerStaleness = {
+  stale: true,
+  known: true,
+  base_image_id: "sha256:aaa",
+  current_base_image_id: "sha256:bbb",
+  snapshot_created_at: "2026-03-01T09:00:00Z",
+  missing_paths: ["/usr/bin/socat"],
+  missing_features: ["Auth bridge tunnel (socat)"],
+  apt_delta: ["socat"],
+  npm_global_delta: [],
+  verbatim_paths: [],
+  outdated_package_count: 61,
+  probe_error: null,
+};
+
+const FRESH: ContainerStaleness = {
+  ...STALE,
+  stale: false,
+  base_image_id: "sha256:bbb",
+  missing_paths: [],
+  missing_features: [],
+  apt_delta: [],
+  outdated_package_count: 0,
+};
+
+const CLEAN: MigrationReport = {
+  phase: "succeeded",
+  packages_requested: ["socat"],
+  packages_installed: ["socat"],
+  packages_failed: [],
+  paths_copied: [],
+  features_restored: ["Auth bridge tunnel (socat)"],
+  rollback_available: true,
+  message: "",
+};
+
+const OPTIONS = {
+  replay_packages: true,
+  copy_paths: false,
+  keep_rollback: true,
+};
+
+function state(overrides: Partial<MigrationState> = {}): MigrationState {
+  return {
+    phase: "in-progress",
+    from_image_id: "sha256:aaa",
+    to_base_id: "sha256:bbb",
+    started_at: "2026-08-09T10:00:00Z",
+    report: null,
+    rollback_image: "triple-c-snapshot-p1:pre-migration-1754733600",
+    staging_path: null,
+    options: OPTIONS,
+    plan: null,
+    ...overrides,
+  };
+}
+
+const project = { id: "p1", name: "api-server", container_id: "c1", status: "stopped" } as Project;
+
+describe("useContainerMigration", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    progress = undefined;
+    getContainerStaleness.mockResolvedValue(STALE);
+    getMigrationState.mockResolvedValue(null);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("probes staleness for a container that exists", async () => {
+    const { result } = renderHook(() => useContainerMigration(project));
+    await waitFor(() => expect(result.current.staleness).toEqual(STALE));
+    expect(getContainerStaleness).toHaveBeenCalledWith("p1");
+  });
+
+  it("does not probe a project whose container was never created", async () => {
+    renderHook(() =>
+      useContainerMigration({ ...project, container_id: null } as Project),
+    );
+    await waitFor(() => expect(getMigrationState).toHaveBeenCalled());
+    expect(getContainerStaleness).not.toHaveBeenCalled();
+  });
+
+  it("shows an absent banner rather than an error one when the probe fails", async () => {
+    getContainerStaleness.mockRejectedValue(new Error("no such container"));
+    const { result } = renderHook(() => useContainerMigration(project));
+    await waitFor(() => expect(result.current.probing).toBe(false));
+    expect(result.current.staleness).toBeNull();
+  });
+
+  it("passes the options through and keeps the report", async () => {
+    migrateProjectToBase.mockResolvedValue(CLEAN);
+    const { result } = renderHook(() => useContainerMigration(project));
+    await waitFor(() => expect(result.current.staleness).toEqual(STALE));
+
+    getContainerStaleness.mockResolvedValue(FRESH);
+    await act(async () => {
+      await result.current.start({
+        replay_packages: true,
+        copy_paths: false,
+        keep_rollback: true,
+      });
+    });
+
+    expect(migrateProjectToBase).toHaveBeenCalledWith("p1", {
+      replay_packages: true,
+      copy_paths: false,
+      keep_rollback: true,
+    });
+    expect(result.current.report).toEqual(CLEAN);
+    expect(result.current.running).toBe(false);
+  });
+
+  it("turns a rejected migrate call into a failed report, not a silent nothing", async () => {
+    migrateProjectToBase.mockRejectedValue(new Error("docker daemon went away"));
+    const { result } = renderHook(() => useContainerMigration(project));
+    await act(async () => {
+      await result.current.start({
+        replay_packages: true,
+        copy_paths: false,
+        keep_rollback: true,
+      });
+    });
+    expect(result.current.report?.phase).toBe("failed");
+    expect(result.current.report?.message).toMatch(/docker daemon went away/);
+    expect(result.current.report?.rollback_available).toBe(false);
+  });
+
+  it("clears the report and re-probes once the migration is kept", async () => {
+    migrateProjectToBase.mockResolvedValue(CLEAN);
+    confirmMigration.mockResolvedValue(undefined);
+    const { result } = renderHook(() => useContainerMigration(project));
+    await act(async () => {
+      await result.current.start({
+        replay_packages: true,
+        copy_paths: false,
+        keep_rollback: true,
+      });
+    });
+    getContainerStaleness.mockResolvedValue(FRESH);
+    await act(async () => {
+      await result.current.keep();
+    });
+    expect(confirmMigration).toHaveBeenCalledWith("p1");
+    expect(result.current.report).toBeNull();
+    await waitFor(() => expect(result.current.staleness).toEqual(FRESH));
+  });
+
+  it("says out loud that a rollback left the volumes alone", async () => {
+    rollbackMigration.mockResolvedValue(undefined);
+    const { result } = renderHook(() => useContainerMigration(project));
+    await act(async () => {
+      await result.current.rollback();
+    });
+    expect(rollbackMigration).toHaveBeenCalledWith("p1");
+    expect(pushToast).toHaveBeenCalledWith(
+      expect.objectContaining({
+        kind: "success",
+        detail: expect.stringMatching(/Volumes were not touched/i),
+      }),
+    );
+  });
+
+  describe("crash recovery", () => {
+    it("adopts a run that was still in progress, and polls it to a report", async () => {
+      getMigrationState.mockResolvedValue(state());
+
+      const { result } = renderHook(() => useContainerMigration(project));
+      await waitFor(() => expect(result.current.running).toBe(true));
+      expect(result.current.recovered).toBe(true);
+
+      getMigrationState.mockResolvedValue(
+        state({ phase: "awaiting-confirmation", report: CLEAN }),
+      );
+      await waitFor(() => expect(result.current.report).toEqual(CLEAN), {
+        timeout: 5000,
+      });
+      expect(result.current.running).toBe(false);
+    });
+
+    it("surfaces a finished migration that was never acknowledged", async () => {
+      getMigrationState.mockResolvedValue(
+        state({ phase: "awaiting-confirmation", report: CLEAN }),
+      );
+      const { result } = renderHook(() => useContainerMigration(project));
+      await waitFor(() => expect(result.current.report).toEqual(CLEAN));
+      expect(result.current.running).toBe(false);
+    });
+
+    it("surfaces an interrupted migration instead of leaving it invisible", async () => {
+      getMigrationState.mockResolvedValue(state({ phase: "interrupted" }));
+      const { result } = renderHook(() => useContainerMigration(project));
+      await waitFor(() => expect(result.current.interrupted).not.toBeNull());
+      // Nothing is driving it, so it is not "running" and has no report.
+      expect(result.current.running).toBe(false);
+      expect(result.current.report).toBeNull();
+    });
+
+    it("resumes an interrupted migration with the options it was given", async () => {
+      getMigrationState.mockResolvedValue(state({ phase: "interrupted" }));
+      migrateProjectToBase.mockResolvedValue(CLEAN);
+      const { result } = renderHook(() => useContainerMigration(project));
+      await waitFor(() => expect(result.current.interrupted).not.toBeNull());
+
+      await act(async () => {
+        await result.current.resume();
+      });
+      // The deltas cannot be recomputed after the swap, so the recorded plan's
+      // options are replayed verbatim rather than re-derived.
+      expect(migrateProjectToBase).toHaveBeenCalledWith("p1", OPTIONS);
+      expect(result.current.interrupted).toBeNull();
+      expect(result.current.report).toEqual(CLEAN);
+    });
+
+    it("ignores an unrecognised phase from a future build rather than crashing", async () => {
+      getMigrationState.mockResolvedValue(state({ phase: "quantum-tunnelling" }));
+      const { result } = renderHook(() => useContainerMigration(project));
+      await waitFor(() => expect(result.current.staleness).toEqual(STALE));
+      expect(result.current.running).toBe(false);
+      expect(result.current.interrupted).toBeNull();
+      expect(result.current.report).toBeNull();
+    });
+  });
+});