fix: finalize durable Pi lifecycle

backend/src/settings/settings-cli.ts

@@ -1,7 +1,15 @@
 /* Core-side, non-interactive installation-default writer used only through compose exec.
  * It accepts no credentials and writes the same SETTINGS_FILE consumed by session creation. */
+import { readFileSync } from "node:fs";
 import { loadConfig } from "../config.js";
-import { loadSettings, saveSettings, type Settings } from "./settings-store.js";
+import {
+  captureSettingsSnapshot,
+  loadSettings,
+  restoreSettingsSnapshot,
+  saveSettings,
+  type Settings,
+  type SettingsSnapshot,
+} from "./settings-store.js";
 
 const choice = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/;
 
@@ -15,15 +23,25 @@ function value(args: string[], flag: string): string {
 
 try {
   const args = process.argv.slice(2);
-  if (args.length !== 6) throw new Error("only provider, model, and thinking may be configured");
-  const provider = value(args, "--provider");
-  const model = value(args, "--model");
-  const thinking = value(args, "--thinking");
-  if (!choice.test(provider) || !choice.test(model)) throw new Error("invalid provider or model");
-  if (!["low", "medium", "high"].includes(thinking)) throw new Error("invalid thinking level");
   const cfg = loadConfig(process.env);
-  const next: Settings = { ...loadSettings(cfg), provider, model, thinking };
-  saveSettings(cfg, next);
+  if (args.length === 1 && args[0] === "--snapshot") {
+    process.stdout.write(`${JSON.stringify(captureSettingsSnapshot(cfg))}\n`);
+  } else if (args.length === 1 && args[0] === "--restore") {
+    const parsed = JSON.parse(readFileSync(0, "utf8")) as Partial<SettingsSnapshot>;
+    if (Object.keys(parsed).some((key) => key !== "exists" && key !== "rawBase64")) {
+      throw new Error("invalid settings snapshot");
+    }
+    restoreSettingsSnapshot(cfg, parsed as SettingsSnapshot);
+  } else {
+    if (args.length !== 6) throw new Error("only provider, model, and thinking may be configured");
+    const provider = value(args, "--provider");
+    const model = value(args, "--model");
+    const thinking = value(args, "--thinking");
+    if (!choice.test(provider) || !choice.test(model)) throw new Error("invalid provider or model");
+    if (!["low", "medium", "high"].includes(thinking)) throw new Error("invalid thinking level");
+    const next: Settings = { ...loadSettings(cfg), provider, model, thinking };
+    saveSettings(cfg, next);
+  }
 } catch (error) {
   process.stderr.write(`settings-cli: ${error instanceof Error ? error.message : "invalid configuration"}\n`);
   process.exitCode = 2;

backend/src/settings/settings-store.ts

@@ -22,6 +22,11 @@ export interface SettingsDurability {
   syncDirectory(directory: string): void;
 }
 
+export interface SettingsSnapshot {
+  exists: boolean;
+  rawBase64: string;
+}
+
 /**
  * Settings files are installation defaults only. Personal workspace/model/thinking choices
  * belong to the browser and must never be written back here by request handlers.
@@ -39,6 +44,45 @@ export function loadSettings(cfg: AppConfig): Settings {
   }
 }
 
+/** Capture exact file existence and bytes so host-side configuration can compensate losslessly. */
+export function captureSettingsSnapshot(cfg: AppConfig): SettingsSnapshot {
+  try {
+    return { exists: true, rawBase64: readFileSync(cfg.settingsFile).toString("base64") };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { exists: false, rawBase64: "" };
+    }
+    throw error;
+  }
+}
+
+/** Restore a previously captured settings file exactly, including the clean absent state. */
+export function restoreSettingsSnapshot(
+  cfg: AppConfig,
+  snapshot: SettingsSnapshot,
+  durability: SettingsDurability = defaultDurability,
+): void {
+  if (typeof snapshot.exists !== "boolean" || typeof snapshot.rawBase64 !== "string") {
+    throw new Error("invalid settings snapshot");
+  }
+  const raw = Buffer.from(snapshot.rawBase64, "base64");
+  if (raw.toString("base64") !== snapshot.rawBase64 || (!snapshot.exists && raw.length !== 0)) {
+    throw new Error("invalid settings snapshot");
+  }
+  const directory = dirname(cfg.settingsFile);
+  mkdirSync(directory, { recursive: true });
+  if (snapshot.exists) {
+    replaceSettingsFile(cfg.settingsFile, raw);
+  } else {
+    try {
+      unlinkSync(cfg.settingsFile);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  }
+  durability.syncDirectory(directory);
+}
+
 /** Persist settings (pretty JSON). Creates the parent directory if needed. */
 export function saveSettings(
   cfg: AppConfig,