orionfold-relay 0.24.0 → 0.24.1

package/dist/cli.js

@@ -21726,6 +21726,41 @@ var init_openai_direct = __esm({
   }
 });
 
+// src/lib/agents/runtime/ollama-model-resolver.ts
+async function listPulledOllamaModels(baseUrl) {
+  try {
+    const response = await fetch(`${baseUrl}/api/tags`, {
+      signal: AbortSignal.timeout(5e3)
+    });
+    if (!response.ok) return [];
+    const data = await response.json();
+    return (data.models ?? []).map((m) => m.name).filter((n) => typeof n === "string" && n.length > 0);
+  } catch {
+    return [];
+  }
+}
+async function resolveOllamaModel(baseUrl, requestedModel, defaultModel) {
+  const explicit = requestedModel?.trim() || defaultModel?.trim();
+  if (explicit) return explicit;
+  const pulled = await listPulledOllamaModels(baseUrl);
+  if (pulled.length > 0) return pulled[0];
+  throw new OllamaModelNotConfiguredError();
+}
+var OllamaModelNotConfiguredError;
+var init_ollama_model_resolver = __esm({
+  "src/lib/agents/runtime/ollama-model-resolver.ts"() {
+    "use strict";
+    OllamaModelNotConfiguredError = class extends Error {
+      constructor(message) {
+        super(
+          message ?? "No Ollama model is configured. Pull a model (e.g. `ollama pull llama3.2`) or set a default in Settings \u2192 Ollama."
+        );
+        this.name = "OllamaModelNotConfiguredError";
+      }
+    };
+  }
+});
+
 // src/lib/agents/runtime/ollama-adapter.ts
 import { eq as eq38 } from "drizzle-orm";
 async function getOllamaBaseUrl() {
@@ -21734,11 +21769,11 @@ async function getOllamaBaseUrl() {
   const url = await getSetting2(SETTINGS_KEYS2.OLLAMA_BASE_URL);
   return url || DEFAULT_OLLAMA_BASE_URL;
 }
-async function getOllamaModel() {
+async function getOllamaModel(baseUrl) {
   const { getSetting: getSetting2 } = await Promise.resolve().then(() => (init_helpers(), helpers_exports));
   const { SETTINGS_KEYS: SETTINGS_KEYS2 } = await Promise.resolve().then(() => (init_settings(), settings_exports));
-  const model = await getSetting2(SETTINGS_KEYS2.OLLAMA_DEFAULT_MODEL);
-  return model || DEFAULT_OLLAMA_MODEL;
+  const defaultModel = await getSetting2(SETTINGS_KEYS2.OLLAMA_DEFAULT_MODEL);
+  return resolveOllamaModel(baseUrl, null, defaultModel);
 }
 async function streamOllamaChat(baseUrl, model, messages, signal) {
   const response = await fetch(`${baseUrl}/api/chat`, {
@@ -21833,7 +21868,7 @@ async function executeOllamaTask(taskId) {
     await db.update(tasks).set({ status: "running", updatedAt: /* @__PURE__ */ new Date() }).where(eq38(tasks.id, taskId));
     const ctx = await buildTaskQueryContext(task, agentProfileId);
     const baseUrl = await getOllamaBaseUrl();
-    const modelId = await getOllamaModel();
+    const modelId = await getOllamaModel(baseUrl);
     const messages = [];
     if (ctx.systemInstructions) {
       messages.push({ role: "system", content: ctx.systemInstructions });
@@ -21924,7 +21959,7 @@ async function executeOllamaTask(taskId) {
 }
 async function runOllamaTaskAssist(input) {
   const baseUrl = await getOllamaBaseUrl();
-  const modelId = await getOllamaModel();
+  const modelId = await getOllamaModel(baseUrl);
   const profileIds = listProfiles().map((p) => p.id);
   const profileList = profileIds.length > 0 ? `Available agent profiles: ${profileIds.join(", ")}` : "No explicit profiles available.";
   const systemPrompt = `You are an AI task definition assistant. Analyze the given task and return ONLY a JSON object (no markdown) with:
@@ -21980,7 +22015,7 @@ async function testOllamaConnection() {
     };
   }
 }
-var DEFAULT_OLLAMA_BASE_URL, DEFAULT_OLLAMA_MODEL, ollamaRuntimeAdapter;
+var DEFAULT_OLLAMA_BASE_URL, ollamaRuntimeAdapter;
 var init_ollama_adapter = __esm({
   "src/lib/agents/runtime/ollama-adapter.ts"() {
     "use strict";
@@ -21989,10 +22024,10 @@ var init_ollama_adapter = __esm({
     init_execution_manager();
     init_claude_agent();
     init_catalog2();
+    init_ollama_model_resolver();
     init_registry2();
     init_ledger();
     DEFAULT_OLLAMA_BASE_URL = "http://localhost:11434";
-    DEFAULT_OLLAMA_MODEL = "llama3.2";
     ollamaRuntimeAdapter = {
       metadata: getRuntimeCatalogEntry("ollama"),
       async executeTask(taskId) {
@@ -25803,8 +25838,8 @@ import { execFileSync as execFileSync3 } from "child_process";
 import yaml12 from "js-yaml";
 import semver from "semver";
 function relayCoreVersion() {
-  if (semver.valid("0.24.0")) {
-    return "0.24.0";
+  if (semver.valid("0.24.1")) {
+    return "0.24.1";
   }
   try {
     const root = getAppRoot(import.meta.dirname, 3);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orionfold-relay",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "description": "Orionfold Relay — a local-first, multi-agent orchestration runtime and builder scaffold for AI-native work.",
   "keywords": [
     "ai",

package/src/app/api/snapshots/[id]/restore/route.ts

@@ -2,6 +2,7 @@ import { NextRequest, NextResponse } from "next/server";
 import {
   restoreFromSnapshot,
   isSnapshotLocked,
+  SnapshotBusyError,
 } from "@/lib/snapshots/snapshot-manager";
 import { db } from "@/lib/db";
 import { tasks } from "@/lib/db/schema";
@@ -51,6 +52,11 @@ export async function POST(
         "Restore complete. Please restart the server to load the restored database.",
     });
   } catch (error) {
+    // Lock contention is a 409, not a server error — never conflate it with a
+    // genuine failure (issue #24).
+    if (error instanceof SnapshotBusyError) {
+      return NextResponse.json({ error: error.message }, { status: 409 });
+    }
     return NextResponse.json(
       {
         error:

package/src/app/api/snapshots/route.ts

@@ -4,6 +4,7 @@ import {
   listSnapshots,
   getSnapshotsSize,
   isSnapshotLocked,
+  SnapshotBusyError,
 } from "@/lib/snapshots/snapshot-manager";
 
 /** GET /api/snapshots — list all snapshots with disk usage */
@@ -46,6 +47,11 @@ export async function POST(req: NextRequest) {
 
     return NextResponse.json(snapshot, { status: 201 });
   } catch (error) {
+    // A lock grabbed between the isSnapshotLocked() check and createSnapshot is
+    // still contention, not a server error (issue #24).
+    if (error instanceof SnapshotBusyError) {
+      return NextResponse.json({ error: error.message }, { status: 409 });
+    }
     return NextResponse.json(
       { error: error instanceof Error ? error.message : "Failed to create snapshot" },
       { status: 500 }

package/src/components/chat/app-composer-hero.tsx

@@ -16,7 +16,7 @@ const EXAMPLE_PROMPTS: { label: string; prompt: string }[] = [
   {
     label: "Build me a reading log…",
     prompt:
-      "Build me a reading log. Track each book with title, author, date finished, and a 1–5 rating. Every Friday at 5pm, summarize what I read this week.",
+      "Build me a reading log. Track each book with title, author, date finished, and a rating from 1 to 5. Every Friday at 5pm, summarize what I read this week.",
   },
   {
     label: "Build me an expense tracker for my contractors…",

package/src/components/chat/chat-empty-state.tsx

@@ -97,10 +97,10 @@ export function ChatEmptyState({
         <div className="flex h-12 w-12 items-center justify-center rounded-xl bg-primary/10">
           <Bot className="h-6 w-6 text-primary" />
         </div>
-        <h2 className="text-lg font-semibold">Describe an app. Orionfold Relay builds it.</h2>
+        <h2 className="text-lg font-semibold">Describe an app. Relay builds it.</h2>
         <p className="text-sm text-muted-foreground text-center max-w-md">
-          Profiles, blueprints, tables, and schedules, composed from a single prompt.
-          Or ask anything about your workspace.
+          One prompt builds the whole app: profiles, blueprints, tables, and
+          schedules. Or ask anything about your workspace.
         </p>
       </div>
 

package/src/components/dashboard/welcome-landing.tsx

@@ -9,17 +9,17 @@ const pillars = [
   {
     icon: Sparkles,
     title: "Apps from a sentence",
-    description: "Describe what you do every week. Orionfold Relay composes the profile, blueprint, schedule, and tables into a running app. No code.",
+    description: "Tell Relay what you do each week. It builds a running app for you. No code needed.",
   },
   {
     icon: Shield,
     title: "Your rules, enforced",
-    description: "Every agent action respects your policies. Full audit trail for every decision.",
+    description: "Agents follow your rules on every task. You get a full record of what they did.",
   },
   {
     icon: Wallet,
     title: "Know what you spend",
-    description: "Track spend per task, per provider. Budget guardrails prevent surprise bills.",
+    description: "See the cost of each task. Set a budget so you never get a surprise bill.",
   },
 ];
 
@@ -44,7 +44,7 @@ export function WelcomeLanding({ starters = [] }: WelcomeLandingProps) {
         Welcome
       </h1>
       <p className="text-base text-muted-foreground mb-8 max-w-lg">
-        Your AI Business Operating System. Describe an app, Orionfold Relay builds it, and runs it on your rules, your budget, your data.
+        Relay is your AI business operating system. Describe an app. Relay builds it and runs it on your rules, your budget, and your data.
       </p>
 
       <div className="grid grid-cols-1 sm:grid-cols-3 gap-4 w-full mb-8">

package/src/components/onboarding/runtime-preference-modal.tsx

@@ -42,7 +42,7 @@ const STATIC_OPTIONS: readonly PreferenceOption[] = [
     id: "quality",
     label: "Best quality",
     capabilityNote:
-      "Top-tier model (Opus). Full filesystem + tool access; highest cost.",
+      "Our smartest model (Opus). It can use every tool and read files. Costs the most.",
     recommendedModel: "opus",
     icon: Sparkles,
   },
@@ -50,7 +50,7 @@ const STATIC_OPTIONS: readonly PreferenceOption[] = [
     id: "balanced",
     label: "Balanced (recommended)",
     capabilityNote:
-      "Strong quality at a moderate price (Sonnet). Same capabilities as Opus.",
+      "Great quality for less (Sonnet). It can do everything Opus can.",
     recommendedModel: "sonnet",
     icon: Scale,
   },
@@ -58,7 +58,7 @@ const STATIC_OPTIONS: readonly PreferenceOption[] = [
     id: "cost",
     label: "Lowest cost",
     capabilityNote:
-      "Fastest, cheapest cloud model (Haiku). Same tool surface as Sonnet.",
+      "Our fastest, cheapest model (Haiku). It uses the same tools as Sonnet.",
     recommendedModel: "haiku",
     icon: DollarSign,
   },
@@ -66,7 +66,7 @@ const STATIC_OPTIONS: readonly PreferenceOption[] = [
     id: "privacy",
     label: "Best privacy (local only)",
     capabilityNote:
-      "Runs entirely on your machine via Ollama. No cloud calls; no MCP servers; smaller context window.",
+      "Runs on your own computer with Ollama. Nothing leaves your machine. It skips cloud tools and holds less at once.",
     recommendedModel: "", // resolved against the Ollama discovery list at submit time
     icon: Lock,
   },
@@ -168,7 +168,7 @@ export function RuntimePreferenceModal({
       return {
         modelId: BALANCED_FALLBACK_MODEL,
         fallbackNote:
-          "No local models found. Point Orionfold Relay at your Ollama install in Settings. Using balanced default for now.",
+          "We could not find a local model. We will use the balanced model for now. To use your own, point Relay at Ollama in Settings.",
       };
     }
     return {
@@ -248,8 +248,8 @@ export function RuntimePreferenceModal({
         <DialogHeader>
           <DialogTitle>Pick your default chat model</DialogTitle>
           <DialogDescription>
-            We&apos;ll set sensible defaults based on what matters most to you.
-            You can change this anytime in Settings.
+            Tell us what matters most and we will set a good default. You can
+            change it anytime in Settings.
           </DialogDescription>
         </DialogHeader>
 
@@ -311,7 +311,7 @@ export function RuntimePreferenceModal({
                 onClick={handleSkip}
                 disabled={submitting}
               >
-                Skip — use default
+                Skip, use default
               </Button>
               <Button onClick={handleConfirm} disabled={submitting}>
                 {submitting ? "Saving…" : "Continue"}

package/src/components/profiles/profile-card.tsx

@@ -3,7 +3,7 @@
 import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
 import { Badge } from "@/components/ui/badge";
 import { Download } from "lucide-react";
-import { listRuntimeCatalog } from "@/lib/agents/runtime/catalog";
+import type { AgentRuntimeId } from "@/lib/agents/runtime/catalog";
 import { getSupportedRuntimes } from "@/lib/agents/profiles/compatibility";
 import { IconCircle, getProfileIcon, getDomainColors } from "@/lib/constants/card-icons";
 import type { AgentProfile } from "@/lib/agents/profiles/types";
@@ -14,13 +14,23 @@ interface ProfileCardProps {
   onClick: () => void;
 }
 
+/**
+ * Short chip labels for the compact runtime-coverage row. Distinct from the
+ * catalog's full `label` (used in profile-detail-view) — a card needs one word.
+ * Keyed by runtime id, NOT provider: claude-code vs anthropic-direct share a
+ * provider, as do openai-codex vs openai-direct, so a provider-based (or the old
+ * `label.includes("Codex")`) heuristic collapses distinct runtimes — notably
+ * Ollama, the $0-local differentiator, which used to render as "Claude".
+ */
+const RUNTIME_SHORT_LABEL: Record<AgentRuntimeId, string> = {
+  "claude-code": "Claude",
+  "openai-codex-app-server": "Codex",
+  "anthropic-direct": "Anthropic",
+  "openai-direct": "OpenAI",
+  ollama: "Ollama (Local)",
+};
+
 export function ProfileCard({ profile, isBuiltin = false, onClick }: ProfileCardProps) {
-  const runtimeLabelMap = new Map(
-    listRuntimeCatalog().map((runtime) => [
-      runtime.id,
-      runtime.label.includes("Codex") ? "Codex" : "Claude",
-    ])
-  );
 
   return (
     <Card
@@ -67,7 +77,7 @@ export function ProfileCard({ profile, isBuiltin = false, onClick }: ProfileCard
         <div className="flex flex-wrap gap-1">
           {getSupportedRuntimes(profile).map((runtimeId) => (
             <Badge key={runtimeId} variant="secondary" className="text-xs">
-              {runtimeLabelMap.get(runtimeId) ?? runtimeId}
+              {RUNTIME_SHORT_LABEL[runtimeId] ?? runtimeId}
             </Badge>
           ))}
         </div>

package/src/lib/agents/runtime/ollama-adapter.ts

@@ -12,6 +12,7 @@ import { eq } from "drizzle-orm";
 import { setExecution, removeExecution, getExecution } from "../execution-manager";
 import { buildTaskQueryContext, createTaskUsageState } from "../claude-agent";
 import { getRuntimeCatalogEntry } from "./catalog";
+import { resolveOllamaModel } from "./ollama-model-resolver";
 import type {
   AgentRuntimeAdapter,
   RuntimeConnectionResult,
@@ -24,7 +25,6 @@ import { recordUsageLedgerEntry, resolveUsageActivityType } from "@/lib/usage/le
 // ── Constants ───────────────────────────────────────────────────────
 
 const DEFAULT_OLLAMA_BASE_URL = "http://localhost:11434";
-const DEFAULT_OLLAMA_MODEL = "llama3.2";
 
 // ── Settings helpers ────────────────────────────────────────────────
 
@@ -35,11 +35,16 @@ async function getOllamaBaseUrl(): Promise<string> {
   return url || DEFAULT_OLLAMA_BASE_URL;
 }
 
-async function getOllamaModel(): Promise<string> {
+/**
+ * Resolve the effective Ollama model for a task. Uses the configured default,
+ * else the first actually-pulled model, else throws a named error — never the
+ * old hardcoded `llama3.2` phantom (issue #25).
+ */
+async function getOllamaModel(baseUrl: string): Promise<string> {
   const { getSetting } = await import("@/lib/settings/helpers");
   const { SETTINGS_KEYS } = await import("@/lib/constants/settings");
-  const model = await getSetting(SETTINGS_KEYS.OLLAMA_DEFAULT_MODEL);
-  return model || DEFAULT_OLLAMA_MODEL;
+  const defaultModel = await getSetting(SETTINGS_KEYS.OLLAMA_DEFAULT_MODEL);
+  return resolveOllamaModel(baseUrl, null, defaultModel);
 }
 
 // ── NDJSON streaming chat ───────────────────────────────────────────
@@ -186,7 +191,7 @@ async function executeOllamaTask(taskId: string): Promise<void> {
 
     const ctx = await buildTaskQueryContext(task, agentProfileId);
     const baseUrl = await getOllamaBaseUrl();
-    const modelId = await getOllamaModel();
+    const modelId = await getOllamaModel(baseUrl);
 
     // Build messages
     const messages: OllamaChatMessage[] = [];
@@ -300,7 +305,7 @@ async function executeOllamaTask(taskId: string): Promise<void> {
 
 async function runOllamaTaskAssist(input: TaskAssistInput): Promise<TaskAssistResponse> {
   const baseUrl = await getOllamaBaseUrl();
-  const modelId = await getOllamaModel();
+  const modelId = await getOllamaModel(baseUrl);
 
   const profileIds = listProfiles().map((p) => p.id);
   const profileList = profileIds.length > 0

package/src/lib/agents/runtime/ollama-model-resolver.ts

@@ -0,0 +1,76 @@
+/**
+ * Ollama model resolution — import-free leaf.
+ *
+ * Shared by the task adapter (`ollama-adapter.ts`, runtime-registry-reachable)
+ * and the chat engine (`ollama-engine.ts`). Kept dependency-free (only `fetch`)
+ * so it can never introduce a module-load cycle into the runtime catalog graph
+ * (see memory `shared-constant-zero-import-leaf` + the smoke-test budget rule).
+ *
+ * Fixes issue #25: a fresh install has no `OLLAMA_DEFAULT_MODEL` setting, so the
+ * old code fell back to a hardcoded `llama3.2` that no customer had pulled →
+ * every Ollama task 404'd. We instead resolve to an actually-pulled model, or
+ * fail with a named, actionable error.
+ */
+
+/**
+ * Raised when no Ollama model can be resolved — no explicit/default model is
+ * set and the local Ollama has no models pulled. Named so callers surface an
+ * actionable message instead of a raw 404 on a phantom model (CLAUDE.md #1/#2).
+ */
+export class OllamaModelNotConfiguredError extends Error {
+  constructor(message?: string) {
+    super(
+      message ??
+        "No Ollama model is configured. Pull a model (e.g. `ollama pull llama3.2`) or set a default in Settings → Ollama.",
+    );
+    this.name = "OllamaModelNotConfiguredError";
+  }
+}
+
+interface OllamaTagsResponse {
+  models?: Array<{ name?: string }>;
+}
+
+/** List the models currently pulled into the local Ollama, newest-first order as returned. */
+export async function listPulledOllamaModels(baseUrl: string): Promise<string[]> {
+  try {
+    const response = await fetch(`${baseUrl}/api/tags`, {
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!response.ok) return [];
+    const data = (await response.json()) as OllamaTagsResponse;
+    return (data.models ?? [])
+      .map((m) => m.name)
+      .filter((n): n is string => typeof n === "string" && n.length > 0);
+  } catch {
+    // Connection failures surface elsewhere (testConnection); here we just
+    // report "no models available" and let the caller raise the named error.
+    return [];
+  }
+}
+
+/**
+ * Resolve the effective Ollama model.
+ *
+ * Precedence: an explicitly requested model → the configured default →
+ * the first actually-pulled model. If none of those yield a model, throw
+ * {@link OllamaModelNotConfiguredError} rather than returning a phantom that
+ * would 404 at call time.
+ *
+ * @param baseUrl        Ollama base URL.
+ * @param requestedModel A caller-pinned model (e.g. chat's `ollama:` selection). Optional.
+ * @param defaultModel   The `OLLAMA_DEFAULT_MODEL` setting value. Optional/empty on fresh install.
+ */
+export async function resolveOllamaModel(
+  baseUrl: string,
+  requestedModel?: string | null,
+  defaultModel?: string | null,
+): Promise<string> {
+  const explicit = requestedModel?.trim() || defaultModel?.trim();
+  if (explicit) return explicit;
+
+  const pulled = await listPulledOllamaModels(baseUrl);
+  if (pulled.length > 0) return pulled[0];
+
+  throw new OllamaModelNotConfiguredError();
+}

package/src/lib/chat/ollama-engine.ts

@@ -19,6 +19,7 @@ import {
 import { buildChatContext } from "./context-builder";
 import { getWorkspaceContext } from "@/lib/environment/workspace-context";
 import { recordUsageLedgerEntry } from "@/lib/usage/ledger";
+import { resolveOllamaModel } from "@/lib/agents/runtime/ollama-model-resolver";
 import type { ChatStreamEvent } from "./types";
 
 /**
@@ -40,10 +41,22 @@ export async function* sendOllamaMessage(
   // Resolve Ollama base URL and model
   const baseUrl =
     (await getSetting(SETTINGS_KEYS.OLLAMA_BASE_URL)) || "http://localhost:11434";
-  const modelId =
-    conversation.modelId?.replace(/^ollama:/, "") ||
-    (await getSetting(SETTINGS_KEYS.OLLAMA_DEFAULT_MODEL)) ||
-    "llama3.2";
+  // Resolve: conversation-pinned model → configured default → first pulled
+  // model → named error. Never the old hardcoded `llama3.2` phantom (#25).
+  const requestedModel = conversation.modelId?.replace(/^ollama:/, "");
+  const defaultModel = await getSetting(SETTINGS_KEYS.OLLAMA_DEFAULT_MODEL);
+  let modelId: string;
+  try {
+    modelId = await resolveOllamaModel(baseUrl, requestedModel, defaultModel);
+  } catch (err) {
+    // Surface the "no model configured" case as a visible chat error rather
+    // than an unhandled rejection that silently kills the stream (#25, CLAUDE.md #1).
+    yield {
+      type: "error",
+      message: err instanceof Error ? err.message : "No Ollama model configured",
+    };
+    return;
+  }
 
   // Build context
   let projectName: string | null = null;

package/src/lib/packs/templates/relay-agency-pro/pack.yaml

@@ -5,19 +5,35 @@ author: Orionfold
 # This description renders as the what-you-get preview on the locked /packs
 # card (D6) — it is sales copy, not an internal summary.
 description: >
-  Relay Agency runs a workflow. Agency Pro runs your agency. Six chapters of
-  agency operating system: a Finance Cockpit that closes your month by itself
-  (per-client rollups, margin on one screen, a scheduled month-end close);
-  Intake Pipelines that turn a dropped row into the right client workflow
-  automatically; a New-Business Machine that takes a prospect from research to
-  signed engagement letter; client-safe Governance profiles with hard tool
-  policies and a per-client audit export; a deep Commercial Real Estate
-  renewal engine that covers critical dates, escalations, comps, LOI drafts,
-  and portfolio rent roll; and the Nonprofit deep chapter (added in v0.2.0,
-  your first included update), a grant pipeline that takes every opportunity from
-  fit-scored go/no-go through LOI, full application, and post-award
-  restricted-funds compliance with a reporting calendar. Everything installs
-  offline; Relay never sends your data to Orionfold.
+  Agency Pro runs your whole agency, not just one workflow. Six chapters of an
+  agency operating system:
+
+
+  Finance Cockpit closes your month for you. See margin on one screen, with
+  per-client rollups and a month-end close that runs on a schedule.
+
+
+  Intake Pipelines turn a new row into the right client workflow on their own.
+
+
+  New-Business Machine takes a prospect from first research to a signed
+  engagement letter.
+
+
+  Governance profiles keep each client safe with firm tool rules and an audit
+  export you can hand over.
+
+
+  Real Estate renewal engine tracks key dates, escalations, comps, LOI drafts,
+  and your full rent roll.
+
+
+  Nonprofit chapter (new in v0.2.0, your first free update) runs a grant
+  pipeline from a go or no-go call, through the full application, to
+  post-award reporting and fund rules.
+
+
+  Everything installs offline. Relay never sends your data to Orionfold.
 relayCore: ">=0.18.0"
 entitlement: product:orionfold-relay
 # Two-phase offer, hand-maintained to match orionfold.com/relay/ in this

package/src/lib/snapshots/snapshot-manager.ts

@@ -48,6 +48,18 @@ export function isSnapshotLocked(): boolean {
   return snapshotLock;
 }
 
+/**
+ * Raised when a snapshot operation is requested while another one holds the
+ * mutex. Named so callers (the API route) can map lock-contention to 409
+ * instead of conflating it with a genuine 500 failure. See issue #24.
+ */
+export class SnapshotBusyError extends Error {
+  constructor() {
+    super("Another snapshot operation is already in progress");
+    this.name = "SnapshotBusyError";
+  }
+}
+
 interface SnapshotManifest {
   version: 1;
   timestamp: string;
@@ -103,16 +115,38 @@ function dirSize(dirPath: string): { fileCount: number; sizeBytes: number } {
 
 /**
  * Create a full-state snapshot (DB + files).
+ *
+ * Public entry point: acquires the mutex, then delegates to the unlocked core.
+ * Throws {@link SnapshotBusyError} if another operation holds the lock.
  */
 export async function createSnapshot(
   label: string,
   type: "manual" | "auto" = "manual"
 ): Promise<SnapshotRow> {
   if (snapshotLock) {
-    throw new Error("Another snapshot operation is already in progress");
+    throw new SnapshotBusyError();
   }
 
   snapshotLock = true;
+  try {
+    return await createSnapshotUnlocked(label, type);
+  } finally {
+    snapshotLock = false;
+  }
+}
+
+/**
+ * Create a snapshot WITHOUT touching the mutex.
+ *
+ * Callers are responsible for holding `snapshotLock` around this. It exists so
+ * an already-locked operation (e.g. restoreFromSnapshot's pre-restore safety
+ * snapshot) can create a snapshot without self-deadlocking against the public
+ * `createSnapshot` lock check (issue #24).
+ */
+async function createSnapshotUnlocked(
+  label: string,
+  type: "manual" | "auto" = "manual"
+): Promise<SnapshotRow> {
   const id = generateId();
   const now = new Date();
   const sanitizedLabel = label.replace(/[^a-zA-Z0-9-_ ]/g, "_").slice(0, 100);
@@ -246,8 +280,6 @@ export async function createSnapshot(
     }
 
     throw error;
-  } finally {
-    snapshotLock = false;
   }
 }
 
@@ -353,7 +385,7 @@ export async function restoreFromSnapshot(id: string): Promise<{
   preRestoreSnapshotId: string;
 }> {
   if (snapshotLock) {
-    throw new Error("Another snapshot operation is already in progress");
+    throw new SnapshotBusyError();
   }
 
   const snapshot = await getSnapshot(id);
@@ -373,8 +405,10 @@ export async function restoreFromSnapshot(id: string): Promise<{
   snapshotLock = true;
 
   try {
-    // 1. Create pre-restore safety snapshot
-    const preRestore = await createSnapshot(
+    // 1. Create pre-restore safety snapshot. Use the UNLOCKED core: we already
+    // hold snapshotLock, and the public createSnapshot would throw
+    // SnapshotBusyError against our own lock (the issue #24 deadlock).
+    const preRestore = await createSnapshotUnlocked(
       `pre-restore-${formatTimestamp(new Date())}`,
       "auto"
     );