@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/plugins/defaults/turn-context/unified-turn-context.ts

@@ -29,7 +29,6 @@ export interface UnifiedTurnContextOptions {
     name: string;
     /** Directory stem: the handle a human would recognize the app by. */
     slug: string;
-    sourceDir: string;
     /** Set when the app is bundled by an installed plugin rather than built here. */
     pluginName?: string;
   } | null;
@@ -127,7 +126,7 @@ export function buildUnifiedTurnContextBlock(
       ? ` It is bundled by the "${sanitizeInlineContextValue(app.pluginName)}" plugin, not built in the sandbox.`
       : "";
     lines.push(
-      `visible_app: "${sanitizeInlineContextValue(app.name)}" (app_id: "${sanitizeInlineContextValue(app.appId)}", slug: "${sanitizeInlineContextValue(app.slug)}", source: "${sanitizeInlineContextValue(app.sourceDir)}"). The user has this app open on screen; unqualified references to "the app" mean this one. The app tools take the app_id.${provenance}`,
+      `visible_app: "${sanitizeInlineContextValue(app.name)}" (app_id: "${sanitizeInlineContextValue(app.appId)}", slug: "${sanitizeInlineContextValue(app.slug)}"). The user has this app open on screen; unqualified references to "the app" mean this one.${provenance}`,
     );
   }
 

package/src/plugins/external-plugin-loader.ts

@@ -461,9 +461,14 @@ export async function loadExternalPlugin(
  * Exported so the mtime cache can discover plugin identity without going
  * through the full `buildExternalPlugin` path. The identity mirrors
  * {@link buildPluginFromDir}: the directory name, not `package.json` `name`.
+ *
+ * `quiet` suppresses the failure logs, for callers that poll on a timer and
+ * surface the failure through their own channel (e.g. the schedule
+ * reconciler's per-day deduped notification).
  */
 export async function parsePluginManifest(
   pluginDir: string,
+  opts: { quiet?: boolean } = {},
 ): Promise<
   Pick<PluginManifest, "name" | "version" | "credentialKeyPatterns"> | undefined
 > {
@@ -473,18 +478,22 @@ export async function parsePluginManifest(
     rawPkg = JSON.parse(await readFile(pkgPath, "utf8"));
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
-    log.error(
-      { err, pluginDir },
-      `package.json at ${pluginDir} could not be read or parsed: ${reason}`,
-    );
+    if (!opts.quiet) {
+      log.error(
+        { err, pluginDir },
+        `package.json at ${pluginDir} could not be read or parsed: ${reason}`,
+      );
+    }
     return undefined;
   }
   const parsed = PluginPackageJsonSchema.safeParse(rawPkg);
   if (!parsed.success) {
-    log.error(
-      { err: parsed.error, pluginDir },
-      `package.json at ${pluginDir} failed schema validation: ${parsed.error.message}`,
-    );
+    if (!opts.quiet) {
+      log.error(
+        { err: parsed.error, pluginDir },
+        `package.json at ${pluginDir} failed schema validation: ${parsed.error.message}`,
+      );
+    }
     return undefined;
   }
   const pkg: PluginPackageJson = parsed.data;

package/src/plugins/installed-plugin-dirs.ts

@@ -0,0 +1,101 @@
+/**
+ * Enumerate installed plugin directories under the workspace plugins dir.
+ *
+ * An installed plugin is a non-hidden directory carrying a `package.json`,
+ * whose realpath stays under the realpath of the plugins directory. This walk
+ * is shared by the plugin source-version collector
+ * (`./collect-source-versions.ts`) and the schedule reconciler
+ * (`../schedule/plugin-schedule-reconciler.ts`) so both agree on what counts
+ * as an installed plugin. Disabled-state and manifest validation are caller
+ * concerns: the source collector fingerprints disabled plugins too, while the
+ * reconciler skips them and additionally gates on `parsePluginManifest`.
+ *
+ * The containment half of that definition is exported on its own
+ * ({@link isInsidePluginRoot}) for the plugin loader, which applies the same
+ * boundary at boot discovery and before it imports a plugin directory, and for
+ * the schedule fire-time probe, which applies it before answering that a
+ * declaration is available to run.
+ */
+
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { join, sep } from "node:path";
+
+import { getWorkspacePluginsDir } from "../util/platform.js";
+
+export interface InstalledPluginDir {
+  /** Directory basename: the plugin's install identity. */
+  readonly name: string;
+  /** Absolute path to the plugin directory. */
+  readonly dir: string;
+}
+
+/**
+ * True when `dir` resolves to a location strictly inside `root`, where `root`
+ * is the tree the caller requires `dir` to stay in: an allowed plugin root
+ * (the workspace plugins directory, or the standalone workspace hooks
+ * directory) for a plugin directory, or a plugin directory for something
+ * installed under it.
+ *
+ * Both sides are resolved before the comparison. Resolving the candidate is
+ * what judges a symlinked entry by where it points rather than by where it
+ * sits; resolving the root is what keeps a root that itself sits behind a
+ * symlinked path component (macOS `/tmp` to `/private/tmp`, a workspace under
+ * a linked home) matching its own children. A resolved candidate compared
+ * against an unresolved root reports every entry as outside.
+ *
+ * This is the one containment boundary the plugin loader applies: enumeration
+ * here, boot discovery, and the pre-import check before a plugin directory is
+ * dynamic-imported (`scanPlugins` and `isAllowedPluginDir` in
+ * `./mtime-cache.ts`) all go through it, so a root the loader refuses to
+ * activate is never reported as installed either. A link pointing at the root
+ * itself is outside the boundary: it aliases the root, not a plugin. The
+ * schedule fire-time probe
+ * (`../schedule/plugin-schedule-declarations.ts`) applies the same boundary,
+ * so such a root cannot be run by a declared schedule either.
+ */
+export function isInsidePluginRoot(dir: string, root: string): boolean {
+  try {
+    return realpathSync(dir).startsWith(realpathSync(root) + sep);
+  } catch {
+    // Unresolvable (dangling link, races with an uninstall, unreadable): not
+    // provably contained, so it is not inside.
+    return false;
+  }
+}
+
+/**
+ * List every installed plugin directory, sorted by the underlying readdir
+ * order. A missing plugins directory yields `[]`.
+ */
+export function listInstalledPluginDirs(): InstalledPluginDir[] {
+  const pluginsDir = getWorkspacePluginsDir();
+  let entries: string[] = [];
+  try {
+    entries = readdirSync(pluginsDir);
+  } catch {
+    // No plugins directory yet, so nothing installed.
+    return [];
+  }
+  const out: InstalledPluginDir[] = [];
+  for (const entry of entries) {
+    if (entry.startsWith(".")) {
+      continue;
+    }
+    const dir = join(pluginsDir, entry);
+    try {
+      if (!statSync(dir).isDirectory()) {
+        continue;
+      }
+    } catch {
+      continue;
+    }
+    if (!isInsidePluginRoot(dir, pluginsDir)) {
+      continue;
+    }
+    if (!existsSync(join(dir, "package.json"))) {
+      continue;
+    }
+    out.push({ name: entry, dir });
+  }
+  return out;
+}

package/src/plugins/mtime-cache.ts

@@ -31,13 +31,7 @@
  * each hook through the hook loader on demand.
  */
 
-import {
-  existsSync,
-  readdirSync,
-  readFileSync,
-  realpathSync,
-  statSync,
-} from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 import type { Logger } from "pino";
@@ -72,6 +66,7 @@ import {
   listSurfaceDir,
   parsePluginManifest,
 } from "./external-plugin-loader.js";
+import { isInsidePluginRoot } from "./installed-plugin-dirs.js";
 import { snapshotPluginSource } from "./source-fingerprint.js";
 import type { PluginSourceVersion } from "./source-versions.js";
 import {
@@ -293,6 +288,18 @@ export async function reconcilePluginSourcesNow(): Promise<void> {
     } catch (err) {
       log.error({ err }, "imperative plugin reconcile failed");
     }
+    // Converge plugin-declared schedules against the plugin set this apply
+    // just settled, so install/uninstall/upgrade arm and disarm rows in the
+    // same poke. Imported lazily to keep the notification pipeline out of
+    // this module's static graph (sidecar workers import it for hook reads).
+    // Self-contained: never throws and checks DB readiness itself.
+    try {
+      const { reconcilePluginSchedules } =
+        await import("../schedule/plugin-schedule-reconciler.js");
+      await reconcilePluginSchedules();
+    } catch (err) {
+      log.error({ err }, "plugin schedule reconcile failed");
+    }
   })().finally(() => {
     reconcileInFlight = null;
   });
@@ -306,32 +313,26 @@ export async function reconcilePluginSourcesNow(): Promise<void> {
  * never dynamically imports code from outside the designated plugin roots,
  * regardless of what the collector walked.
  *
- * Uses `realpathSync` to resolve symlinks before the prefix check, so a
- * symlinked path that looks like it's under the plugins dir but points
- * elsewhere is rejected.
+ * Containment runs through {@link isInsidePluginRoot}, which resolves the
+ * candidate and the root, so a symlinked path that looks like it's under the
+ * plugins dir but points elsewhere is rejected while a plugins dir reached
+ * through a symlinked path component still accepts its own children.
  */
 function isAllowedPluginDir(
   dir: string,
   pluginsDir: string,
   hooksDir: string,
 ): boolean {
-  let resolved: string;
-  try {
-    resolved = realpathSync(dir);
-  } catch {
-    // Directory doesn't exist or is inaccessible — allow it through so
-    // bringUpPlugin/parsePluginManifest can log the normal failure. The
+  if (!existsSync(dir)) {
+    // Directory doesn't exist or is inaccessible: allow it through so
+    // bringUpPlugin/parsePluginManifest can log the normal failure, and so a
+    // directory that just went away still reaches its teardown branch. The
     // danger is importing code from an unexpected location, not a missing
     // directory.
     return true;
   }
-  const normalizedPluginsDir = pluginsDir + "/";
-  const normalizedHooksDir = hooksDir + "/";
   return (
-    resolved === pluginsDir ||
-    resolved.startsWith(normalizedPluginsDir) ||
-    resolved === hooksDir ||
-    resolved.startsWith(normalizedHooksDir)
+    isInsidePluginRoot(dir, pluginsDir) || isInsidePluginRoot(dir, hooksDir)
   );
 }
 
@@ -754,6 +755,17 @@ async function scanPlugins(): Promise<void> {
     } catch {
       continue;
     }
+    // Judge the entry by where it resolves. A symlinked plugin root pointing
+    // out of the plugins directory is not an install, and activating one at
+    // boot would run code that enumeration and the reload path both refuse to
+    // touch.
+    if (!isInsidePluginRoot(pluginDir, pluginsDir)) {
+      log.warn(
+        { pluginDir },
+        "plugin root resolves outside the plugins directory, skipping",
+      );
+      continue;
+    }
     if (!existsSync(join(pluginDir, "package.json"))) {
       continue;
     }

package/src/plugins/types.ts

@@ -147,9 +147,9 @@ export interface TurnContext {
   /** Human-readable interface label (e.g. "vellum", "telegram"). */
   readonly interfaceName?: string;
   /**
-   * Client OS surface ("web" | "ios" | "macos"), reported independently of
-   * the transport interface. Rendered as the `client_os:` line so the model
-   * knows the platform even though the web/iOS/macOS apps share one `"web"`
+   * Client OS surface, reported independently of the transport interface.
+   * Rendered as the `client_os:` line so the model knows the platform even
+   * though browser, mobile, and desktop apps share one `"web"`
    * transport interface.
    */
   readonly clientOs?: string;
@@ -163,10 +163,13 @@ export interface TurnContext {
     /** Canonical id the app tools key off (an opaque UUID for workspace apps). */
     appId: string;
     name: string;
-    /** Directory stem: the readable handle for an otherwise opaque id. */
+    /**
+     * Directory stem: the readable handle for an otherwise opaque id, and the
+     * piece the model joins with the workspace root and the app-builder skill's
+     * `data/apps/<slug>/` layout to reach the app's files. The resolved
+     * directory itself is not sent, being derivable from those three.
+     */
     slug: string;
-    /** Absolute path of the app's source directory. */
-    sourceDir: string;
     /** Owning plugin, when the app is plugin-bundled rather than sandbox-built. */
     pluginName?: string;
   } | null;
@@ -350,10 +353,68 @@ export interface Injector {
 // surfaces (e.g. `routes/`) are served from their workspace location rather
 // than wired through the loader, so they carry no `Plugin` contribution slot.
 
+/**
+ * How the worker resolves a claimed job row after its handler returns
+ * without throwing. Handlers that report failure through a returned domain
+ * outcome (rather than a throw) translate that outcome into one of these at
+ * the registration site, so the persisted `memory_jobs.status` reflects what
+ * actually happened instead of unconditionally reading `completed`.
+ *
+ * - `completed`: the work succeeded (or was a legitimate no-op).
+ * - `failed`: terminal failure; the row is dead-lettered with
+ *   `errorMessage` as `last_error`. Use when retry is owned elsewhere
+ *   (event-driven re-enqueue, durable backoff checkpoints).
+ * - `retryable`: transient failure; the row re-enters the queue's
+ *   attempt-budgeted retry machinery with `errorMessage` recorded.
+ * - `deferred`: the work could not run yet for a reason external to the
+ *   job (e.g. its source conversation is mid-turn); the row goes back to
+ *   pending on the deferral counter's backoff curve and dead-letters with
+ *   `deferralExhaustedMessage` once the deferral budget is spent.
+ */
+export interface JobQueueResolution {
+  queueResolution: "completed" | "failed" | "retryable" | "deferred";
+  /** Persisted to `memory_jobs.last_error` for `failed` / `retryable`. */
+  errorMessage?: string;
+  /** Retry delay override for `retryable`. */
+  retryDelayMs?: number;
+  /** Terminal `last_error` when a `deferred` job exhausts its budget. */
+  deferralExhaustedMessage?: string;
+}
+
+const QUEUE_RESOLUTIONS = new Set([
+  "completed",
+  "failed",
+  "retryable",
+  "deferred",
+]);
+
+/**
+ * Narrow an arbitrary handler return value to a {@link JobQueueResolution}.
+ * Anything else (including `undefined` and legacy domain outcomes) resolves
+ * as `completed`, preserving the historical contract for handlers that only
+ * signal failure by throwing.
+ */
+export function isJobQueueResolution(
+  value: unknown,
+): value is JobQueueResolution {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "queueResolution" in value &&
+    typeof (value as { queueResolution: unknown }).queueResolution ===
+      "string" &&
+    QUEUE_RESOLUTIONS.has(
+      (value as { queueResolution: string }).queueResolution,
+    )
+  );
+}
+
 /**
  * Processes one claimed background job: receives the claimed job row and the
- * live assistant config. The return value is ignored — a handler signals
- * failure by throwing, which the worker records against the job.
+ * live assistant config. A handler signals failure by throwing (recorded
+ * against the job's attempt budget) or by returning a
+ * {@link JobQueueResolution}; any other return value resolves the row as
+ * `completed`.
  */
 export type JobHandler = (job: MemoryJob, config: AssistantConfig) => unknown;
 

package/src/prompts/persona-resolver.ts

@@ -82,7 +82,10 @@ function readPersonaFile(filePath: string): string | null {
  * (`guardianExternalUserId`): the info read is keyed on that address so it
  * matches the gateway's guardian binding. When the context carries no guardian
  * address (desktop / native turns), fall back to the channel's guardian
- * contact. Returns `"guardian.md"` when the resolved guardian has no userFile.
+ * contact, then any guardian: the guardian may be bound on a channel other
+ * than the turn's source, and the construction-time warm populates both the
+ * channel-filtered and unfiltered cache keys. Returns `"guardian.md"` when the
+ * resolved guardian has no userFile.
  */
 function resolveGuardianUserFile(trustContext: TrustContext): string | null {
   if (trustContext.guardianExternalUserId) {
@@ -94,7 +97,8 @@ function resolveGuardianUserFile(trustContext: TrustContext): string | null {
       return guardianContact.userFile ?? "guardian.md";
     }
   }
-  const guardian = peekGuardianForChannel(trustContext.sourceChannel);
+  const guardian =
+    peekGuardianForChannel(trustContext.sourceChannel) ?? peekAnyGuardian();
   return guardian
     ? (guardianDeliveryUserFile(guardian) ?? "guardian.md")
     : null;

package/src/prompts/system-prompt.ts

@@ -48,13 +48,61 @@ function hasPopulatedUsersDir(): boolean {
   }
 }
 
-function hasExistingConversations(): boolean {
+/**
+ * Conversation types that are internal side channels rather than threads the
+ * user opens: onboarding research, personality/identity rewrites, heartbeat
+ * and scheduled runs, plus legacy private rows.
+ */
+const HIDDEN_CONVERSATION_TYPES = new Set([
+  "background",
+  "scheduled",
+  "private",
+]);
+
+/**
+ * Whether the workspace carries at least one standard (user-visible)
+ * conversation.
+ *
+ * Classifies each disk-view directory by the `type` in its `meta.json` rather
+ * than counting raw directory entries, because hidden side threads get a
+ * disk-view directory too and must not be mistaken for the user's own history.
+ * The type read here is the same value `countConversations("standard")` filters
+ * on, but the answer comes off disk rather than out of the database:
+ * `ensurePromptFiles()` runs before `initializeDb()` settles in
+ * `daemon/lifecycle.ts`, so a query here would hit a partially-migrated schema.
+ *
+ * Only directories are classified. The layout is browsable, so stray files such
+ * as `.DS_Store` sit beside the conversations, and a `meta.json` read under one
+ * fails indistinguishably from an unreadable conversation. Directory names are
+ * not filtered further, because both the canonical `<ISO>_<id>` layout and the
+ * legacy `<id>_<ISO>` one name real conversations.
+ *
+ * A directory whose `meta.json` is missing or unreadable counts as standard: a
+ * directory the daemon cannot classify is far more likely to be legacy history
+ * than a side thread, and over-counting only keeps onboarding from re-running.
+ */
+function hasStandardConversations(): boolean {
   try {
     const convDir = getConversationsDir();
     if (!existsSync(convDir)) {
       return false;
     }
-    return readdirSync(convDir).length > 0;
+    return readdirSync(convDir, { withFileTypes: true }).some((entry) => {
+      if (!entry.isDirectory()) {
+        return false;
+      }
+      try {
+        const meta = JSON.parse(
+          readFileSync(join(convDir, entry.name, "meta.json"), "utf-8"),
+        ) as { type?: unknown };
+        return (
+          typeof meta.type !== "string" ||
+          !HIDDEN_CONVERSATION_TYPES.has(meta.type)
+        );
+      } catch {
+        return true;
+      }
+    });
   } catch {
     return false;
   }
@@ -78,14 +126,14 @@ export function ensurePromptFiles(): void {
 
   // Track whether this is a fresh workspace.  A workspace counts as fresh
   // only when none of these signals are present: core prompt files, a
-  // populated `users/` directory, or existing conversations.  Upgraded
-  // workspaces that dropped USER.md but still carry personas or history
-  // would otherwise be mistaken for fresh installs and re-trigger
+  // populated `users/` directory, or existing standard conversations.
+  // Upgraded workspaces that dropped USER.md but still carry personas or
+  // history would otherwise be mistaken for fresh installs and re-trigger
   // onboarding.
   const isFirstRun =
     PROMPT_FILES.every((file) => !existsSync(getWorkspacePromptPath(file))) &&
     !hasPopulatedUsersDir() &&
-    !hasExistingConversations();
+    !hasStandardConversations();
 
   for (const file of PROMPT_FILES) {
     const dest = getWorkspacePromptPath(file);
@@ -152,18 +200,25 @@ export function ensurePromptFiles(): void {
   // Auto-delete stale BOOTSTRAP.md at startup.  The model is instructed to
   // delete it at the end of the first conversation, but if the user closes
   // the app or starts a new thread before the model gets another turn, it
-  // never gets the chance.  If BOOTSTRAP.md still exists but prior
-  // conversations are present, the onboarding window has passed — clean up.
+  // never gets the chance.  If BOOTSTRAP.md still exists but prior standard
+  // conversations are present, the onboarding window has passed, so clean up.
+  //
+  // Only standard conversations count.  Onboarding mints hidden side threads
+  // before the user's first visible chat, so counting those would delete
+  // BOOTSTRAP.md out from under that chat on the next daemon restart.
+  //
+  // This gate is one conversation stricter than the in-process gate in
+  // `persistence/conversation-key-store.ts`, which keeps BOOTSTRAP.md through
+  // the whole first standard conversation and deletes it when a second one is
+  // created.  A restart while the user is still inside that first conversation
+  // deletes BOOTSTRAP.md from under it.
   const bootstrapCleanup = getWorkspacePromptPath("BOOTSTRAP.md");
-  if (!isFirstRun && existsSync(bootstrapCleanup)) {
-    const convDir = getConversationsDir();
-    try {
-      if (existsSync(convDir) && readdirSync(convDir).length > 0) {
-        cleanupBootstrapFiles("prior conversations exist");
-      }
-    } catch (err) {
-      log.warn({ err }, "Failed to auto-delete stale BOOTSTRAP.md");
-    }
+  if (
+    !isFirstRun &&
+    existsSync(bootstrapCleanup) &&
+    hasStandardConversations()
+  ) {
+    cleanupBootstrapFiles("prior conversations exist");
   }
 
   // Seed HEARTBEAT.md — always created if missing so the heartbeat service

package/src/providers/__tests__/inference.test.ts

@@ -181,6 +181,46 @@ describe("Connection CRUD", () => {
     expect(fetched?.auth.type).toBe("api_key");
   });
 
+  test("updateConnection: provider correction rides an auth rewrite", () => {
+    // The ChatGPT sign-in flow stamps provider "openai" when it writes
+    // subscription auth, so a claiming row with another provider cannot
+    // strand the fresh token behind derived platform auth.
+    const { db } = setupDb();
+    createConnection(db, {
+      name: "chatgpt-subscription",
+      provider: "vellum",
+      auth: { type: "platform" },
+    });
+    const result = updateConnection(db, "chatgpt-subscription", {
+      auth: {
+        type: "oauth_subscription",
+        credential: "credential/chatgpt/access_token",
+      },
+      provider: "openai",
+    });
+    expect(result.ok).toBe(true);
+    const fetched = getConnection(db, "chatgpt-subscription");
+    expect(fetched?.provider).toBe("openai");
+    expect(fetched?.auth.type).toBe("oauth_subscription");
+  });
+
+  test("updateConnection: rejects an unknown provider", () => {
+    const { db } = setupDb();
+    createConnection(db, {
+      name: "updatable-provider",
+      provider: "anthropic",
+      auth: { type: "api_key", credential: "credential/anthropic/api_key" },
+    });
+    const result = updateConnection(db, "updatable-provider", {
+      auth: { type: "api_key", credential: "credential/anthropic/api_key" },
+      provider: "not-a-provider",
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe("invalid_provider");
+    }
+  });
+
   test("updateConnection — rejects unknown name", () => {
     const { db } = setupDb();
     const result = updateConnection(db, "ghost", { auth: { type: "none" } });

package/src/providers/__tests__/preflight-resolved-config.test.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, mock, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
 let connectionsByName: Record<string, unknown> = {};
 let secureKeys: Record<string, string | undefined> = {};
@@ -74,6 +74,11 @@ beforeEach(() => {
   secureKeys = { "credential/anthropic/api_key": "sk-ant" };
   cesUnreachable = false;
   platformLoggedIn = false;
+  delete process.env.IS_PLATFORM;
+});
+
+afterEach(() => {
+  delete process.env.IS_PLATFORM;
 });
 
 describe("preflightResolvedConfig", () => {
@@ -300,3 +305,55 @@ describe("preflightResolvedConfig", () => {
     expect(await preflightError(resolved())).toBeUndefined();
   });
 });
+
+describe("preflightResolvedConfig platform-managed credential messaging", () => {
+  const platformManaged = () => {
+    connectionsByName = {
+      vellum: {
+        name: "vellum",
+        provider: "vellum",
+        auth: { type: "platform" },
+      },
+    };
+    process.env.IS_PLATFORM = "true";
+  };
+  const managedRoute = () => resolved({ provider_connection: "vellum" });
+
+  test("store unreachable surfaces a retriable message with no login text", async () => {
+    platformManaged();
+    cesUnreachable = true;
+    const err = await preflightError(managedRoute());
+    expect(err?.reason).toBe("platform_unauthenticated");
+    expect(err?.message).toContain("temporarily unavailable");
+    expect(err?.message).not.toContain("log in");
+  });
+
+  test("credential absent asks for platform re-provisioning, not a login", async () => {
+    platformManaged();
+    // Logged out with a reachable store means the credential is genuinely absent.
+    const err = await preflightError(managedRoute());
+    expect(err?.reason).toBe("platform_unauthenticated");
+    expect(err?.message).toContain("must be re-provisioned");
+    expect(err?.message).not.toContain("log in");
+  });
+
+  test("a healthy platform login passes silently", async () => {
+    platformManaged();
+    platformLoggedIn = true;
+    expect(await preflightError(managedRoute())).toBeUndefined();
+  });
+
+  test("non-platform install keeps the log-in-or-switch wording", async () => {
+    connectionsByName = {
+      vellum: {
+        name: "vellum",
+        provider: "vellum",
+        auth: { type: "platform" },
+      },
+    };
+    // IS_PLATFORM left unset covers both local and self-hosted Docker installs.
+    const err = await preflightError(managedRoute());
+    expect(err?.reason).toBe("platform_unauthenticated");
+    expect(err?.message).toContain("log in or pick a different provider");
+  });
+});