@yalehwang/cloudpit 2.0.0 → 3.0.0

package/server/modules/websocket/services/chat-control.service.ts

@@ -182,7 +182,18 @@ type SendResult =
     }
   | {
       ok: false;
-      code: 'SESSION_NOT_FOUND' | 'UNSUPPORTED_PROVIDER' | 'RUN_IN_PROGRESS' | 'FORBIDDEN';
+      code:
+        | 'SESSION_NOT_FOUND'
+        | 'UNSUPPORTED_PROVIDER'
+        | 'RUN_IN_PROGRESS'
+        | 'FORBIDDEN'
+        // A send whose model would move the session to another upstream
+        // provider (`SESSION_PROVIDER_MISMATCH`), or whose model is bound to a
+        // provider that no longer exists (`SESSION_PROVIDER_UNKNOWN`). Both are
+        // decided by `dispatchRun` before it reserves a run and are handed back
+        // here rather than relabelled RUN_IN_PROGRESS.
+        | 'SESSION_PROVIDER_MISMATCH'
+        | 'SESSION_PROVIDER_UNKNOWN';
       message: string;
     };
 
@@ -658,6 +669,11 @@ export function createChatControlService(deps: ChatControlDependencies) {
       resolveRunId = resolve;
     });
     let busyAccepted = false;
+    // The dispatch-level refusal (busy session, upstream-provider switch),
+    // remembered so the result can carry its real code: the race below only
+    // knows "the dispatch settled instead of registering a run". Held in an
+    // object because the only write happens inside the `onRefuse` callback.
+    const dispatchVerdict: { refusal: { code: string; message: string } | null } = { refusal: null };
 
     // What the delivery-shaped answer needs, read BEFORE the dispatch: run=turn
     // is the mode in which a send is a DELIVERY, and "would this session take a
@@ -703,7 +719,12 @@ export function createChatControlService(deps: ChatControlDependencies) {
       // A run in progress is `dispatchRun`'s own refusal and it is decided
       // before its first `await`, so the verdict can be handed back on this
       // tick. `ws` is null above, so this is the only channel that reports it.
-      input.onRefuse,
+      // Kept as well as forwarded, because the result below has to repeat the
+      // refusal's own code (a provider switch is not "busy").
+      (refusal) => {
+        dispatchVerdict.refusal = refusal;
+        input.onRefuse?.(refusal);
+      },
       // The run's recorded origin. Derived from `caller.via` and passed
       // explicitly because `ws`/connection are both null here: the
       // connection-derived default cannot tell a WebSocket send from an MCP or
@@ -724,6 +745,18 @@ export function createChatControlService(deps: ChatControlDependencies) {
     ]);
 
     if (!outcome.registered) {
+      // The refusal dispatchRun reported, when it is one this result's own
+      // vocabulary can state. Anything else (including no refusal at all) keeps
+      // the historical answer.
+      const refused = dispatchVerdict.refusal;
+      if (
+        refused !== null
+        && (refused.code === 'RUN_IN_PROGRESS'
+          || refused.code === 'SESSION_PROVIDER_MISMATCH'
+          || refused.code === 'SESSION_PROVIDER_UNKNOWN')
+      ) {
+        return { ok: false, code: refused.code, message: refused.message };
+      }
       return {
         ok: false,
         code: 'RUN_IN_PROGRESS',

package/server/modules/websocket/services/chat-websocket.service.ts

@@ -62,7 +62,7 @@ import type {
   ProviderRuntimeWriter,
   RealtimeClientConnection,
 } from '@/shared/types.js';
-import { parseIncomingJsonObject, residentRunIsTurn } from '@/shared/utils.js';
+import { AppError, parseIncomingJsonObject, residentRunIsTurn } from '@/shared/utils.js';
 
 /**
  * Trust boundary for client-supplied image attachments: chat.send options come
@@ -861,6 +861,30 @@ export async function dispatchRun(
 ): Promise<{ started: boolean; error: string | null }> {
   const provider = session.provider as LLMProvider;
 
+  // A session's upstream provider is part of what the provider started its
+  // thread with, and it cannot be moved to another one in place (Codex answers
+  // `modelProviderMismatch` on the turn; the thread is already bound). The
+  // switch is therefore refused HERE — before the run is reserved — because the
+  // recording write below (`setSessionModel`) refuses the same selection and
+  // runs after `startRun`: a throw there would leave a `running` run with no
+  // process behind it. Every send funnels through this function (`chat.send`
+  // and `chat.edit-send` alike), so this is the one admission gate. A session
+  // with no recorded binding — every session's first send — passes.
+  const requestedModel = (data.options as AnyRecord | undefined)?.model;
+  if (typeof requestedModel === 'string' && requestedModel.trim()) {
+    try {
+      providerModelsService.assertSessionProviderSwitch(provider, sessionId, requestedModel);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const code = error instanceof AppError ? error.code : 'SESSION_PROVIDER_MISMATCH';
+      if (ws) {
+        sendProtocolError(ws, code, message, sessionId);
+      }
+      onRefuse?.({ code, message });
+      return { started: false, error: message };
+    }
+  }
+
   const runIsTurn = residentRunIsTurn();
   // Whether a busy send from this provider would be taken by a process that is
   // already running. Read once, before the probe, because run=turn makes two

package/server/modules/websocket/tests/chat-background-task.test.ts

@@ -706,12 +706,22 @@ test('the per-run runtime places backgroundTasks on the live instance and does n
   const tempDirectory = await mkdtemp(path.join(os.tmpdir(), 'chat-background-task-per-run-'));
   const savedHome = process.env.HOME;
   const savedConfigDir = process.env.CLAUDE_CONFIG_DIR;
+  const savedDatabasePath = process.env.DATABASE_PATH;
   const savedFactory = claudeQueryFactory.current;
   const fixture = createPerRunFixture();
 
   try {
+    // The run's wind-down reads its session row through the notifications path,
+    // so this leg needs a migrated database of its own: the ambient one may
+    // predate the latest added column, and a run must not depend on that.
+    closeConnection();
+    process.env.DATABASE_PATH = path.join(tempDirectory, 'auth.db');
     process.env.HOME = tempDirectory;
     process.env.CLAUDE_CONFIG_DIR = tempDirectory;
+    await initializeDatabase();
+    // A real user row, so the run's own wind-down can read its notification
+    // preferences without an FK failure (the SQLite foreign key is on user_id).
+    const user = userDb.createUser('background-task-per-run', 'unused-hash');
     claudeQueryFactory.current = (() => fixture.factory()) as unknown as typeof claudeQueryFactory.current;
 
     const appSessionId = PER_RUN_SESSION_ID;
@@ -720,7 +730,7 @@ test('the per-run runtime places backgroundTasks on the live instance and does n
     void queryClaudeSDK(
       'hold',
       { sessionId: appSessionId },
-      createWriter(),
+      { send: () => undefined, setSessionId: () => undefined, userId: Number(user.id) },
       RUNTIME_CONTEXT,
     );
 
@@ -758,6 +768,12 @@ test('the per-run runtime places backgroundTasks on the live instance and does n
     if (getActiveClaudeSDKSessions().includes(PER_RUN_SESSION_ID)) {
       await abortClaudeSDKSession(PER_RUN_SESSION_ID);
     }
+    if (savedDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = savedDatabasePath;
+    }
+    closeConnection();
     await rm(tempDirectory, { recursive: true, force: true });
   }
 });

package/server/modules/websocket/tests/chat-stop-task.test.ts

@@ -668,12 +668,22 @@ test('the per-run runtime places stopTask on the live instance and does not end
   const tempDirectory = await mkdtemp(path.join(os.tmpdir(), 'chat-stop-task-per-run-'));
   const savedHome = process.env.HOME;
   const savedConfigDir = process.env.CLAUDE_CONFIG_DIR;
+  const savedDatabasePath = process.env.DATABASE_PATH;
   const savedFactory = claudeQueryFactory.current;
   const fixture = createPerRunFixture();
 
   try {
+    // The run's wind-down reads its session row through the notifications path,
+    // so this leg needs a migrated database of its own: the ambient one may
+    // predate the latest added column, and a run must not depend on that.
+    closeConnection();
+    process.env.DATABASE_PATH = path.join(tempDirectory, 'auth.db');
     process.env.HOME = tempDirectory;
     process.env.CLAUDE_CONFIG_DIR = tempDirectory;
+    await initializeDatabase();
+    // A real user row, so the run's own wind-down can read its notification
+    // preferences without an FK failure (the SQLite foreign key is on user_id).
+    const user = userDb.createUser('stop-task-per-run', 'unused-hash');
     claudeQueryFactory.current = (() => fixture.factory()) as unknown as typeof claudeQueryFactory.current;
 
     const appSessionId = PER_RUN_SESSION_ID;
@@ -682,7 +692,7 @@ test('the per-run runtime places stopTask on the live instance and does not end
     void queryClaudeSDK(
       'hold',
       { sessionId: appSessionId },
-      createWriter(),
+      { send: () => undefined, setSessionId: () => undefined, userId: Number(user.id) },
       {
         resolveProviderSessionId: () => null,
         resolveResumeModel: async () => undefined,
@@ -722,6 +732,12 @@ test('the per-run runtime places stopTask on the live instance and does not end
     if (getActiveClaudeSDKSessions().includes(PER_RUN_SESSION_ID)) {
       await abortClaudeSDKSession(PER_RUN_SESSION_ID);
     }
+    if (savedDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = savedDatabasePath;
+    }
+    closeConnection();
     await rm(tempDirectory, { recursive: true, force: true });
   }
 });

package/server/modules/worktrees/services/worktree-list.service.ts

@@ -89,7 +89,7 @@ async function readLastCommit(
 /**
  * Builds the full Worktrees panel payload for the repository containing
  * `projectPath`: every worktree with dirty count, ahead/behind vs the base
- * branch, last commit info, and the linked CloudCLI project (when registered).
+ * branch, last commit info, and the linked Cloudpit project (when registered).
  */
 export async function listWorktrees(
   input: ListWorktreesInput,

package/server/modules/worktrees/services/worktree-open.service.ts

@@ -26,7 +26,7 @@ function mapRowToProjectView(row: ProjectRepositoryRow): WorktreeProjectView {
 }
 
 /**
- * Ensures a CloudCLI project exists (and is active) for a worktree directory
+ * Ensures a Cloudpit project exists (and is active) for a worktree directory
  * and returns it, so the caller can switch the UI into that worktree.
  *
  * The path is only accepted when it is a registered worktree of the repository

package/server/modules/worktrees/services/worktree-remove.service.ts

@@ -13,7 +13,7 @@ import {
 
 /**
  * Removes a linked worktree (never the main one), optionally deletes its
- * branch, and archives the CloudCLI project registered for the directory so it
+ * branch, and archives the Cloudpit project registered for the directory so it
  * disappears from the sidebar while its chat history stays recoverable.
  */
 export async function removeWorktree(

package/server/shared/brand.ts

@@ -1,24 +1,31 @@
 /**
- * Brand-owned environment variables, read under the new Cloudpit names with a
- * fallback to the legacy CloudCLI names.
+ * Brand-owned environment variables, read under the Cloudpit spelling only.
  *
- * This module is deliberately unwired: GOAL-053 builds the reader so a later
- * task can point the CLI, database, settings and Electron paths at it without
- * changing any default in this change. Because no production module imports it
- * yet, the only consumer is `tests/cloudpit-brand-env.test.ts`.
+ * v3.0 RETIREMENT. Up to 2.x this reader also accepted the legacy `CLOUDCLI_<NAME>`
+ * spelling and emitted one deprecation warning per legacy key. The runtime fallback is
+ * gone: a process that exports only `CLOUDCLI_<NAME>` reads as absent, so the caller's
+ * shipped default applies. Setting the legacy name is not an error and produces no
+ * warning — it is simply not consulted.
+ *
+ * There is no `warn` dependency any more: every reading is either the canonical key's
+ * value or absent, so the reader has nothing to report. Callers that still pass a
+ * warning sink would be compiling against the retired API, hence the narrower shape.
+ *
+ * The production wiring points (Electron main/localServer/serverInstaller, the
+ * browser-use service and its MCP entry) all read through this module, and
+ * `electron/brandEnv.js` carries the same semantics for the Electron runtime.
  */
 
 /** Which spelling an environment read resolved through. */
-export type BrandEnvSource = 'new' | 'legacy' | 'absent';
+export type BrandEnvSource = 'new' | 'absent';
 
 /**
  * One resolved environment read.
  *
  * `value` is `undefined` only for `source: 'absent'`; an empty string is never
  * returned as a value, because `.env` files routinely carry `NAME=` and that
- * must not read as an enabled setting. `key` is the spelling that supplied the
- * value (`CLOUDPIT_…` or `CLOUDCLI_…`), or the canonical `CLOUDPIT_…` key when
- * nothing was set.
+ * must not read as an enabled setting. `key` is always the canonical
+ * `CLOUDPIT_…` spelling the operator should set.
  */
 export type BrandEnvReading = {
   value: string | undefined;
@@ -26,35 +33,25 @@ export type BrandEnvReading = {
   key: string;
 };
 
-/** Dependencies of {@link createBrandEnvReader}; both are injected so the reader is testable. */
+/** Dependencies of {@link createBrandEnvReader}; injectable so the reader is testable. */
 export type BrandEnvReaderDeps = {
   /** The environment to read (typically `process.env`). */
   env: Readonly<Record<string, string | undefined>>;
-  /** Called once per legacy key that is actually used. */
-  warn: (message: string) => void;
 };
 
-/** A reader bound to one environment and one warning sink. */
+/** A reader bound to one environment. */
 export type BrandEnvReader = {
-  /**
-   * Read `<NAME>`: `CLOUDPIT_<NAME>` wins, then `CLOUDCLI_<NAME>`, then absent.
-   *
-   * Using the legacy spelling emits one warning for that key on this reader;
-   * a second read of the same key stays silent. Separate readers keep separate
-   * warning state, so draining one does not silence a sibling.
-   */
+  /** Read `CLOUDPIT_<NAME>`; anything else (including `CLOUDCLI_<NAME>`) reads absent. */
   read: (name: string) => BrandEnvReading;
 };
 
 /**
  * Build a brand environment reader.
  *
- * The warned-key set lives in this factory's closure, not at module scope: the
- * state belongs to the reader instance, and two readers never share it.
+ * The reader holds no state: the canonical spelling either supplies a non-empty value
+ * or the reading is absent. A legacy `CLOUDCLI_<NAME>` is never consulted.
  */
-export function createBrandEnvReader({ env, warn }: BrandEnvReaderDeps): BrandEnvReader {
-  const warnedLegacyKeys = new Set<string>();
-
+export function createBrandEnvReader({ env }: BrandEnvReaderDeps): BrandEnvReader {
   return {
     read(name) {
       const canonicalKey = `CLOUDPIT_${name}`;
@@ -62,18 +59,7 @@ export function createBrandEnvReader({ env, warn }: BrandEnvReaderDeps): BrandEn
       if (canonical !== undefined && canonical !== '') {
         return { value: canonical, source: 'new', key: canonicalKey };
       }
-
-      const legacyKey = `CLOUDCLI_${name}`;
-      const legacy = env[legacyKey];
-      if (legacy === undefined || legacy === '') {
-        return { value: undefined, source: 'absent', key: canonicalKey };
-      }
-
-      if (!warnedLegacyKeys.has(legacyKey)) {
-        warnedLegacyKeys.add(legacyKey);
-        warn(`${legacyKey} is deprecated; set ${canonicalKey} instead.`);
-      }
-      return { value: legacy, source: 'legacy', key: legacyKey };
+      return { value: undefined, source: 'absent', key: canonicalKey };
     },
   };
 }

package/server/shared/data-root-migration.ts

@@ -1,5 +1,5 @@
 /**
- * Copies a legacy CloudCLI data root into an explicitly requested Cloudpit data
+ * Copies a legacy Cloudpit data root into an explicitly requested Cloudpit data
  * root.
  *
  * WHY THIS FINISHES BEFORE THE MARKER. A half-copied data root must never read
@@ -7,7 +7,8 @@
  * presence is the single fact that means "every earlier step succeeded". The
  * legacy root is only ever read — it is never renamed, unlinked, checkpointed
  * or written to, so a failed attempt (including an occupied SQLite database)
- * leaves it exactly as it was and the caller can fall back to it.
+ * leaves it exactly as it was. v3.0 does NOT fall back to it at runtime: the
+ * caller reports the thrown failure instead.
  *
  * ROLLBACK ON FAILURE. Every file and directory this module creates is recorded
  * before it is written and removed in reverse order when any step throws. The

package/server/shared/data-root.ts

@@ -1,19 +1,23 @@
 /**
  * Resolve where the server's data lives, and migrate a legacy layout when the
- * caller asks for the Cloudpit default (or names an explicit root).
+ * Cloudpit default (or an explicit root) is selected.
  *
- * TWO DEFAULT MODES. `defaultRoot: 'legacy'` (the default when the option is
- * omitted) keeps the historical behaviour: with neither `CLOUDPIT_HOME` nor
- * `CLOUDCLI_HOME` set, the active root stays `<home>/.cloudcli` and nothing is
- * copied or created. `defaultRoot: 'cloudpit'` is what the server bootstrap now
- * asks for: with no explicit environment root it selects `<home>/.cloudpit`,
- * copies the legacy layout into it once, and falls back to the legacy root when
- * the copy fails. An explicitly requested root always takes the migration path.
+ * v3.0 RETIREMENT. Up to 2.x the resolver had two default modes: `defaultRoot:
+ * 'legacy'` kept the historical `~/.cloudcli` layout, and any migration failure
+ * fell back to that layout so the server always kept running. Both runtime
+ * compatibilities are gone:
  *
- * The legacy root is only ever read: a failed attempt is rolled back by
- * `data-root-migration.ts` and the fallback keeps the server running on the old
- * layout. Callers that must not migrate keep passing `'legacy'` (AC-449's
- * criterion does exactly that).
+ *  - there is ONE default root, `<home>/.cloudpit`, selected when neither
+ *    `CLOUDPIT_HOME` nor an explicit caller root is set;
+ *  - the one-time migration still runs when a legacy `~/.cloudcli` layout exists
+ *    (a machine upgrading straight from 1.x is copied into `~/.cloudpit`), but a
+ *    failed migration is REPORTED, never silently swallowed by reverting to the
+ *    old root. `resolveDataRoots` returns `reason: 'migration-failed'` and a
+ *    `migrationError` message; the caller logs it and keeps the Cloudpit root.
+ *
+ * The legacy root is only ever READ: `data-root-migration.ts` rolls back every
+ * file it created, so a failed attempt leaves `~/.cloudcli` byte-identical and
+ * never deletes it. An explicitly requested root always takes the migration path.
  */
 import os from 'node:os';
 import path from 'node:path';
@@ -24,13 +28,8 @@ import {
   type DataRootFs,
 } from './data-root-migration.js';
 
-/** Which default root the caller wants when no explicit environment root is set. */
-export type DataRootMode = 'legacy' | 'cloudpit';
-
 /** Why {@link resolveDataRoots} selected the root it returned. */
 export type DataRootReason =
-  /** No explicit root was requested and the caller asked for the legacy default. */
-  | 'default-legacy'
   /** The Cloudpit default was selected and the legacy layout was copied into it. */
   | 'default-migrated'
   /** The Cloudpit default already carries a completion marker. */
@@ -47,8 +46,8 @@ export type DataRootReason =
   | 'explicit-user-root'
   /** The explicit root was requested but there was no legacy layout to copy. */
   | 'explicit-no-legacy'
-  /** A migration step failed; the legacy root is active and the new one is clean. */
-  | 'fallback-after-failure';
+  /** The migration threw; the Cloudpit root stays active and the error is reported. */
+  | 'migration-failed';
 
 /**
  * The resolved data locations. Every path is derived from `activeRoot` and the
@@ -67,12 +66,18 @@ export type ResolvedDataRoots = {
   replySuggestionsUsagePath: string;
   /** The settings file for the active mode. */
   settingsPath: string;
-  /** The legacy settings file, always named for a possible migration source. */
+  /** The legacy settings file, kept as the one-time migration source. */
   legacySettingsPath: string;
   /** Which of the documented cases this resolution took. */
   reason: DataRootReason;
-  /** True only when this call copied the legacy layout into the explicit root. */
+  /** True only when this call copied the legacy layout into the active root. */
   migrated: boolean;
+  /**
+   * The migration failure message when `reason` is `'migration-failed'`, else
+   * `null`. The caller must surface it (the boot logs it) — v3.0 does not fall
+   * back to the legacy root.
+   */
+  migrationError: string | null;
 };
 
 /** Dependencies of {@link resolveDataRoots}; all injectable so it is testable. */
@@ -81,11 +86,6 @@ export type ResolveDataRootsOptions = {
   env?: Readonly<Record<string, string | undefined>>;
   /** The home `~` expands against; defaults to the process home. */
   homeDir?: string;
-  /**
-   * Which default root to use when no explicit environment root is set.
-   * Defaults to `'legacy'`, so existing callers keep the historical layout.
-   */
-  defaultRoot?: DataRootMode;
   /** The filesystem seam; defaults to `node:fs`. */
   fs?: DataRootFs;
   /** The SQLite snapshot seam; defaults to a readonly `VACUUM INTO`. */
@@ -136,17 +136,29 @@ function expandTildePrefix(value: string, homeDir: string): string {
   return value;
 }
 
-/** The first non-empty explicit-root environment value, with `~` expanded. */
+/**
+ * Format a migration failure without importing `shared/utils.ts`: that module
+ * reads environment defaults during evaluation, before `load-env.ts` has loaded
+ * `.env`, which is exactly the ordering this bootstrap module must not disturb.
+ */
+function describeFailure(failure: unknown): string {
+  return failure instanceof Error ? failure.message : String(failure);
+}
+
+/**
+ * The explicit-root environment value, with `~` expanded.
+ *
+ * v3.0: only `CLOUDPIT_HOME` is consulted. The legacy `CLOUDCLI_HOME` spelling no
+ * longer selects a root, so a process exporting only that name migrates into the
+ * default `~/.cloudpit` instead of writing to the old location.
+ */
 function readExplicitRoot(
   env: Readonly<Record<string, string | undefined>>,
   homeDir: string,
 ): string | null {
-  // SPEC §4.1: the Cloudpit spelling wins, the legacy spelling is the fallback.
-  for (const variableName of ['CLOUDPIT_HOME', 'CLOUDCLI_HOME'] as const) {
-    const rawValue = env[variableName];
-    if (typeof rawValue === 'string' && rawValue.trim() !== '') {
-      return expandTildePrefix(rawValue.trim(), homeDir);
-    }
+  const rawValue = env.CLOUDPIT_HOME;
+  if (typeof rawValue === 'string' && rawValue.trim() !== '') {
+    return expandTildePrefix(rawValue.trim(), homeDir);
   }
   return null;
 }
@@ -158,6 +170,7 @@ function buildResolvedRoots(
   legacySettingsPath: string,
   reason: DataRootReason,
   migrated: boolean,
+  migrationError: string | null = null,
 ): ResolvedDataRoots {
   return {
     activeRoot,
@@ -169,6 +182,7 @@ function buildResolvedRoots(
     legacySettingsPath,
     reason,
     migrated,
+    migrationError,
   };
 }
 
@@ -201,18 +215,20 @@ function defaultReason(outcome: ReturnType<typeof migrateLegacyDataRoot>): DataR
 }
 
 /**
- * Resolve the active data root and, for an explicit root or the Cloudpit
- * default, migrate the legacy layout into it when it is safe to do so.
+ * Resolve the active data root and migrate the legacy layout into it when it is
+ * safe to do so.
  *
- * The settings location follows the mode, not the data root: the legacy default
- * and every fallback arm keep `<home>/.config/claudecodeui/server.settings.json`,
- * while explicit-root and Cloudpit-default arms use
- * `<home>/.config/cloudpit/server.settings.json`.
+ * The active root is `CLOUDPIT_HOME` when it names one, else `<home>/.cloudpit`.
+ * The settings location is always `<home>/.config/cloudpit/server.settings.json`
+ * (the legacy settings file is only a migration source).
+ *
+ * A failed migration does not change the active root: the resolver returns
+ * `reason: 'migration-failed'` with the thrown message in `migrationError`. The
+ * legacy root is left byte-identical by the migration module's rollback.
  */
 export function resolveDataRoots(options: ResolveDataRootsOptions = {}): ResolvedDataRoots {
   const env = options.env ?? process.env;
   const homeDir = options.homeDir ?? os.homedir();
-  const mode: DataRootMode = options.defaultRoot ?? 'legacy';
   const legacyRoot = path.join(homeDir, LEGACY_ROOT_DIRECTORY_NAME);
   const legacySettingsPath = path.join(
     homeDir,
@@ -228,43 +244,14 @@ export function resolveDataRoots(options: ResolveDataRootsOptions = {}): Resolve
   );
 
   const requestedRoot = readExplicitRoot(env, homeDir);
-  if (requestedRoot === null) {
-    if (mode === 'legacy') {
-      return buildResolvedRoots(legacyRoot, legacySettingsPath, legacySettingsPath, 'default-legacy', false);
-    }
-
-    // The Cloudpit default: migrate into `<home>/.cloudpit` exactly as an
-    // explicitly requested root would, with reasons that name this mode.
-    const cloudpitRoot = path.join(homeDir, CLOUDPIT_ROOT_DIRECTORY_NAME);
-    try {
-      const outcome = migrateLegacyDataRoot({
-        legacyRoot,
-        newRoot: cloudpitRoot,
-        legacySettingsPath,
-        newSettingsPath: explicitSettingsPath,
-        version: options.version ?? 'unknown',
-        fs: options.fs,
-        backupDatabase: options.backupDatabase,
-        now: options.now,
-      });
-      return buildResolvedRoots(
-        cloudpitRoot,
-        explicitSettingsPath,
-        legacySettingsPath,
-        defaultReason(outcome),
-        outcome.migrated,
-      );
-    } catch {
-      // The migration module rolled back everything it created; the legacy root
-      // was only ever read, so keeping it active is the safe outcome.
-      return buildResolvedRoots(legacyRoot, legacySettingsPath, legacySettingsPath, 'fallback-after-failure', false);
-    }
-  }
+  const explicit = requestedRoot !== null;
+  const activeRoot = requestedRoot ?? path.join(homeDir, CLOUDPIT_ROOT_DIRECTORY_NAME);
+  const reasonOf = explicit ? explicitReason : defaultReason;
 
   try {
     const outcome = migrateLegacyDataRoot({
       legacyRoot,
-      newRoot: requestedRoot,
+      newRoot: activeRoot,
       legacySettingsPath,
       newSettingsPath: explicitSettingsPath,
       version: options.version ?? 'unknown',
@@ -273,15 +260,22 @@ export function resolveDataRoots(options: ResolveDataRootsOptions = {}): Resolve
       now: options.now,
     });
     return buildResolvedRoots(
-      requestedRoot,
+      activeRoot,
       explicitSettingsPath,
       legacySettingsPath,
-      explicitReason(outcome),
+      reasonOf(outcome),
       outcome.migrated,
     );
-  } catch {
-    // The migration module has already rolled back everything it created; the
-    // legacy root was only ever read, so it is safe to keep using.
-    return buildResolvedRoots(legacyRoot, legacySettingsPath, legacySettingsPath, 'fallback-after-failure', false);
+  } catch (failure) {
+    // v3.0: no fallback to the legacy root. The migration module rolled back every
+    // file it created, so the Cloudpit root is clean; the caller sees the failure.
+    return buildResolvedRoots(
+      activeRoot,
+      explicitSettingsPath,
+      legacySettingsPath,
+      'migration-failed',
+      false,
+      describeFailure(failure),
+    );
   }
 }

package/server/shared/interfaces.ts

@@ -516,7 +516,7 @@ export interface IProviderFork {
 /**
  * Model catalog contract for one provider.
  *
- * Implementations supply CloudCLI's curated predefined models and can inspect
+ * Implementations supply Cloudpit's curated predefined models and can inspect
  * provider-native session state. The Providers service merges these immutable
  * source-controlled definitions with user-created SQLite rows at read time.
  */