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>
This commit is contained in:
2026-08-09 18:19:12 -07:00
co-authored by Claude Opus 5
parent cc5f691677
commit d42b741337
26 changed files with 5704 additions and 58 deletions
@@ -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();
});
});
});
+293
View File
@@ -0,0 +1,293 @@
import { useCallback, useEffect, useRef, useState } from "react";
import type {
ContainerStaleness,
MigrationOptions,
MigrationReport,
MigrationState,
Project,
} from "../lib/types";
import {
MIGRATION_PHASE_AWAITING_CONFIRMATION,
MIGRATION_PHASE_IN_PROGRESS,
MIGRATION_PHASE_INTERRUPTED,
} from "../lib/types";
import * as commands from "../lib/tauri-commands";
import { useAppState } from "../store/appState";
/**
* Unsettled phases from `MigrationState.phase` (hyphenated, unlike the
* outcome phases on `MigrationReport`). Compared as strings on purpose: the
* backend types this loosely so an unrecognised value from a future build
* cannot crash the UI, and neither can it here — an unknown phase simply
* surfaces nothing rather than throwing.
*/
const IN_PROGRESS = MIGRATION_PHASE_IN_PROGRESS;
const INTERRUPTED = MIGRATION_PHASE_INTERRUPTED;
const AWAITING = MIGRATION_PHASE_AWAITING_CONFIRMATION;
export interface ContainerMigration {
/** Null until the first probe returns, or when the container has never been created. */
staleness: ContainerStaleness | null;
probing: boolean;
/** True while a migration is running — whether we started it or found it. */
running: boolean;
/** True when the run in progress was recovered from disk, not started here. */
recovered: boolean;
/**
* A migration the app died in the middle of. It is not running and it has no
* report: the container is mid-swap until someone resumes or rolls it back.
*/
interrupted: MigrationState | null;
/** Re-enter an interrupted migration. The backend continues the same run. */
resume: () => Promise<void>;
/** The settled report, kept until the user keeps, rolls back or dismisses it. */
report: MigrationReport | null;
/** Progress lines from `container-progress`, oldest first. */
log: string[];
/** The most recent progress line, or null before the first one arrives. */
phaseMessage: string | null;
/** True while confirm/rollback is in flight. */
busy: boolean;
start: (options: MigrationOptions) => Promise<void>;
keep: () => Promise<void>;
rollback: () => Promise<void>;
/** Clear a report we cannot act on (failed / rolled back). Local only. */
dismiss: () => void;
refresh: () => Promise<void>;
}
/**
* Container base-image migration for one project.
*
* Three things have to survive a closed modal: the run itself, the progress
* log, and the report. A migration takes minutes, so the modal is a *view* onto
* this hook rather than the thing that owns the work — closing it must not
* cancel anything. The hook lives in `ProjectHome`, above both the modal and
* the Overview banner, so either surface can be showing at any point.
*
* A migration the app died in the middle of is picked up from
* `getMigrationState` on mount — as `interrupted`, which is offered for resume,
* or as `awaiting-confirmation`, whose report is put back on screen. Without
* that, a half-migrated container would look identical to a healthy one, which
* is the exact failure mode this whole feature exists to fix.
*/
export function useContainerMigration(project: Project): ContainerMigration {
const projectId = project.id;
const [staleness, setStaleness] = useState<ContainerStaleness | null>(null);
const [probing, setProbing] = useState(false);
const [running, setRunning] = useState(false);
const [recovered, setRecovered] = useState(false);
const [interrupted, setInterrupted] = useState<MigrationState | null>(null);
const [report, setReport] = useState<MigrationReport | null>(null);
const [log, setLog] = useState<string[]>([]);
const [busy, setBusy] = useState(false);
const pushToast = useAppState((s) => s.pushToast);
const progress = useAppState((s) => s.containerProgress[projectId]);
// Guards a late response from an earlier project overwriting a newer one.
const generation = useRef(0);
const refresh = useCallback(async () => {
const gen = ++generation.current;
if (!project.container_id) {
setStaleness(null);
return;
}
setProbing(true);
try {
const next = await commands.getContainerStaleness(projectId);
if (gen === generation.current) setStaleness(next);
} catch {
// A probe that cannot reach the container is "we do not know", which is
// an absent banner rather than an error one — the same call is retried
// whenever the container's status changes.
if (gen === generation.current) setStaleness(null);
} finally {
if (gen === generation.current) setProbing(false);
}
}, [projectId, project.container_id]);
// Probe staleness when the container settles into a new state. The probe runs
// two filesystem walks and is explicitly not for polling, so it is skipped
// mid-transition and mid-run — a reading taken while the container is being
// swapped describes neither the old system layer nor the new one.
const settled = project.status !== "starting" && project.status !== "stopping";
useEffect(() => {
if (running || !settled) return;
void refresh();
}, [refresh, settled, running]);
// Crash recovery: adopt whatever the backend still has on record.
useEffect(() => {
let cancelled = false;
commands
.getMigrationState(projectId)
.then((state) => {
if (cancelled || !state) return;
if (state.phase === IN_PROGRESS) {
// Something is still driving it; watch rather than restart.
setRunning(true);
setRecovered(true);
} else if (state.phase === INTERRUPTED) {
// Nothing is driving it. The container is mid-swap and will stay that
// way until someone resumes — so this must be visible, not silent.
setInterrupted(state);
} else if (state.phase === AWAITING && state.report) {
setReport(state.report);
}
})
.catch(() => {
/* No recorded state is the normal case. */
});
return () => {
cancelled = true;
};
}, [projectId]);
// A recovered run has no promise to await, so poll it to completion.
useEffect(() => {
if (!running || !recovered) return;
let cancelled = false;
const timer = setInterval(() => {
commands
.getMigrationState(projectId)
.then((state: MigrationState | null) => {
if (cancelled || state?.phase === IN_PROGRESS) return;
setRunning(false);
setRecovered(false);
// A cleared record means it was confirmed or rolled back elsewhere.
if (!state) {
void refresh();
return;
}
if (state.phase === INTERRUPTED) {
setInterrupted(state);
return;
}
if (state.report) setReport(state.report);
void refresh();
})
.catch(() => {
/* Keep polling; a transient IPC failure is not an outcome. */
});
}, 2500);
return () => {
cancelled = true;
clearInterval(timer);
};
}, [running, recovered, projectId, refresh]);
// Accumulate the shared progress line into a scrollback the modal can show.
// The store collapses repeats, so identical consecutive apt lines appear once.
useEffect(() => {
if (!running || !progress) return;
setLog((prev) =>
prev[prev.length - 1] === progress ? prev : [...prev, progress],
);
}, [progress, running]);
const start = useCallback(
async (options: MigrationOptions) => {
setLog([]);
setReport(null);
setRecovered(false);
setInterrupted(null);
setRunning(true);
try {
const result = await commands.migrateProjectToBase(projectId, options);
setReport(result);
} catch (e) {
// A rejected call means the backend never produced a report. Synthesise
// the failed shape so the report surface — not a toast that scrolls
// away — is still what tells the user.
setReport({
phase: "failed",
packages_requested: [],
packages_installed: [],
packages_failed: [],
paths_copied: [],
features_restored: [],
rollback_available: false,
message: String(e),
});
} finally {
setRunning(false);
useAppState.getState().setContainerProgress(projectId, null);
void refresh();
}
},
[projectId, refresh],
);
/**
* Re-enter an interrupted migration. The backend continues that run rather
* than starting a new one, and the recorded options are replayed as-is — the
* deltas cannot be recomputed once the container has already been swapped.
*/
const resume = useCallback(async () => {
const pending = interrupted;
if (!pending) return;
await start(pending.options);
}, [interrupted, start]);
const keep = useCallback(async () => {
setBusy(true);
try {
await commands.confirmMigration(projectId);
setReport(null);
await refresh();
} catch (e) {
pushToast({
kind: "error",
message: `Could not discard the rollback image for “${project.name}`,
detail: String(e),
});
} finally {
setBusy(false);
}
}, [projectId, project.name, refresh, pushToast]);
const rollback = useCallback(async () => {
setBusy(true);
try {
await commands.rollbackMigration(projectId);
setReport(null);
setInterrupted(null);
pushToast({
kind: "success",
message: `${project.name}” is back on its previous system layer.`,
detail:
"Volumes were not touched, so anything written to your home directory or workspace during the update is still there.",
});
await refresh();
} catch (e) {
pushToast({
kind: "error",
message: `Rollback failed for “${project.name}`,
detail: String(e),
});
} finally {
setBusy(false);
}
}, [projectId, project.name, refresh, pushToast]);
const dismiss = useCallback(() => setReport(null), []);
return {
staleness,
probing,
running,
recovered,
interrupted,
report,
log,
phaseMessage: log.length > 0 ? log[log.length - 1] : null,
busy,
start,
resume,
keep,
rollback,
dismiss,
refresh,
};
}