talon-agent 5.26.4 → 5.26.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.26.4",
+  "version": "5.26.5",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "The Falconry",
   "license": "Apache-2.0",

package/src/app.ts

@@ -212,6 +212,14 @@ const { config } = await withConfigGuard(() =>
   ),
 );
 
+// Before any backend resumes a session: carry Claude transcripts over a
+// Talon-home move (their project slug is the cwd), and in a container
+// alert when a backend's session store isn't on a persistent volume.
+await bootPhase("storage layout", async () => {
+  const { runStorageLayoutChecks } = await import("./core/layout/index.js");
+  await runStorageLayoutChecks(config as unknown as Record<string, unknown>);
+});
+
 // Record this process as the daemon. The gateway port is appended once
 // the gateway binds (it may fall back from the default on EADDRINUSE).
 const bootedAt = new Date().toISOString();

package/src/backend/agy/auth.ts

@@ -14,16 +14,16 @@
  * the host.
  */
 
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { readFileSync } from "node:fs";
+import { userHome } from "../../util/fs-path.js";
 
 /** Where the CLI caches its OAuth token. Env override for tests. */
 function agyTokenPath(override?: string): string {
   return (
     override ||
     process.env.TALON_AGY_TOKEN_FILE ||
-    join(homedir(), ".gemini", "antigravity-cli", "antigravity-oauth-token")
+    join(userHome(), ".gemini", "antigravity-cli", "antigravity-oauth-token")
   );
 }
 

package/src/backend/agy/mcp/config.ts

@@ -28,7 +28,6 @@
  * touch the real files.
  */
 
-import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { randomBytes } from "node:crypto";
 import {
@@ -47,6 +46,7 @@ import { frontendsForChat } from "../../runtime/frontends.js";
 import { logWarn } from "../../../util/log.js";
 import { gatewayAuthHeaders } from "../../../core/engine/gateway-auth.js";
 import { AGY_MCP_PREFIX } from "../constants.js";
+import { userHome } from "../../../util/fs-path.js";
 
 // ── Paths ───────────────────────────────────────────────────────────────────
 
@@ -55,7 +55,7 @@ function agyMcpConfigPath(override?: string): string {
   return (
     override ||
     process.env.TALON_AGY_MCP_CONFIG ||
-    join(homedir(), ".gemini", "config", "mcp_config.json")
+    join(userHome(), ".gemini", "config", "mcp_config.json")
   );
 }
 
@@ -64,7 +64,7 @@ function agyMcpSnapshotDir(override?: string): string {
   return (
     override ||
     process.env.TALON_AGY_MCP_SNAPSHOT_DIR ||
-    join(homedir(), ".gemini", "antigravity-cli", "mcp")
+    join(userHome(), ".gemini", "antigravity-cli", "mcp")
   );
 }
 

package/src/backend/claude-sdk/usage/plan-usage.ts

@@ -13,13 +13,13 @@
  */
 
 import { readFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { logWarn } from "../../../util/log.js";
 import type {
   PlanUsage,
   PlanWindow,
 } from "../../../core/agent-runtime/capabilities.js";
+import { userHome } from "../../../util/fs-path.js";
 
 // `cedar_ember=1` asks the endpoint to include banked limit resets (the
 // claude.ai "Reset for free" grants); `skip_spend=1` drops the spend block we
@@ -38,7 +38,7 @@ let inFlight: Promise<PlanUsage | undefined> | undefined;
 function credentialsPath(): string {
   const configDir = process.env.CLAUDE_CONFIG_DIR?.trim();
   return join(
-    configDir && configDir.length > 0 ? configDir : join(homedir(), ".claude"),
+    configDir && configDir.length > 0 ? configDir : join(userHome(), ".claude"),
     ".credentials.json",
   );
 }

package/src/backend/codex/discovery.ts

@@ -39,12 +39,12 @@
  */
 
 import { promises as fs } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { log, logDebug } from "../../util/log.js";
 import { getState } from "./state.js";
 import type { CodexAuthInfo } from "./auth.js";
 import { normalizeReasoningLevels } from "../../core/models/reasoning-levels.js";
+import { userHome } from "../../util/fs-path.js";
 
 /** Shape of one entry returned by OpenAI's `/v1/models`. Sparse — only `id` is reliably present. */
 interface OpenAiModelEntry {
@@ -99,7 +99,7 @@ export function getCodexCachePath(): string {
   const home = process.env.CODEX_HOME?.trim();
   return home && home.length > 0
     ? join(home, "models_cache.json")
-    : join(homedir(), ".codex", "models_cache.json");
+    : join(userHome(), ".codex", "models_cache.json");
 }
 
 /** Default soft timeout when callers await an in-flight discovery. */

package/src/backend/codex/plan-usage.ts

@@ -12,13 +12,13 @@
  */
 
 import { readFile, stat } from "node:fs/promises";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { logWarn } from "../../util/log.js";
 import type {
   PlanUsage,
   PlanWindow,
 } from "../../core/agent-runtime/capabilities.js";
+import { userHome } from "../../util/fs-path.js";
 
 const USAGE_ENDPOINT = "https://chatgpt.com/backend-api/wham/usage";
 const REQUEST_TIMEOUT_MS = 5_000;
@@ -37,7 +37,7 @@ function authPath(): string {
   const home = process.env.CODEX_HOME?.trim();
   return home && home.length > 0
     ? join(home, "auth.json")
-    : join(homedir(), ".codex", "auth.json");
+    : join(userHome(), ".codex", "auth.json");
 }
 
 interface CodexAuth {

package/src/backend/codex/token-usage.ts

@@ -29,8 +29,8 @@
  */
 
 import { readFile, readdir } from "node:fs/promises";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { userHome } from "../../util/fs-path.js";
 
 export interface CodexLastTokenUsage {
   /** Last API call's prompt size = current context fill in tokens. */
@@ -120,7 +120,7 @@ export interface CodexRolloutSnapshot {
  * Codex CLI resolves its data directory.
  */
 function codexHome(): string {
-  return process.env.CODEX_HOME ?? join(homedir(), ".codex");
+  return process.env.CODEX_HOME ?? join(userHome(), ".codex");
 }
 
 /**

package/src/core/auth/status.ts

@@ -13,9 +13,9 @@
  */
 
 import { readFile, stat } from "node:fs/promises";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { logWarn } from "../../util/log.js";
+import { userHome } from "../../util/fs-path.js";
 
 export type AuthProvider = "claude" | "codex";
 
@@ -44,14 +44,14 @@ export function claudeCredentialsPath(
 ): string {
   const configDir = env.CLAUDE_CONFIG_DIR?.trim();
   return join(
-    configDir ? configDir : join(homedir(), ".claude"),
+    configDir ? configDir : join(userHome(), ".claude"),
     ".credentials.json",
   );
 }
 
 export function codexAuthPath(env: NodeJS.ProcessEnv = process.env): string {
   const home = env.CODEX_HOME?.trim();
-  return join(home ? home : join(homedir(), ".codex"), "auth.json");
+  return join(home ? home : join(userHome(), ".codex"), "auth.json");
 }
 
 /** Providers the backends reported as dead since boot (cleared on login). */

package/src/core/backup/plan.ts

@@ -21,8 +21,8 @@
 
 import { lstat, readdir, readlink } from "node:fs/promises";
 import { isAbsolute, join, resolve, sep } from "node:path";
-import { homedir } from "node:os";
 import type { BackupSettings } from "./types.js";
+import { userHome } from "../../util/fs-path.js";
 
 /**
  * The workspace is mostly machine-generated bulk (uploads, media, build
@@ -219,9 +219,9 @@ export function workspaceRoots(patterns: readonly string[]): string[] {
 /** Expand a leading `~` and resolve against the home directory. */
 export function expandUserPath(path: string): string {
   const trimmed = path.trim();
-  if (trimmed === "~") return homedir();
-  if (trimmed.startsWith("~/")) return resolve(homedir(), trimmed.slice(2));
-  return isAbsolute(trimmed) ? resolve(trimmed) : resolve(homedir(), trimmed);
+  if (trimmed === "~") return userHome();
+  if (trimmed.startsWith("~/")) return resolve(userHome(), trimmed.slice(2));
+  return isAbsolute(trimmed) ? resolve(trimmed) : resolve(userHome(), trimmed);
 }
 
 /** One member the builder will hand to the tar writer. */

package/src/core/backup/restore.ts

@@ -36,7 +36,6 @@ import {
   unlink,
   copyFile,
 } from "node:fs/promises";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { dirs } from "../../util/paths.js";
@@ -73,6 +72,7 @@ import {
 } from "./store.js";
 import type { BackupTarget } from "./targets.js";
 import type { BackupSettings, Manifest, SnapshotPart } from "./types.js";
+import { userHome } from "../../util/fs-path.js";
 
 /** A staged request older than this is stale and ignored. */
 export const RESTORE_PENDING_MAX_AGE_MS = 10 * 60_000;
@@ -571,7 +571,7 @@ export async function restoreSnapshot(
   const realHome = options.home === undefined;
   const cloneTarget: CloneTarget = {
     home,
-    userHome: options.userHome ?? homedir(),
+    userHome: options.userHome ?? userHome(),
     env: options.env ?? (realHome ? process.env : {}),
   };
   const missing = await missingParts(manifest, home);
@@ -597,7 +597,7 @@ export async function restoreSnapshot(
       pinned: true,
       settings: options.settings,
       home,
-      userHome: options.userHome ?? (realHome ? homedir() : null),
+      userHome: options.userHome ?? (realHome ? userHome() : null),
       env: cloneTarget.env,
     });
     checkpointId = checkpoint.id;

package/src/core/backup/snapshot.ts

@@ -29,7 +29,7 @@ import {
   stat,
   writeFile,
 } from "node:fs/promises";
-import { homedir, hostname } from "node:os";
+import { hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { dirs } from "../../util/paths.js";
@@ -89,6 +89,7 @@ import type {
   SnapshotKind,
   SnapshotPart,
 } from "./types.js";
+import { userHome } from "../../util/fs-path.js";
 
 /** The part that holds WhatsApp auth and the userbot session. */
 const LOGINS_PART = "logins.tar.zst";
@@ -467,7 +468,7 @@ async function sourceContext(
       options.userHome !== undefined
         ? options.userHome
         : realHome
-          ? homedir()
+          ? userHome()
           : null,
     env: options.env ?? (realHome ? process.env : {}),
     config: await readConfigJson(home),

package/src/core/backup/sources/sessions.ts

@@ -179,6 +179,35 @@ async function storeRoots(
   return roots;
 }
 
+/**
+ * The directory each configured backend keeps its sessions (and sign-in)
+ * under, whether or not it exists yet. Claude is always listed: it is the
+ * default backend. The container storage check uses this to tell which
+ * of them would vanish with the container.
+ */
+export function backendStoreDirs(
+  userHome: string,
+  env: SourceContext["env"],
+  config: Record<string, unknown>,
+): { backend: string; path: string }[] {
+  const configDir = env.CLAUDE_CONFIG_DIR?.trim();
+  const out = [
+    { backend: "claude", path: configDir || join(userHome, ".claude") },
+  ];
+  const backends = enabledBackends(config);
+  for (const spec of STORES) {
+    if (!backends.has(spec.backend)) continue;
+    const dir = spec.dir(userHome, env);
+    // agy's store is one level inside ~/.gemini, which also holds its
+    // sign-in: check the whole directory.
+    out.push({
+      backend: spec.backend,
+      path: spec.backend === "agy" ? join(userHome, ".gemini") : dir,
+    });
+  }
+  return out;
+}
+
 /**
  * Every session root this machine has for the configured backends, in a
  * deterministic order. Nothing outside the Talon home is looked at when

package/src/core/engine/gateway-actions/native/params.ts

@@ -4,15 +4,15 @@
  * something the handlers can use.
  */
 
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { userHome } from "../../../../util/fs-path.js";
 
 // — path parameter resolution ----------------------------------------------
 
 /** Expand a leading `~` — local runs only; a device's home is not ours. */
 function expandHome(path: string): string {
-  if (path === "~") return homedir();
-  if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+  if (path === "~") return userHome();
+  if (path.startsWith("~/")) return join(userHome(), path.slice(2));
   return path;
 }
 

package/src/core/layout/claude-relink.ts

@@ -0,0 +1,131 @@
+/**
+ * Keep Claude transcripts resumable when the Talon home moves.
+ *
+ * Claude Code files a session's transcript under
+ * `~/.claude/projects/<slug>/`, where the slug IS the absolute cwd with
+ * every non-alphanumeric character turned into `-`. Talon's cwd is
+ * `<TALON_HOME>/workspace`, so moving the home — `/home/bun/.talon` to
+ * `/data/.talon` when a container switches to the single data root, or a
+ * new TALON_HOME on a host — changes the slug, and every stored session
+ * id then points at a transcript Claude can no longer find.
+ *
+ * This copies the old slug directories' files under the new slug. It
+ * never overwrites a file that already exists there and never moves or
+ * deletes the originals: the old directories stay as they were.
+ */
+
+import { constants } from "node:fs";
+import { copyFile, mkdir, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { relocateClaudeSlug } from "../backup/sources/relocate.js";
+import { claudeProjectSlug, sessionCwds } from "../backup/sources/sessions.js";
+
+export type RelinkResult = {
+  /** The old slug directory, left in place. */
+  from: string;
+  /** The directory the current home's sessions are looked up in. */
+  to: string;
+  /** Files copied (existing ones are skipped, never replaced). */
+  copied: number;
+};
+
+function matchesSlugOf(name: string, home: string): boolean {
+  return sessionCwds(home)
+    .map(claudeProjectSlug)
+    .some((slug) => name === slug || name.startsWith(`${slug}-`));
+}
+
+/** Copy `src` into `dst` recursively; existing files win. Returns files copied. */
+export async function mergeCopy(src: string, dst: string): Promise<number> {
+  await mkdir(dst, { recursive: true });
+  let copied = 0;
+  for (const entry of await readdir(src, { withFileTypes: true })) {
+    const from = join(src, entry.name);
+    const to = join(dst, entry.name);
+    if (entry.isDirectory()) {
+      copied += await mergeCopy(from, to);
+    } else if (entry.isFile()) {
+      try {
+        await copyFile(from, to, constants.COPYFILE_EXCL);
+        copied++;
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+      }
+    }
+  }
+  return copied;
+}
+
+async function listDir(dir: string): Promise<string[]> {
+  try {
+    return (await readdir(dir, { withFileTypes: true }))
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Old-slug directories to carry over: every project dir, in any of the
+ * `sources` projects directories, that belongs to one of `previousHomes`
+ * and not to `home`.
+ */
+async function findOldSlugDirs(input: {
+  home: string;
+  previousHomes: readonly string[];
+  sources: readonly string[];
+}): Promise<{ from: string; name: string; previousHome: string }[]> {
+  const found: { from: string; name: string; previousHome: string }[] = [];
+  for (const dir of new Set(input.sources)) {
+    const names = await listDir(dir);
+    for (const previousHome of new Set(input.previousHomes)) {
+      if (previousHome === input.home) continue;
+      for (const name of names) {
+        if (!matchesSlugOf(name, previousHome)) continue;
+        if (matchesSlugOf(name, input.home)) continue;
+        found.push({ from: join(dir, name), name, previousHome });
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Copy transcripts filed under a previous home's slug to the current
+ * home's slug. `projectsDir` is where the current Claude looks;
+ * `extraSources` are other projects directories to read from (an old
+ * `~/.claude` still mounted during a migration). Sources in `skip` were
+ * carried over on an earlier boot. A directory that fails to copy is
+ * reported through `onError` and left for the next boot.
+ */
+export async function relinkClaudeProjects(input: {
+  home: string;
+  projectsDir: string;
+  previousHomes: readonly string[];
+  extraSources?: readonly string[];
+  skip?: ReadonlySet<string>;
+  onError?: (from: string, err: unknown) => void;
+}): Promise<RelinkResult[]> {
+  const olds = await findOldSlugDirs({
+    home: input.home,
+    previousHomes: input.previousHomes,
+    sources: [input.projectsDir, ...(input.extraSources ?? [])],
+  });
+  const results: RelinkResult[] = [];
+  for (const { from, name, previousHome } of olds) {
+    if (input.skip?.has(from)) continue;
+    const to = join(
+      input.projectsDir,
+      relocateClaudeSlug(name, previousHome, input.home),
+    );
+    if (to === from) continue;
+    try {
+      results.push({ from, to, copied: await mergeCopy(from, to) });
+    } catch (err) {
+      input.onError?.(from, err);
+    }
+  }
+  return results;
+}

package/src/core/layout/index.ts

@@ -0,0 +1,170 @@
+/**
+ * Storage layout at boot: keep Claude transcripts reachable across a
+ * Talon-home move, and (in a container) warn when a backend's session
+ * store is not on a persistent volume. See docs/docker.md.
+ *
+ * Neither step throws: both are advisory, and a boot must never fail
+ * because a check could not read a directory.
+ */
+
+import { readFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { claudeProjectsDir } from "../backup/sources/sessions.js";
+import { raiseAlert } from "../frontend-runtime/alerts.js";
+import { dirs } from "../../util/paths.js";
+import { log, logWarn } from "../../util/log.js";
+import { relinkClaudeProjects, type RelinkResult } from "./claude-relink.js";
+import { readMountTable, type MountEntry } from "./mounts.js";
+import {
+  describeFindings,
+  findEphemeralStores,
+  inContainer,
+  type StorageFinding,
+} from "./persistence.js";
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+/**
+ * Talon homes the published image has used. In a container either may
+ * hold the transcripts of a deployment that moved to the other.
+ */
+const CONTAINER_HOMES = ["/home/bun/.talon", "/data/.talon"] as const;
+/** The pre-/data image's HOME, where an old `~/.claude` may still be mounted. */
+const LEGACY_USER_HOME = "/home/bun";
+
+/** What the last boot recorded: the home it ran in, dirs already copied. */
+type RelinkState = { home: string; merged: string[] };
+
+async function readState(file: string): Promise<RelinkState | null> {
+  try {
+    const raw = JSON.parse(await readFile(file, "utf8")) as unknown;
+    if (!raw || typeof raw !== "object") return null;
+    const { home, merged } = raw as Record<string, unknown>;
+    if (typeof home !== "string") return null;
+    return {
+      home,
+      merged: Array.isArray(merged)
+        ? merged.filter((m): m is string => typeof m === "string")
+        : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Carry Claude transcripts over from a previous Talon home's project slug.
+ * The previous home comes from the state file (which travels with a copied
+ * `.talon`, so it names the old path after a migration) and, in a
+ * container, from the image's known homes.
+ */
+export async function relinkAfterHomeMove(opts: {
+  home: string;
+  userHome: string;
+  env: Env;
+  container: boolean;
+  stateFile: string;
+}): Promise<RelinkResult[]> {
+  const state = await readState(opts.stateFile);
+  const previousHomes = [
+    ...(state ? [state.home] : []),
+    ...(opts.container ? CONTAINER_HOMES : []),
+  ].filter((h) => h !== opts.home);
+  const projectsDir = claudeProjectsDir(opts.userHome, opts.env);
+  const legacyProjects = join(LEGACY_USER_HOME, ".claude", "projects");
+  const results = await relinkClaudeProjects({
+    home: opts.home,
+    projectsDir,
+    previousHomes,
+    extraSources:
+      opts.container && legacyProjects !== projectsDir ? [legacyProjects] : [],
+    skip: new Set(state?.merged ?? []),
+    onError: (from, err) =>
+      logWarn(
+        "sessions",
+        `Could not copy Claude transcripts from ${from}: ${String(err)} (will retry next boot)`,
+      ),
+  });
+  for (const r of results) {
+    log(
+      "sessions",
+      `Talon home moved: copied ${r.copied} Claude transcript file(s) from ${r.from} to ${r.to} (the original is kept)`,
+    );
+  }
+  if (state?.home !== opts.home || results.length > 0) {
+    const merged = [...(state?.merged ?? []), ...results.map((r) => r.from)];
+    await mkdir(dirname(opts.stateFile), { recursive: true });
+    await writeFileAtomic(
+      opts.stateFile,
+      JSON.stringify({ home: opts.home, merged: [...new Set(merged)] }) + "\n",
+      { mode: 0o600 },
+    );
+  }
+  return results;
+}
+
+/**
+ * In a container, raise one admin alert listing every store that would
+ * not survive a recreate. Returns the findings (empty outside a container
+ * or when the check is switched off with TALON_STORAGE_CHECK=0).
+ */
+export function checkContainerStorage(opts: {
+  talonHome: string;
+  userHome: string;
+  env: Env;
+  config: Record<string, unknown>;
+  container: boolean;
+  mounts?: readonly MountEntry[];
+  raise?: typeof raiseAlert;
+}): StorageFinding[] {
+  if (!opts.container || opts.env.TALON_STORAGE_CHECK === "0") return [];
+  const findings = findEphemeralStores({
+    ...opts,
+    mounts: opts.mounts ?? readMountTable(),
+  });
+  if (findings.length === 0) return [];
+  // Losing only Claude's account file costs a re-onboarding; losing a
+  // session store costs every conversation.
+  const onlyAccountFile = findings.every((f) =>
+    f.path.endsWith(".claude.json"),
+  );
+  (opts.raise ?? raiseAlert)(
+    "storage.ephemeral",
+    describeFindings(findings, opts.env),
+    { severity: onlyAccountFile ? "warn" : "error" },
+  );
+  return findings;
+}
+
+/** Both steps, with this process's paths. Never throws. */
+export async function runStorageLayoutChecks(
+  config: Record<string, unknown>,
+): Promise<void> {
+  const env = process.env;
+  const container = inContainer(env);
+  const userHome = homedir();
+  try {
+    await relinkAfterHomeMove({
+      home: dirs.root,
+      userHome,
+      env,
+      container,
+      stateFile: join(dirs.data, "claude-relink.json"),
+    });
+  } catch (err) {
+    logWarn("sessions", `Claude transcript relink failed: ${String(err)}`);
+  }
+  try {
+    checkContainerStorage({
+      talonHome: dirs.root,
+      userHome,
+      env,
+      config,
+      container,
+    });
+  } catch (err) {
+    logWarn("bot", `Container storage check failed: ${String(err)}`);
+  }
+}

package/src/core/layout/mounts.ts

@@ -0,0 +1,129 @@
+/**
+ * Which filesystem a path lives on, read from /proc/self/mountinfo.
+ *
+ * Inside a container the root filesystem is the image's writable layer:
+ * whatever is written there is gone the moment the container is recreated
+ * (an image update, a NAS app redeploy). Only bind mounts and named
+ * volumes outlive it. This module answers "is this path on one of those?"
+ * without shelling out to `mountpoint` or `df`.
+ */
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+
+/** One line of /proc/self/mountinfo, the fields this module needs. */
+export type MountEntry = {
+  /** Where it is mounted, in this mount namespace. */
+  mountPoint: string;
+  /** The directory of the source filesystem that is mounted there. */
+  root: string;
+  fsType: string;
+  source: string;
+};
+
+/** Where a path's data lives, as far as surviving a container recreate goes. */
+export type Persistence =
+  | "persistent"
+  /** The container's own writable layer (or a tmpfs): lost on recreate. */
+  | "ephemeral"
+  /** An anonymous Docker volume: lost when the container is removed. */
+  | "anonymous";
+
+/** mountinfo escapes space, tab, newline and backslash as octal. */
+function unescape(field: string): string {
+  return field.replace(/\\([0-7]{3})/g, (_, oct: string) =>
+    String.fromCharCode(parseInt(oct, 8)),
+  );
+}
+
+/**
+ * Parse mountinfo text (proc(5)): `id parent maj:min root mountpoint opts
+ * [optional…] - fstype source superopts`. Malformed lines are skipped.
+ */
+export function parseMountInfo(text: string): MountEntry[] {
+  const out: MountEntry[] = [];
+  for (const line of text.split("\n")) {
+    const fields = line.trim().split(" ");
+    const dash = fields.indexOf("-");
+    if (fields.length < 6 || dash < 6 || dash + 2 >= fields.length) continue;
+    out.push({
+      root: unescape(fields[3]),
+      mountPoint: unescape(fields[4]),
+      fsType: fields[dash + 1],
+      source: unescape(fields[dash + 2]),
+    });
+  }
+  return out;
+}
+
+function covers(mountPoint: string, path: string): boolean {
+  if (mountPoint === "/") return true;
+  return path === mountPoint || path.startsWith(mountPoint + "/");
+}
+
+/**
+ * The mount a path is on: the longest covering mount point, and among
+ * equal ones the last listed (a later mount on the same point shadows the
+ * earlier one).
+ */
+export function mountFor(
+  path: string,
+  mounts: readonly MountEntry[],
+): MountEntry | undefined {
+  let best: MountEntry | undefined;
+  for (const m of mounts) {
+    if (!covers(m.mountPoint, path)) continue;
+    if (!best || m.mountPoint.length >= best.mountPoint.length) best = m;
+  }
+  return best;
+}
+
+/** Docker names anonymous volumes by a 64-hex id; named ones by name. */
+const ANONYMOUS_VOLUME = /\/volumes\/[0-9a-f]{64}\/_data(\/|$)/;
+
+/** Classify the mount a path is on. A missing mount counts as ephemeral. */
+export function classifyMount(mount: MountEntry | undefined): Persistence {
+  if (!mount || mount.mountPoint === "/" || mount.fsType === "tmpfs")
+    return "ephemeral";
+  if (ANONYMOUS_VOLUME.test(mount.root)) return "anonymous";
+  return "persistent";
+}
+
+/**
+ * The real path `path` resolves to once created: symlinks in the part that
+ * exists are followed (a `~/.claude` symlinked onto a volume is on that
+ * volume), the part that doesn't is appended as-is.
+ */
+function resolveExisting(path: string): string {
+  let head = path;
+  const tail: string[] = [];
+  while (!existsSync(head)) {
+    const parent = dirname(head);
+    if (parent === head) return path;
+    tail.unshift(relative(parent, head));
+    head = parent;
+  }
+  try {
+    return tail.length ? join(realpathSync(head), ...tail) : realpathSync(head);
+  } catch {
+    return path;
+  }
+}
+
+/** Read this process's mount table; empty when there is none (not Linux). */
+export function readMountTable(file = "/proc/self/mountinfo"): MountEntry[] {
+  try {
+    return parseMountInfo(readFileSync(file, "utf8"));
+  } catch {
+    return [];
+  }
+}
+
+/** Whether `path` would survive the container being recreated. */
+export function persistenceOf(
+  path: string,
+  mounts: readonly MountEntry[],
+): Persistence {
+  const real = resolveExisting(path).split(sep).join("/");
+  return classifyMount(mountFor(real, mounts));
+}

package/src/core/layout/persistence.ts

@@ -0,0 +1,132 @@
+/**
+ * Boot check: in a container, is every backend's session store on a
+ * volume that outlives the container?
+ *
+ * The image keeps everything under one data root (HOME=/data). A setup
+ * that maps only part of it — commonly just `~/.talon` in a NAS "custom
+ * app" — runs fine until the first image update, which silently takes
+ * every Claude/Codex/OpenCode transcript with it: the database still
+ * names those sessions, but nothing is left to resume. This check turns
+ * that into one admin alert at boot, naming each path and the fix.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { backendStoreDirs } from "../backup/sources/sessions.js";
+import { persistenceOf, type MountEntry, type Persistence } from "./mounts.js";
+
+export type StorageFinding = {
+  path: string;
+  /** What the operator loses with it. */
+  label: string;
+  persistence: Exclude<Persistence, "persistent">;
+};
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+/** Whether this process runs inside a container (Docker, Podman, the image). */
+export function inContainer(
+  env: Env,
+  exists: (path: string) => boolean = existsSync,
+): boolean {
+  return (
+    env.TALON_CONTAINER === "1" ||
+    exists("/.dockerenv") ||
+    exists("/run/.containerenv")
+  );
+}
+
+const LABELS: Record<string, string> = {
+  claude: "Claude Code transcripts and sign-in",
+  codex: "Codex sessions and sign-in",
+  opencode: "OpenCode sessions",
+  kilo: "Kilo sessions",
+  agy: "Antigravity sign-in and conversations",
+};
+
+/** Every path whose loss costs the operator something, with what it holds. */
+function storagePaths(input: {
+  talonHome: string;
+  userHome: string;
+  env: Env;
+  config: Record<string, unknown>;
+}): { path: string; label: string }[] {
+  const paths = [
+    {
+      path: input.talonHome,
+      label: "Talon home: config, chat history, memory, keys",
+    },
+  ];
+  for (const store of backendStoreDirs(
+    input.userHome,
+    input.env,
+    input.config,
+  )) {
+    paths.push({
+      path: store.path,
+      label: LABELS[store.backend] ?? `${store.backend} sessions`,
+    });
+  }
+  // Claude Code keeps its account/onboarding state next to ~/.claude,
+  // not inside it — unless CLAUDE_CONFIG_DIR moves both.
+  if (!input.env.CLAUDE_CONFIG_DIR?.trim()) {
+    paths.push({
+      path: join(input.userHome, ".claude.json"),
+      label: "Claude Code account state",
+    });
+  }
+  return paths;
+}
+
+/**
+ * The stores that would not survive a container recreate. Empty when the
+ * mount table is unknown: no table, no claim either way.
+ */
+export function findEphemeralStores(input: {
+  talonHome: string;
+  userHome: string;
+  env: Env;
+  config: Record<string, unknown>;
+  mounts: readonly MountEntry[];
+}): StorageFinding[] {
+  if (input.mounts.length === 0) return [];
+  const findings: StorageFinding[] = [];
+  const seen = new Set<string>();
+  for (const { path, label } of storagePaths(input)) {
+    if (seen.has(path)) continue;
+    seen.add(path);
+    const persistence = persistenceOf(path, input.mounts);
+    if (persistence !== "persistent")
+      findings.push({ path, label, persistence });
+  }
+  return findings;
+}
+
+const WHERE: Record<StorageFinding["persistence"], string> = {
+  ephemeral: "container filesystem, lost on every image update",
+  anonymous: "anonymous Docker volume, lost when the container is removed",
+};
+
+/** The admin alert text for a set of findings. */
+export function describeFindings(
+  findings: readonly StorageFinding[],
+  env: Env,
+): string {
+  const lines = findings.map(
+    (f) => `• ${f.path}: ${f.label} (${WHERE[f.persistence]})`,
+  );
+  const legacy =
+    env.TALON_LAYOUT === "legacy"
+      ? "\nThis container runs the old /home/bun layout (only some paths mounted)."
+      : "";
+  return (
+    "Some of Talon's state is not on a persistent volume and will be lost " +
+    "when this container is recreated:\n" +
+    lines.join("\n") +
+    legacy +
+    "\n\nFix: mount one volume at /data and run with HOME=/data (the image " +
+    "default), after copying the paths above into it. Nothing is moved for " +
+    'you. Steps: docs/docker.md, "Upgrading from the old layout".' +
+    "\nSilence this check with TALON_STORAGE_CHECK=0."
+  );
+}

package/src/plugins/mempalace/provision.ts

@@ -21,7 +21,6 @@
  */
 
 import { existsSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import type { DoctorCheck } from "../../core/doctor/index.js";
 import {
@@ -41,6 +40,7 @@ import {
   type ProvisionState,
 } from "../../core/plugin/provision.js";
 import { dirs, files } from "../../util/paths.js";
+import { userHome } from "../../util/fs-path.js";
 
 /**
  * The mempalace version Talon installs and reconciles the managed venv
@@ -89,7 +89,7 @@ export interface MempalaceSection {
  */
 export function resolveMempalacePaths(
   section: MempalaceSection | undefined,
-  home = homedir(),
+  home = userHome(),
 ): { pythonPath: string; palacePath: string } {
   return {
     pythonPath: resolve(
@@ -166,7 +166,7 @@ export async function provisionMempalace(
   const exec = deps.exec ?? runStep;
   const platform = deps.platform ?? process.platform;
   const now = deps.now ?? Date.now;
-  const home = deps.home ?? homedir();
+  const home = deps.home ?? userHome();
   const pathExists = deps.pathExists ?? existsSync;
   const target = section.version ?? MEMPALACE_PINNED_VERSION;
 
@@ -606,7 +606,7 @@ export async function inspectMempalace(
 ): Promise<DoctorCheck[]> {
   const exec = deps.exec ?? runStep;
   const pathExists = deps.pathExists ?? existsSync;
-  const home = deps.home ?? homedir();
+  const home = deps.home ?? userHome();
   const { pythonPath: python } = resolveMempalacePaths(section, home);
   const pin = section.version ?? MEMPALACE_PINNED_VERSION;
   const managed =

package/src/plugins/playwright/provision.ts

@@ -14,7 +14,6 @@
  */
 
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import type { DoctorCheck } from "../../core/doctor/index.js";
 import {
@@ -34,6 +33,7 @@ import {
   bundledPlaywrightVersion,
   couplingError,
 } from "./version-coupling.js";
+import { userHome } from "../../util/fs-path.js";
 
 /** Engines whose builds Playwright manages (vs system channels). */
 const MANAGED_ENGINES = new Set(["chromium", "firefox", "webkit"]);
@@ -173,7 +173,7 @@ function browserPresent(
 ): boolean {
   const root = browsersRoot(
     deps.platform ?? process.platform,
-    deps.home ?? homedir(),
+    deps.home ?? userHome(),
     deps.env ?? process.env,
   );
   const present = new Set((deps.listDir ?? safeListDir)(root));

package/src/util/fs-path.ts

@@ -10,9 +10,12 @@
  * gateway action bodies) into a `fs.*` or send-media API call, route
  * it through `expandFsPath` first so the leading `~/` is replaced
  * with the actual home directory.
+ *
+ * Also home to `userHome()` and the test-only home guard (below) that every
+ * home-derived default path goes through.
  */
 import { homedir } from "node:os";
-import { isAbsolute, resolve } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
 
 /**
  * Resolve a model-supplied path to an absolute on-disk path.
@@ -25,8 +28,105 @@ import { isAbsolute, resolve } from "node:path";
  */
 export function expandFsPath(input: string): string {
   if (!input) return input;
-  if (input === "~") return homedir();
-  if (input.startsWith("~/")) return resolve(homedir(), input.slice(2));
+  if (input === "~") return userHome();
+  if (input.startsWith("~/")) return resolve(userHome(), input.slice(2));
   if (isAbsolute(input)) return input;
   return resolve(process.cwd(), input);
 }
+
+/*
+ * ── Home guard ──────────────────────────────────────────────────────────
+ *
+ * Test-only tripwire: refuse to resolve a path into the real user home.
+ *
+ * The suite runs on developer machines and on the production host (the
+ * pre-flight lane), where `~/.talon` is a live install. Every vitest worker
+ * gets a throwaway HOME / TALON_HOME (src/__tests__/setup/home-isolation.ts),
+ * but a test that resets the env, mocks `os.homedir()` or spawns a child
+ * with a stripped environment can still land back on the real tree, and
+ * functions such as backup prune/restore default to `dirs.root`. So the
+ * resolvers themselves check: under vitest, a root that is the real home,
+ * an ancestor of it, or anything inside the real `~/.talon` is an error
+ * before a single byte is read or written.
+ *
+ * The real home comes from the password database (`os.userInfo()`), which
+ * on Node ignores HOME/USERPROFILE, and `os` is fetched with
+ * `process.getBuiltinModule` so a `vi.mock("node:os")` in the calling suite
+ * cannot hide it. The global setup also records the pre-override home in
+ * TALON_TEST_REAL_HOME, the fallback for hosts with no passwd entry.
+ *
+ * Outside vitest this is a no-op.
+ */
+
+/** Env var the vitest global setup fills with the home it replaced. */
+export const REAL_HOME_ENV = "TALON_TEST_REAL_HOME";
+
+function underVitest(): boolean {
+  return Boolean(process.env.VITEST);
+}
+
+/** The homes this process must never resolve into (deduplicated). */
+export function realHomes(): string[] {
+  const homes = new Set<string>();
+  // Bun's userInfo().homedir follows $HOME, so it would report the temp
+  // home as the real one; under Bun only the recorded value is trusted.
+  if (!process.versions.bun) {
+    try {
+      const os = process.getBuiltinModule("node:os");
+      const home = os.userInfo().homedir;
+      if (home) homes.add(resolve(home));
+    } catch {
+      // No passwd entry (arbitrary container uid) — fall back to the env.
+    }
+  }
+  const recorded = process.env[REAL_HOME_ENV];
+  if (recorded) homes.add(resolve(recorded));
+  return [...homes];
+}
+
+function norm(p: string): string {
+  return process.platform === "win32" ? p.toLowerCase() : p;
+}
+
+/** True when `child` is `parent` or lies inside it. */
+function within(child: string, parent: string): boolean {
+  const rel = relative(norm(parent), norm(child));
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/**
+ * True when `path` is a real home, an ancestor of one, or inside a real
+ * `~/.talon`. A path elsewhere under the real home is allowed: on Windows the
+ * temp dir itself lives in `%USERPROFILE%\AppData\Local\Temp`.
+ */
+export function touchesRealHome(path: string): boolean {
+  const target = resolve(path);
+  return realHomes().some(
+    (home) => within(home, target) || within(target, resolve(home, ".talon")),
+  );
+}
+
+/**
+ * Throw when running under vitest and `path` resolves into the real home.
+ * `what` names the resolver in the error.
+ */
+export function assertNotRealHome(path: string, what: string): void {
+  if (!underVitest()) return;
+  if (!touchesRealHome(path)) return;
+  throw new Error(
+    `[home-guard] ${what} resolved to ${resolve(path)}, which is the real ` +
+      `user home or its ~/.talon. Tests must run against the per-worker ` +
+      `temp home (src/__tests__/setup/home-isolation.ts); set TALON_HOME / ` +
+      `HOME to a temp dir instead.`,
+  );
+}
+
+/**
+ * `os.homedir()`, guarded: under vitest it throws rather than hand back the
+ * real home. Use it wherever a default path is built from the user home.
+ */
+export function userHome(): string {
+  const home = homedir();
+  assertNotRealHome(home, "os.homedir()");
+  return home;
+}

package/src/util/paths.ts

@@ -32,16 +32,20 @@
  */
 
 import { resolve } from "node:path";
-import { homedir } from "node:os";
+import { assertNotRealHome, userHome } from "./fs-path.js";
 
 /**
  * Root of the Talon data directory: ~/.talon/, relocatable via the
  * TALON_HOME environment variable (containers, systemd units, tests).
  * Resolved once at import time — a mid-process override does nothing.
+ * Under vitest, resolving to the real ~/.talon throws (util/fs-path.ts):
+ * the check runs on every evaluation of this module, so a suite that
+ * re-imports it after changing the env is checked again.
  */
 const TALON_ROOT = resolve(
-  process.env.TALON_HOME || resolve(homedir(), ".talon"),
+  process.env.TALON_HOME || resolve(userHome(), ".talon"),
 );
+assertNotRealHome(TALON_ROOT, "dirs.root (TALON_HOME / ~/.talon)");
 
 // ── Directories ────────────────────────────────────────────────────────────