@animalabs/connectome-host 0.7.3 → 0.8.0

package/src/recipe.ts

@@ -11,8 +11,9 @@
  *   - Built-in default (generic assistant)
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, chmodSync } from 'node:fs';
 import { dirname, isAbsolute, resolve } from 'node:path';
+import { buildWorkspaceMounts } from './workspace-mounts.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -50,11 +51,29 @@ export interface RecipeStrategy {
   /** Complete provider-request admission ceiling for compression fallbacks,
    * including the output reserve. */
   compressionContextBudgetTokens?: number;
+  /** Residence-scoped direct source-only L1 compression: the summarizer sees
+   * only the compression marker + exact target chunk + directive (no head,
+   * recall, or non-target raw recent material). One call, not a refusal
+   * ladder. Source-preserving; L1 only. Default off. */
+  compressionSourceOnly?: boolean;
+  /** Preserve canonical + recall variants, then issue one source-only L1 request last. */
+  compressionSourceOnlyFallback?: boolean;
+  /** Legacy first-choice target-only merge request. */
+  compressionMergeSourceOnly?: boolean;
+  /** Preserve ordinary merge retries, then use target-only on the final attempt. */
+  compressionMergeSourceOnlyFallback?: boolean;
+  /** Token budget for prior recall-pair context in compression/merge
+   * requests (Context Manager `compressionRecallBudgetTokens`). */
+  compressionRecallBudgetTokens?: number;
   positionedRecallPairs?: boolean;
   recallHeaderTemplate?: string;
   targetChunkTokens?: number;
   mergeThreshold?: number;
   summaryTargetTokens?: number;
+  /** Standing production target: keep the summary forest deep enough to fit
+   *  this budget, enabling a later live-budget descent with no fold-storm and
+   *  a single KV invalidation (see context-manager productionBudgetTokens). */
+  productionBudgetTokens?: number;
   l1BudgetTokens?: number;
   l2BudgetTokens?: number;
   l3BudgetTokens?: number;
@@ -74,7 +93,10 @@ export interface RecipeStrategy {
   /** Adaptive-resolution fold planner. The host defaults this to 'kv-stable'
    *  (cache-stable compile plans; see buildFrameworkStrategy) — set explicitly
    *  only to opt into the legacy planners. */
-  foldingStrategy?: 'flat-profile' | 'oldest-first' | 'kv-stable';
+  foldingStrategy?: 'flat-profile' | 'oldest-first' | 'kv-stable' | 'kv-unified';
+  /** Complete fail-closed policy for the kv-unified solver. No live defaults
+   * are supplied: selecting kv-unified without every field is invalid. */
+  kvUnified?: RecipeKvUnifiedConfig;
   speculativeProduction?: boolean;
   /** L1 production holdback: keep the newest N closed chunks out of the
    *  speculative compression queue (default 1); demand still overrides. */
@@ -95,6 +117,37 @@ export interface RecipeStrategy {
   /** Override wording for the witnessed-record instruction ({targetTokens}
    *  substituted). */
   witnessedInstruction?: string;
+  /** Identity reminder appended to every compression/merge instruction.
+   *  For agents in multi-resident channels (and older models especially):
+   *  names the agent and directs attribution so pure-witness chunks don't
+   *  flip the summarizer into another speaker's identity. */
+  identityReminder?: string;
+}
+
+export interface RecipeKvUnifiedConfig {
+  policy: {
+    alpha: number;
+    budgetLowRatio: number;
+    budgetHighRatio: number;
+    budgetUnderLambda: number;
+    budgetOverLambda: number;
+    cacheLambda: number;
+    cacheScale: number;
+    cacheReadPrice: number;
+    cacheWritePrice: number;
+    continuityLambda: number;
+    continuityScale: number;
+    continuityRecencyHalfLifeTokens: number;
+    continuityRecencyFloor: number;
+    continuityStableHalfLife: number;
+    continuityStableFloor: number;
+  };
+  tokenBucketSize: number;
+  continuityBucketSize: number;
+  fidelityBucketSize: number;
+  labelCeiling: number;
+  adoptEpsilon: number;
+  treeifyNonContiguousSummaries: boolean;
 }
 
 export interface RecipeAgent {
@@ -102,8 +155,22 @@ export interface RecipeAgent {
   model?: string;
   /** IANA zone used when rendering wall-clock times to the agent. */
   timezone?: string;
-  /** Provider transport. Omitted preserves the historical Anthropic default. */
-  provider?: 'anthropic' | 'openai-responses' | 'openai-codex' | 'openrouter' | 'bedrock';
+  /** Provider transport. Omitted preserves the historical Anthropic default.
+   * 'mock' wires membrane's MockAdapter — canned/echo responses, no API key,
+   * no provider spend; for exercising the full host loop offline. */
+  provider?: 'anthropic' | 'openai-responses' | 'openai-codex' | 'openrouter' | 'bedrock' | 'openai-compatible' | 'mock';
+  /**
+   * Base URL of an OpenAI-compatible chat-completions endpoint, e.g.
+   * `http://localhost:11434/v1` (Ollama), a vLLM server, Together, Groq,
+   * NanoGPT... Required with `provider: 'openai-compatible'`, rejected with
+   * any other provider (those have their own `*_BASE_URL` env overrides).
+   * The API key comes from `OPENAI_COMPATIBLE_API_KEY` only — deliberately no
+   * `OPENAI_API_KEY` fallback, since `baseUrl` is recipe-controlled and a real
+   * OpenAI credential must never travel silently to an arbitrary endpoint.
+   * Local servers may need none. `agent.model` is required
+   * too — there is no sensible default model for an arbitrary endpoint.
+   */
+  baseUrl?: string;
   /** Message formatter. 'native' (default) = structured user/assistant turns.
    * 'anthropic-xml' = classic prefill format ("participant: text" runs, XML
    * tools) — for migrating prefill-era bots (chapterx borgs) with their exact
@@ -128,6 +195,28 @@ export interface RecipeAgent {
    *  Not forwarded on bedrock — that transport only has the default 5m
    *  cache and rejects the ttl field. */
   cacheTtl?: '5m' | '1h';
+  /**
+   * Prompt-cache keepalive. With `cacheTtl: '1h'`, an idle agent's cached
+   * prefix expires after an hour and its next wake pays a 2x cache write over
+   * the whole context. Reading an entry refreshes its TTL at 0.1x, so a
+   * periodic `max_tokens: 0` replay holds it warm for pennies.
+   *
+   * On by default for the anthropic provider (ignored elsewhere — bedrock has
+   * no 1h cache). Measured on fable-cm 2026-08-11..22: 49.7M tokens of cache
+   * writes followed a >1h idle gap, ~$944 of write premium at fable-5 rates
+   * that this converts to ~$308 of reads.
+   *
+   * Cost is proportional to actual idleness, not to `maxIdleHours` — a busy
+   * agent never fires one, because its own traffic already refreshes the TTL.
+   */
+  cacheKeepalive?: {
+    /** Default true (anthropic provider only). */
+    enabled?: boolean;
+    /** Stop refreshing this long after the last REAL request. Default 24. */
+    maxIdleHours?: number;
+    /** Refresh once untouched this long. Must be < 60 with a 1h TTL. Default 45. */
+    refreshAfterMinutes?: number;
+  };
   /**
    * Explicit prompt-caching override. Unset means provider-appropriate
    * default: on for everything except bedrock models that predate caching
@@ -144,9 +233,12 @@ export interface RecipeAgent {
   /**
    * Prose delivery mode (agent-framework docs/explicit-prose-routing.md).
    * 'explicit' = model prefixes plain text with `>>destination`; unprefixed
-   * prose bounces to a clipboard instead of auto-routing. Default 'locus'.
+   * prose bounces to a clipboard instead of auto-routing.
+   * 'hybrid' = unprefixed prose keeps the current locus while an exact leading
+   * `>>>destination` envelope routes through the authorized channel registry.
+   * Default 'locus'.
    */
-  proseRouting?: 'locus' | 'explicit';
+  proseRouting?: 'locus' | 'explicit' | 'hybrid' | 'disabled';
   /**
    * Extra Anthropic beta flags sent as the `anthropic-beta` header on every
    * request (e.g. `["context-1m-2025-08-07"]` for the 1M context window on
@@ -186,6 +278,15 @@ export interface RecipeAgent {
   codex?: {
     fastMode?: boolean;
   };
+  /** Mock-provider settings. Only used with `provider: "mock"`. The default
+   * (no block) echoes the last user message back — the most informative shape
+   * for interactive smoke runs, since you can see your own words complete the
+   * loop. `echoMode: false` returns `defaultResponse` instead, which gives
+   * deterministic output for scripted tests. */
+  mock?: {
+    echoMode?: boolean;
+    defaultResponse?: string;
+  };
   /**
    * Content-refusal handling. When `autoRewind` is on, a `stop_reason: refusal`
    * turn triggers an automatic rewind of the triggering turn + retry (keeping
@@ -262,13 +363,21 @@ export interface RecipeMcpServer {
 
 /**
  * How to obtain and install an MCP server at deploy time.  Consumed by
- * build tooling like connectome-cook.  All fields optional-at-the-schema-
- * layer except `url`; tools may require more depending on the install
- * pattern they're generating.
+ * build tooling like connectome-cook.  Exactly one of `url` (git form) or
+ * `npm` (registry form) must be set; tools may require more depending on
+ * the install pattern they're generating.
  */
 export interface RecipeMcpServerSource {
-  /** Git URL to clone from. */
-  url: string;
+  /** Git URL to clone from. Mutually exclusive with `npm`. */
+  url?: string;
+  /**
+   * npm registry package spec (`pkg@version` / `@scope/pkg@version`) that
+   * build tooling bakes via a global install instead of a git clone —
+   * matches connectome-cook's `source.npm` grammar.  The git-form fields
+   * (`ref`, `install`, `inContainer`, ...) don't apply.  Mutually
+   * exclusive with `url`.
+   */
+  npm?: string;
   /**
    * Git ref: branch, tag, or commit SHA.  Default: "main".
    * If the value starts with "refs/" (e.g. "refs/pull/3/head"), it's
@@ -383,8 +492,9 @@ export interface RecipeCredentialFileField {
 
 /**
  * Subset of MountConfig exposed to recipes.
- * Intentionally omits watchDebounceMs, followSymlinks, and maxFileSize —
- * these are implementation details best left to framework defaults.
+ * Intentionally omits watchDebounceMs and followSymlinks. The maximum file
+ * size is operator-configurable because binary service artifacts may
+ * legitimately exceed the conservative framework default.
  */
 export interface RecipeWorkspaceMount {
   name: string;
@@ -392,6 +502,8 @@ export interface RecipeWorkspaceMount {
   mode?: 'read-write' | 'read-only';
   watch?: 'always' | 'on-agent-action' | 'never';
   ignore?: string[];
+  /** Maximum file size in bytes (defaults to the framework's 5 MiB limit). */
+  maxFileSize?: number;
   /**
    * Request inference when files in this mount change. Pair with
    * `watch: 'always'` so chokidar actually observes the mount.
@@ -421,12 +533,67 @@ export interface RecipeModules {
   /**
    * Lesson retrieval-injection (requires `lessons`). OPT-IN — defaults to off
    * and is deliberately not part of the standard recipe: it injects
-   * context-dependent content into every compile and spends two Haiku calls
-   * per turn. Enable only for agents that actually curate a lesson library.
+   * context-dependent content into every compile and spends up to two
+   * configured retrieval-model calls. Enable only for agents that actually
+   * curate a lesson library.
    */
-  retrieval?: boolean | { model?: string; maxInjected?: number };
+  retrieval?: boolean | {
+    model?: string;
+    maxInjected?: number;
+    /**
+     * Optional OpenAI Responses/Codex reasoning effort for both retrieval calls.
+     * Requires an explicit retrieval model.
+     */
+    reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+  };
   wake?: boolean | import('@animalabs/agent-framework').GateConfig;
   workspace?: boolean | { mounts: RecipeWorkspaceMount[]; configMount?: boolean };
+  /**
+   * Shared operating instructions. OPT-IN — off by default. Reads a living
+   * instructions document (a CLAUDE.md analogue maintained in a workspace
+   * mount) and injects its current content into EVERY agent's context on
+   * EVERY turn — the resident agent and all ephemeral subagents — via the
+   * gatherContext hook. Injections are per-turn overlays (not persisted to
+   * Chronicle), so edits to the file take effect on the next turn.
+   *
+   * Requires `workspace` (the path below is a workspace mount path);
+   * enabling this alongside `workspace: false` fails validation. The mount
+   * named by the path is cross-checked at load time in every configuration
+   * (explicit mounts and the implicit "input"+"products" default alike), so
+   * a path naming a nonexistent mount is a load error, never a silent
+   * no-injection. A read-write instructions mount must also set
+   * `autoMaterialize: true`: workspace writes are Chronicle-first and the
+   * injection reads disk, so without materialization an agent's own
+   * curation edits would never reach the injection. A read-only mount is
+   * the alternative when the file is maintained outside the agent (edits
+   * then propagate to the injection but not to `workspace--read`, which
+   * serves Chronicle). A missing FILE remains fail-open at runtime: no
+   * injection, warn once.
+   *
+   * Cache economics: with position 'system' the injected block sits in the
+   * prompt-cache prefix of every agent, so each EDIT to the file is a
+   * fleet-wide cache cold start on the next turn (steady state between
+   * edits caches normally). Curate in batches rather than per-message;
+   * 'afterUser' is the cache-cheap, lower-salience alternative.
+   */
+  instructions?: boolean | {
+    /** Workspace path "<mountName>/<relativePath>". Default "instructions/AGENTS.md". */
+    path?: string;
+    /**
+     * Heading line prepended to the injected block.
+     * Default "# Shared operating instructions (live document)".
+     */
+    header?: string;
+    /**
+     * Truncate content beyond this many bytes, appending a
+     * "[truncated: first N of M bytes]" marker (N may sit up to 3 bytes
+     * under the cap when a multibyte character straddles it). At most this
+     * many bytes are ever read from disk. Default 32768.
+     */
+    maxBytes?: number;
+    /** Where the block lands: 'system' (default) | 'beforeUser' | 'afterUser'. */
+    position?: 'system' | 'beforeUser' | 'afterUser';
+  };
   /**
    * Surface agent composition activity (typing indicators) to one or more
    * MCPL channels while inference is active. Opt-in per recipe; channel IDs
@@ -685,6 +852,41 @@ export interface RecipeCodeExecution {
   idleReclaimMs?: number;
 }
 
+/**
+ * Per-channel conversation routing (agent-framework ConversationRouter):
+ * the recipe's agent becomes a dormant "trunk" template, and qualifying
+ * incoming channel messages spawn per-channel fork agents seeded from the
+ * trunk's current context. The host fills in what the framework needs but a
+ * recipe can't say: `templateAgent` is always the recipe's own agent, and
+ * `strategyFactory` builds a fresh instance of the recipe's `agent.strategy`
+ * per fork (strategy instances are stateful and must never be shared).
+ */
+export interface RecipeConversations {
+  /** When an unbound channel acquires a fork.
+   * Defaults: dm 'always', groupDm 'always', channel 'mention'. */
+  bind?: {
+    dm?: 'always' | 'mention' | 'never';
+    groupDm?: 'always' | 'mention' | 'never';
+    channel?: 'always' | 'mention' | 'never';
+  };
+  /** When a message on a bound channel triggers inference (it always lands
+   * in the fork's context regardless).
+   * Defaults: dm 'always', groupDm 'mention', channel 'mention'. */
+  trigger?: {
+    dm?: 'always' | 'mention';
+    groupDm?: 'always' | 'mention';
+    channel?: 'always' | 'mention';
+  };
+  /** Idle time before a binding expires and the fork runs its closure turn.
+   * Default 12h. */
+  idleTtlMs?: number;
+  /** Final system-initiated user message sent to a fork on expiry. */
+  closurePrompt?: string;
+  /** Prefix for generated fork agent names (default 'conversation'). Also
+   * the Chronicle namespace segment, so it is restricted to [A-Za-z0-9_-]. */
+  agentPrefix?: string;
+}
+
 export interface Recipe {
   name: string;
   description?: string;
@@ -697,6 +899,8 @@ export interface Recipe {
   sessionNaming?: { examples?: string[] };
   /** Client-side programmatic tool calling (code_execution tool). */
   codeExecution?: RecipeCodeExecution;
+  /** Per-channel conversation routing — fork-per-channel from this agent. */
+  conversations?: RecipeConversations;
 }
 
 // ---------------------------------------------------------------------------
@@ -718,7 +922,7 @@ export const DEFAULT_RECIPE: Recipe = {
   },
   modules: {
     // subagents + lessons + retrieval deliberately omitted — all opt-in only
-    // (retrieval additionally adds per-turn context churn + Haiku costs);
+    // (retrieval additionally adds per-turn context churn + retrieval-model costs);
     // see the RecipeModules field docs.
     wake: true,
     workspace: true,
@@ -798,6 +1002,27 @@ export function substituteEnvVars(value: unknown, source: string): unknown {
  */
 type RecipeSourceBase = { kind: 'file'; dir: string } | { kind: 'url'; base: string };
 
+/**
+ * A loaded recipe plus the form of it that is safe to persist.
+ *
+ * `recipe` is fully resolved: `${VAR}` env references substituted, relative
+ * child/extension paths made absolute, URL systemPrompt fetched. It is what
+ * the running host consumes — and it can contain secrets (API tokens pulled
+ * from the environment), so it must never be written to disk.
+ *
+ * `persistable` is the raw pre-substitution recipe JSON with only the
+ * source-relative paths (`modules.fleet.children[].recipe`,
+ * `extensions[*].path`) resolved to their final absolute form — those need
+ * the original source base, which a resumed session no longer has. Every
+ * `${VAR}` reference and any URL systemPrompt stay unresolved, so the file
+ * `saveRecipe` writes carries no secret material and re-resolves against the
+ * *current* environment on resume.
+ */
+export interface LoadedRecipe {
+  recipe: Recipe;
+  persistable: Record<string, unknown>;
+}
+
 /**
  * Load a recipe from a URL or local file path.
  * If the systemPrompt value is an HTTP(S) URL, fetches the text.
@@ -807,6 +1032,15 @@ type RecipeSourceBase = { kind: 'file'; dir: string } | { kind: 'url'; base: str
  * parent recipe's directory (or URL base) so sibling recipes are portable.
  */
 export async function loadRecipe(source: string): Promise<Recipe> {
+  return (await loadRecipeDetailed(source)).recipe;
+}
+
+/**
+ * Like loadRecipe, but also returns the persistable (unresolved) form —
+ * see LoadedRecipe. Callers that snapshot the recipe to disk (index.ts's
+ * resolveRecipe) must save `persistable`, never `recipe`.
+ */
+export async function loadRecipeDetailed(source: string): Promise<LoadedRecipe> {
   let raw: unknown;
   let sourceBase: RecipeSourceBase;
 
@@ -822,11 +1056,54 @@ export async function loadRecipe(source: string): Promise<Recipe> {
     sourceBase = { kind: 'file', dir: dirname(path) };
   }
 
+  // Snapshot the pre-substitution form before substituteEnvVars walks the
+  // object — this is what gets persisted, so resolved secrets never do.
+  const persistable = structuredClone(raw) as Record<string, unknown>;
+
   raw = substituteEnvVars(raw, source);
   const recipe = validateRecipe(raw);
   resolveChildRecipePaths(recipe, sourceBase);
   resolveExtensionPaths(recipe, sourceBase);
-  return resolveSystemPrompt(recipe);
+  const resolved = await resolveSystemPrompt(recipe);
+  copyResolvedPathsIntoRaw(persistable, resolved);
+  return { recipe: resolved, persistable };
+}
+
+/**
+ * Copy the resolved `modules.fleet.children[].recipe` and
+ * `extensions[*].path` values from the resolved recipe into the raw
+ * pre-substitution snapshot. Those fields are resolved against the recipe's
+ * original source base (its directory or URL), which is gone by resume time
+ * — so the persisted form must carry them already-absolute. Substitution
+ * never changes object shape (it is a per-string replacement), so the two
+ * trees align index-for-index and key-for-key. Paths are not treated as
+ * secret: an env value that was interpolated into a child-recipe or
+ * extension path IS persisted in resolved form.
+ */
+function copyResolvedPathsIntoRaw(raw: Record<string, unknown>, recipe: Recipe): void {
+  const fleet = recipe.modules?.fleet;
+  const resolvedChildren = (typeof fleet === 'object' && fleet !== null) ? fleet.children : undefined;
+  if (Array.isArray(resolvedChildren)) {
+    const rawModules = raw.modules as Record<string, unknown> | undefined;
+    const rawFleet = rawModules?.fleet as Record<string, unknown> | undefined;
+    const rawChildren = (typeof rawFleet === 'object' && rawFleet !== null) ? rawFleet.children : undefined;
+    if (Array.isArray(rawChildren)) {
+      for (let i = 0; i < rawChildren.length && i < resolvedChildren.length; i++) {
+        const rawChild = rawChildren[i] as Record<string, unknown> | null;
+        if (rawChild && typeof rawChild === 'object' && typeof resolvedChildren[i]?.recipe === 'string') {
+          rawChild.recipe = resolvedChildren[i].recipe;
+        }
+      }
+    }
+  }
+
+  const rawExtensions = raw.extensions as Record<string, unknown> | undefined;
+  for (const [name, ext] of Object.entries(recipe.extensions ?? {})) {
+    const rawExt = rawExtensions?.[name] as Record<string, unknown> | undefined;
+    if (rawExt && typeof rawExt === 'object') {
+      rawExt.path = ext.path;
+    }
+  }
 }
 
 /**
@@ -888,6 +1165,87 @@ async function resolveSystemPrompt(recipe: Recipe): Promise<Recipe> {
   return recipe;
 }
 
+function validateKvUnifiedConfig(strategy: Record<string, unknown>): void {
+  const selected = strategy.foldingStrategy === 'kv-unified';
+  const raw = strategy.kvUnified;
+  if (!selected) {
+    if (raw !== undefined) {
+      throw new Error('Recipe agent.strategy.kvUnified requires foldingStrategy "kv-unified".');
+    }
+    return;
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(
+      'Recipe foldingStrategy "kv-unified" requires a complete agent.strategy.kvUnified object; defaults are forbidden.',
+    );
+  }
+  const config = raw as Record<string, unknown>;
+  if (!config.policy || typeof config.policy !== 'object' || Array.isArray(config.policy)) {
+    throw new Error('Recipe agent.strategy.kvUnified.policy must be a complete object.');
+  }
+  const policy = config.policy as Record<string, unknown>;
+  const policyNumbers = [
+    'alpha', 'budgetLowRatio', 'budgetHighRatio', 'budgetUnderLambda',
+    'budgetOverLambda', 'cacheLambda', 'cacheScale', 'cacheReadPrice',
+    'cacheWritePrice', 'continuityLambda', 'continuityScale',
+    'continuityRecencyHalfLifeTokens', 'continuityRecencyFloor',
+    'continuityStableHalfLife', 'continuityStableFloor',
+  ] as const;
+  for (const key of policyNumbers) {
+    if (typeof policy[key] !== 'number' || !Number.isFinite(policy[key])) {
+      throw new Error(`Recipe agent.strategy.kvUnified.policy.${key} must be a finite number.`);
+    }
+  }
+  const nonNegative = [
+    'alpha', 'budgetUnderLambda', 'budgetOverLambda', 'cacheLambda',
+    'cacheReadPrice', 'cacheWritePrice', 'continuityLambda',
+  ] as const;
+  for (const key of nonNegative) {
+    if ((policy[key] as number) < 0) {
+      throw new Error(`Recipe agent.strategy.kvUnified.policy.${key} must be non-negative.`);
+    }
+  }
+  for (const key of [
+    'cacheScale', 'continuityScale', 'continuityRecencyHalfLifeTokens',
+    'continuityStableHalfLife',
+  ] as const) {
+    if ((policy[key] as number) <= 0) {
+      throw new Error(`Recipe agent.strategy.kvUnified.policy.${key} must be positive.`);
+    }
+  }
+  const low = policy.budgetLowRatio as number;
+  const high = policy.budgetHighRatio as number;
+  if (low < 0 || high > 1 || low > high) {
+    throw new Error('Recipe kvUnified budget ratios must satisfy 0 <= low <= high <= 1.');
+  }
+  for (const key of ['continuityRecencyFloor', 'continuityStableFloor'] as const) {
+    const value = policy[key] as number;
+    if (value < 0 || value > 1) {
+      throw new Error(`Recipe agent.strategy.kvUnified.policy.${key} must be in [0, 1].`);
+    }
+  }
+  for (const key of [
+    'tokenBucketSize', 'continuityBucketSize', 'fidelityBucketSize', 'labelCeiling',
+  ] as const) {
+    const value = config[key];
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+      throw new Error(`Recipe agent.strategy.kvUnified.${key} must be a positive safe integer.`);
+    }
+  }
+  if (
+    typeof config.adoptEpsilon !== 'number' ||
+    !Number.isFinite(config.adoptEpsilon) ||
+    config.adoptEpsilon < 0
+  ) {
+    throw new Error('Recipe agent.strategy.kvUnified.adoptEpsilon must be a finite non-negative number.');
+  }
+  if (typeof config.treeifyNonContiguousSummaries !== 'boolean') {
+    throw new Error(
+      'Recipe agent.strategy.kvUnified.treeifyNonContiguousSummaries must be an explicit boolean.',
+    );
+  }
+}
+
 /**
  * Validate raw JSON and fill defaults.
  */
@@ -903,8 +1261,13 @@ export function validateRecipe(raw: unknown): Recipe {
   }
 
   const agent = obj.agent as Record<string, unknown>;
-  if (typeof agent.systemPrompt !== 'string' || !agent.systemPrompt) {
-    throw new Error('Recipe agent must have a "systemPrompt" string');
+  // Absent or empty systemPrompt is a valid configuration: '' is dropped at
+  // the provider boundary (membrane omits falsy `system`), so the wire
+  // request carries no system block at all.
+  if (agent.systemPrompt === undefined || agent.systemPrompt === null) {
+    agent.systemPrompt = '';
+  } else if (typeof agent.systemPrompt !== 'string') {
+    throw new Error('Recipe agent "systemPrompt" must be a string when present');
   }
 
   if (agent.provider !== undefined &&
@@ -912,13 +1275,25 @@ export function validateRecipe(raw: unknown): Recipe {
       agent.provider !== 'openai-responses' &&
       agent.provider !== 'openai-codex' &&
       agent.provider !== 'openrouter' &&
-      agent.provider !== 'bedrock') {
+      agent.provider !== 'bedrock' &&
+      agent.provider !== 'openai-compatible' &&
+      agent.provider !== 'mock') {
     throw new Error(
-      `Recipe agent.provider must be 'anthropic', 'openai-responses', 'openai-codex', 'openrouter', or 'bedrock', ` +
+      `Recipe agent.provider must be 'anthropic', 'openai-responses', 'openai-codex', 'openrouter', 'bedrock', 'openai-compatible', or 'mock', ` +
       `got ${JSON.stringify(agent.provider)}.`,
     );
   }
 
+  if (
+    agent.proseRouting !== undefined &&
+    agent.proseRouting !== 'locus' &&
+    agent.proseRouting !== 'explicit' &&
+    agent.proseRouting !== 'hybrid' &&
+    agent.proseRouting !== 'disabled'
+  ) {
+    throw new Error(`Recipe agent.proseRouting must be 'locus', 'explicit', 'hybrid', or 'disabled', got ${JSON.stringify(agent.proseRouting)}.`);
+  }
+
   if (agent.timezone !== undefined) {
     if (typeof agent.timezone !== 'string' || !agent.timezone.trim()) {
       throw new Error('Recipe agent.timezone must be a non-empty IANA time zone string.');
@@ -965,6 +1340,20 @@ export function validateRecipe(raw: unknown): Recipe {
     }
   }
 
+  if (agent.mock !== undefined) {
+    if (!agent.mock || typeof agent.mock !== 'object' || Array.isArray(agent.mock)) {
+      throw new Error('Recipe agent.mock must be an object.');
+    }
+    const mock = agent.mock as Record<string, unknown>;
+    if (mock.echoMode !== undefined && typeof mock.echoMode !== 'boolean') {
+      throw new Error('Recipe agent.mock.echoMode must be a boolean.');
+    }
+    if (mock.defaultResponse !== undefined &&
+        (typeof mock.defaultResponse !== 'string' || !mock.defaultResponse.trim())) {
+      throw new Error('Recipe agent.mock.defaultResponse must be a non-empty string.');
+    }
+  }
+
   if (agent.maxStreamTokens !== undefined && (typeof agent.maxStreamTokens !== 'number' || agent.maxStreamTokens <= 0)) {
     throw new Error('Recipe agent.maxStreamTokens must be a positive number.');
   }
@@ -976,6 +1365,63 @@ export function validateRecipe(raw: unknown): Recipe {
   }
   agent.cacheTtl ??= '1h';
 
+  // openai-compatible: an endpoint the host knows nothing about, so the recipe
+  // must say where it is and which model to ask for. Fail at load time, not as
+  // a fetch to 'undefined/chat/completions' at first inference.
+  if (agent.provider === 'openai-compatible') {
+    if (typeof agent.baseUrl !== 'string' || !agent.baseUrl.trim()) {
+      throw new Error("Recipe agent.baseUrl is required when agent.provider is 'openai-compatible' (e.g. \"http://localhost:11434/v1\").");
+    }
+    let parsed: URL;
+    try {
+      parsed = new URL(agent.baseUrl);
+    } catch {
+      throw new Error(`Recipe agent.baseUrl must be an absolute http(s) URL, got ${JSON.stringify(agent.baseUrl)}.`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new Error(`Recipe agent.baseUrl must use http or https, got ${JSON.stringify(agent.baseUrl)}.`);
+    }
+    if (typeof agent.model !== 'string' || !agent.model.trim()) {
+      throw new Error("Recipe agent.model is required when agent.provider is 'openai-compatible' (no default model for an arbitrary endpoint).");
+    }
+  } else if (agent.baseUrl !== undefined) {
+    throw new Error(
+      `Recipe agent.baseUrl only applies to agent.provider 'openai-compatible' (got provider ${JSON.stringify(agent.provider ?? 'anthropic')}); ` +
+      'other providers take their endpoint from ANTHROPIC_BASE_URL / OPENAI_BASE_URL / BEDROCK_BASE_URL.',
+    );
+  }
+
+  // A keepalive that fires AFTER the entry has already expired is the worst of
+  // both worlds: it pays a full 2x cache write on every poke, forever, and
+  // reports success while doing it. Refuse the config rather than discover it
+  // in a bill. (The runtime also self-checks — see membrane cache-keepalive —
+  // but a typo'd recipe should never get that far.)
+  const keepalive = agent.cacheKeepalive;
+  if (keepalive !== undefined) {
+    if (typeof keepalive !== 'object' || keepalive === null) {
+      throw new Error(`Recipe agent.cacheKeepalive must be an object, got ${JSON.stringify(keepalive)}.`);
+    }
+    const { maxIdleHours, refreshAfterMinutes } = keepalive as {
+      maxIdleHours?: unknown;
+      refreshAfterMinutes?: unknown;
+    };
+    if (refreshAfterMinutes !== undefined) {
+      if (typeof refreshAfterMinutes !== 'number' || !(refreshAfterMinutes > 0)) {
+        throw new Error(`Recipe agent.cacheKeepalive.refreshAfterMinutes must be a positive number, got ${JSON.stringify(refreshAfterMinutes)}.`);
+      }
+      const ttlMinutes = agent.cacheTtl === '1h' ? 60 : 5;
+      if (refreshAfterMinutes >= ttlMinutes) {
+        throw new Error(
+          `Recipe agent.cacheKeepalive.refreshAfterMinutes (${refreshAfterMinutes}) must be less than the ${agent.cacheTtl} cache TTL (${ttlMinutes}m), ` +
+          'or every keepalive would land after the entry expired and pay a full cache write instead of a read.',
+        );
+      }
+    }
+    if (maxIdleHours !== undefined && (typeof maxIdleHours !== 'number' || !(maxIdleHours > 0))) {
+      throw new Error(`Recipe agent.cacheKeepalive.maxIdleHours must be a positive number, got ${JSON.stringify(maxIdleHours)}.`);
+    }
+  }
+
   if (agent.promptCaching !== undefined && typeof agent.promptCaching !== 'boolean') {
     throw new Error(
       `Recipe agent.promptCaching must be a boolean, got ${JSON.stringify(agent.promptCaching)}.`,
@@ -1069,6 +1515,21 @@ export function validateRecipe(raw: unknown): Recipe {
         `recipe's "extensions" block (none is declared).`,
       );
     }
+    if (
+      strategy.foldingStrategy !== undefined &&
+      strategy.foldingStrategy !== 'flat-profile' &&
+      strategy.foldingStrategy !== 'oldest-first' &&
+      strategy.foldingStrategy !== 'kv-stable' &&
+      strategy.foldingStrategy !== 'kv-unified'
+    ) {
+      throw new Error(
+        `Recipe agent.strategy.foldingStrategy is invalid: ${JSON.stringify(strategy.foldingStrategy)}.`,
+      );
+    }
+    if (strategy.foldingStrategy === 'kv-unified' && strategy.type === 'passthrough') {
+      throw new Error('Recipe foldingStrategy "kv-unified" requires an autobiographical or frontdesk strategy.');
+    }
+    validateKvUnifiedConfig(strategy);
     if (
       strategy.compressionRefusalCurveFallbacks !== undefined
       && (
@@ -1089,6 +1550,26 @@ export function validateRecipe(raw: unknown): Recipe {
     ) {
       throw new Error('Recipe agent.strategy.compressionContextBudgetTokens must be a positive safe integer.');
     }
+    for (const key of [
+      'compressionSourceOnly',
+      'compressionSourceOnlyFallback',
+      'compressionMergeSourceOnly',
+      'compressionMergeSourceOnlyFallback',
+    ] as const) {
+      if (strategy[key] !== undefined && typeof strategy[key] !== 'boolean') {
+        throw new Error(`Recipe agent.strategy.${key} must be a boolean.`);
+      }
+    }
+    if (
+      strategy.compressionRecallBudgetTokens !== undefined
+      && (
+        typeof strategy.compressionRecallBudgetTokens !== 'number'
+        || !Number.isSafeInteger(strategy.compressionRecallBudgetTokens)
+        || strategy.compressionRecallBudgetTokens <= 0
+      )
+    ) {
+      throw new Error('Recipe agent.strategy.compressionRecallBudgetTokens must be a positive safe integer.');
+    }
   }
 
   const refusalHandling = agent.refusalHandling as Record<string, unknown> | undefined;
@@ -1116,8 +1597,16 @@ export function validateRecipe(raw: unknown): Recipe {
           throw new Error(`mcpServers.${id}.source must be an object`);
         }
         const src = server.source as Record<string, unknown>;
-        if (typeof src.url !== 'string' || !src.url) {
-          throw new Error(`mcpServers.${id}.source.url must be a non-empty string`);
+        const hasSrcUrl = typeof src.url === 'string' && src.url;
+        const hasSrcNpm = typeof src.npm === 'string' && src.npm;
+        if (hasSrcUrl && hasSrcNpm) {
+          throw new Error(`mcpServers.${id}.source must not set both "url" and "npm"`);
+        }
+        if (!hasSrcUrl && !hasSrcNpm) {
+          throw new Error(
+            `mcpServers.${id}.source must have a non-empty "url" (git clone) ` +
+            `or "npm" (registry package spec) string`,
+          );
         }
         if (src.ref !== undefined && typeof src.ref !== 'string') {
           throw new Error(`mcpServers.${id}.source.ref must be a string`);
@@ -1255,6 +1744,159 @@ export function validateRecipe(raw: unknown): Recipe {
       }
     }
 
+    // Validate instructions if present. It reads through a workspace mount,
+    // so pairing it with `workspace: false` is a config contradiction — fail
+    // at load, not with a silent no-injection at runtime.
+    if (mods.instructions !== undefined && mods.instructions !== false) {
+      if (mods.instructions !== true
+          && (typeof mods.instructions !== 'object' || Array.isArray(mods.instructions))) {
+        throw new Error('modules.instructions must be a boolean or object');
+      }
+      if (mods.workspace === false) {
+        throw new Error(
+          'modules.instructions requires modules.workspace: the instructions file is ' +
+          'read through a workspace mount, but this recipe sets workspace: false.',
+        );
+      }
+      if (typeof mods.instructions === 'object') {
+        const ins = mods.instructions as Record<string, unknown>;
+        const allowedInstructionKeys = new Set(['path', 'header', 'maxBytes', 'position']);
+        for (const key of Object.keys(ins)) {
+          if (!allowedInstructionKeys.has(key)) {
+            throw new Error(
+              `modules.instructions has unknown field ${JSON.stringify(key)} ` +
+              `(expected one of: ${[...allowedInstructionKeys].join(', ')}).`,
+            );
+          }
+        }
+        if (ins.path !== undefined) {
+          if (typeof ins.path !== 'string' || !ins.path.trim()) {
+            throw new Error('modules.instructions.path must be a non-empty string');
+          }
+          const slashIdx = ins.path.indexOf('/');
+          if (slashIdx <= 0 || slashIdx === ins.path.length - 1) {
+            throw new Error(
+              'modules.instructions.path must be a workspace path of the form ' +
+              `"<mountName>/<relativePath>", got ${JSON.stringify(ins.path)}.`,
+            );
+          }
+        }
+        if (ins.header !== undefined && typeof ins.header !== 'string') {
+          throw new Error('modules.instructions.header must be a string');
+        }
+        if (ins.maxBytes !== undefined
+            && (typeof ins.maxBytes !== 'number' || !Number.isInteger(ins.maxBytes) || ins.maxBytes <= 0)) {
+          throw new Error('modules.instructions.maxBytes must be a positive integer');
+        }
+        if (ins.position !== undefined
+            && ins.position !== 'system' && ins.position !== 'beforeUser' && ins.position !== 'afterUser') {
+          throw new Error(
+            `modules.instructions.position must be 'system', 'beforeUser', or 'afterUser', ` +
+            `got ${JSON.stringify(ins.position)}.`,
+          );
+        }
+      }
+
+      // The mount the instructions path names is knowable at load time in
+      // EVERY configuration — explicit mounts from the declaration, the
+      // implicit default workspace from the fixed input/products pair the
+      // host builds — so a typo, the default "instructions/…" path with no
+      // matching mount, or `instructions: true` on the implicit workspace
+      // (whose mount set can never contain "instructions") all fail here
+      // instead of as a silent no-injection at runtime.
+      //
+      // A read-write instructions mount additionally requires
+      // autoMaterialize: workspace write/edit are Chronicle-first and reach
+      // disk only when the mount materializes, while this module reads disk
+      // — without it, an agent's own curation edits would never appear in
+      // the injection (and its workspace read would show the new content,
+      // hiding the drift entirely). Read-only mounts are exempt: disk is
+      // their only write path.
+      {
+        const effectivePath =
+          typeof mods.instructions === 'object'
+              && typeof (mods.instructions as { path?: unknown }).path === 'string'
+            ? (mods.instructions as { path: string }).path
+            : 'instructions/AGENTS.md'; // keep in sync with DEFAULT_INSTRUCTIONS_PATH
+        const mountName = effectivePath.slice(0, effectivePath.indexOf('/'));
+        // Reason over the SAME mount construction the runtime uses — one
+        // builder, no validator-vs-host drift (the storePath placeholder is
+        // irrelevant here; only names/modes/flags are consulted).
+        const declaredExplicitly =
+          !!mods.workspace && typeof mods.workspace === 'object' &&
+          !!(mods.workspace as { mounts?: unknown }).mounts;
+        const effectiveMounts =
+          buildWorkspaceMounts(mods.workspace as RecipeModules['workspace'], '.') ?? [];
+        const match = effectiveMounts.find((m) => m.name === mountName);
+        if (!match) {
+          throw new Error(
+            `modules.instructions.path ${JSON.stringify(effectivePath)} names workspace mount ` +
+            `${JSON.stringify(mountName)}, but the ${declaredExplicitly ? 'declared' : 'implicit default'} ` +
+            `mounts are: ${effectiveMounts.map((m) => JSON.stringify(m.name)).join(', ')}. ` +
+            `(The default path "instructions/AGENTS.md" requires a workspace mount named ` +
+            `"instructions" — declare one under modules.workspace.mounts.)`,
+          );
+        }
+        if (match.name === '_config') {
+          throw new Error(
+            `modules.instructions.path ${JSON.stringify(effectivePath)} reads through the ` +
+            `host-managed "_config" mount, which does NOT auto-materialize: agent edits stay ` +
+            `Chronicle-side and only reach disk after branch-changing commands, so the ` +
+            `instructions injection would silently serve stale content. Use a dedicated ` +
+            `instructions mount instead.`,
+          );
+        }
+        if (match.mode !== 'read-only' && match.autoMaterialize !== true) {
+          throw new Error(
+            `modules.instructions.path ${JSON.stringify(effectivePath)} uses read-write mount ` +
+            `${JSON.stringify(mountName)} without autoMaterialize. Workspace writes are ` +
+            `Chronicle-first and reach disk only when the mount materializes, while the ` +
+            `instructions injection reads disk — agent edits to the file would silently never ` +
+            `take effect. Set autoMaterialize: true on the mount` +
+            `${declaredExplicitly ? '' : ' (the implicit default workspace cannot; declare explicit mounts)'}, ` +
+            `or make the mount read-only if the file is maintained outside the agent.`,
+          );
+        }
+      }
+    }
+
+    // Validate retrieval provider reasoning when configured.
+    const retrieval = mods.retrieval;
+    if (retrieval !== undefined && typeof retrieval !== 'boolean') {
+      if (!retrieval || typeof retrieval !== 'object' || Array.isArray(retrieval)) {
+        throw new Error('Recipe modules.retrieval must be a boolean or object.');
+      }
+      const retrievalConfig = retrieval as Record<string, unknown>;
+      if (retrievalConfig.reasoningContext !== undefined) {
+        throw new Error(
+          'modules.retrieval.reasoningContext is not supported: retrieval model calls ' +
+          'are independent one-shot requests with no earlier reasoning items.',
+        );
+      }
+      const efforts = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+      if (retrievalConfig.reasoningEffort !== undefined &&
+          (typeof retrievalConfig.reasoningEffort !== 'string'
+            || !efforts.includes(retrievalConfig.reasoningEffort))) {
+        throw new Error(`Invalid modules.retrieval.reasoningEffort ${JSON.stringify(retrievalConfig.reasoningEffort)}.`);
+      }
+      if (retrievalConfig.reasoningEffort !== undefined
+          && agent.provider !== 'openai-responses'
+          && agent.provider !== 'openai-codex') {
+        throw new Error(
+          'modules.retrieval.reasoningEffort requires agent.provider ' +
+          '"openai-responses" or "openai-codex".',
+        );
+      }
+      if (retrievalConfig.reasoningEffort !== undefined
+          && (typeof retrievalConfig.model !== 'string'
+            || !retrievalConfig.model.trim())) {
+        throw new Error(
+          'modules.retrieval.model must be a non-empty string when ' +
+          'modules.retrieval.reasoningEffort is configured.',
+        );
+      }
+    }
+
     // Validate ttsRelay if present — url + token are load-bearing, and a
     // recipe that names the module but can't reach a relay should fail at
     // load, not silently stream nowhere.
@@ -1349,6 +1991,62 @@ export function validateRecipe(raw: unknown): Recipe {
     }
   }
 
+  if (obj.conversations !== undefined) {
+    if (!obj.conversations || typeof obj.conversations !== 'object' || Array.isArray(obj.conversations)) {
+      throw new Error('Recipe conversations must be an object.');
+    }
+    const conv = obj.conversations as Record<string, unknown>;
+    const allowedConversationKeys = new Set(['bind', 'trigger', 'idleTtlMs', 'closurePrompt', 'agentPrefix']);
+    for (const key of Object.keys(conv)) {
+      if (!allowedConversationKeys.has(key)) {
+        throw new Error(
+          `Recipe conversations has unknown field ${JSON.stringify(key)} ` +
+          `(expected one of: ${[...allowedConversationKeys].join(', ')}).`,
+        );
+      }
+    }
+    const kinds = ['dm', 'groupDm', 'channel'] as const;
+    for (const [field, allowed] of [
+      ['bind', ['always', 'mention', 'never']],
+      ['trigger', ['always', 'mention']],
+    ] as Array<[string, string[]]>) {
+      const rules = conv[field];
+      if (rules === undefined) continue;
+      if (!rules || typeof rules !== 'object' || Array.isArray(rules)) {
+        throw new Error(`Recipe conversations.${field} must be an object.`);
+      }
+      for (const [kind, rule] of Object.entries(rules as Record<string, unknown>)) {
+        if (!(kinds as readonly string[]).includes(kind)) {
+          throw new Error(
+            `Recipe conversations.${field} has unknown channel kind ${JSON.stringify(kind)} ` +
+            `(expected one of: ${kinds.join(', ')}).`,
+          );
+        }
+        if (typeof rule !== 'string' || !allowed.includes(rule)) {
+          throw new Error(
+            `Recipe conversations.${field}.${kind} must be one of ${allowed.map(r => `'${r}'`).join(', ')}, ` +
+            `got ${JSON.stringify(rule)}.`,
+          );
+        }
+      }
+    }
+    if (conv.idleTtlMs !== undefined &&
+        (typeof conv.idleTtlMs !== 'number' || !Number.isFinite(conv.idleTtlMs) ||
+         !Number.isInteger(conv.idleTtlMs) || conv.idleTtlMs <= 0)) {
+      throw new Error('Recipe conversations.idleTtlMs must be a positive finite integer.');
+    }
+    if (conv.closurePrompt !== undefined && (typeof conv.closurePrompt !== 'string' || !conv.closurePrompt.trim())) {
+      throw new Error('Recipe conversations.closurePrompt must be a non-empty string.');
+    }
+    if (conv.agentPrefix !== undefined &&
+        (typeof conv.agentPrefix !== 'string' || !/^[A-Za-z0-9_-]+$/.test(conv.agentPrefix))) {
+      throw new Error(
+        'Recipe conversations.agentPrefix must be a non-empty string of [A-Za-z0-9_-] ' +
+        '(it names fork agents and their Chronicle namespaces).',
+      );
+    }
+  }
+
   return obj as unknown as Recipe;
 }
 
@@ -1360,20 +2058,80 @@ function savedRecipePath(dataDir: string): string {
   return resolve(dataDir, '.recipe.json');
 }
 
-export function saveRecipe(dataDir: string, recipe: Recipe): void {
+/**
+ * Marker key stamped into saved `.recipe.json` snapshots that were written in
+ * unresolved form (post-fix). Its presence tells loadSavedRecipe to run the
+ * full substitute-and-validate pipeline on read; its absence means a legacy
+ * snapshot saved fully resolved, which must be loaded verbatim — running
+ * substitution over legacy content could hard-fail on a literal `${...}`
+ * that survived in prose (e.g. a systemPrompt documenting env-var syntax).
+ */
+export const SAVED_RECIPE_UNRESOLVED_KEY = '$unresolved';
+
+/**
+ * Snapshot a recipe to `$DATA_DIR/.recipe.json` so a later run without a
+ * recipe argument resumes the same configuration.
+ *
+ * Pass the `persistable` half of loadRecipeDetailed(), NOT the resolved
+ * recipe: `$DATA_DIR` is typically host-mounted and backed up, so the file
+ * must never contain substituted secrets. The snapshot keeps `${VAR}`
+ * references (and any URL systemPrompt) unresolved; loadSavedRecipe
+ * re-resolves them against the environment current at resume time.
+ *
+ * The file is written 0600 and chmod'd to 0600 even when it already exists,
+ * as defense in depth for legacy resolved snapshots being overwritten.
+ */
+export function saveRecipe(dataDir: string, persistable: Record<string, unknown>): void {
   mkdirSync(dataDir, { recursive: true });
-  writeFileSync(savedRecipePath(dataDir), JSON.stringify(recipe, null, 2) + '\n', 'utf-8');
+  const path = savedRecipePath(dataDir);
+  const withMarker = { [SAVED_RECIPE_UNRESOLVED_KEY]: true, ...persistable };
+  writeFileSync(path, JSON.stringify(withMarker, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+  // writeFileSync's mode only applies on creation — enforce on overwrite too.
+  chmodSync(path, 0o600);
 }
 
-export function loadSavedRecipe(dataDir: string): Recipe | null {
+/**
+ * Load the `.recipe.json` snapshot for a resumed session, or null when there
+ * is none (or it is unreadable/invalid).
+ *
+ * Snapshots carrying SAVED_RECIPE_UNRESOLVED_KEY are re-resolved through the
+ * same pipeline loadRecipe uses — env substitution (so rotated secrets take
+ * effect on restart), validation, and URL systemPrompt fetch. A missing
+ * required `${VAR}` THROWS rather than returning null: silently falling back
+ * to the default recipe would start a misconfigured agent, and the loud
+ * failure names the variable to restore. A failed systemPrompt fetch throws
+ * for the same reason.
+ *
+ * Legacy snapshots (no marker — saved fully resolved by older versions) are
+ * validated and returned verbatim, exactly as before: no substitution, so a
+ * literal `${...}` that survived resolution in prose cannot fail the load.
+ */
+export async function loadSavedRecipe(dataDir: string): Promise<Recipe | null> {
   const path = savedRecipePath(dataDir);
   if (!existsSync(path)) return null;
+  let raw: unknown;
   try {
-    const raw = JSON.parse(readFileSync(path, 'utf-8'));
-    return validateRecipe(raw);
+    raw = JSON.parse(readFileSync(path, 'utf-8'));
   } catch {
     return null;
   }
+
+  if (!raw || typeof raw !== 'object' || !(SAVED_RECIPE_UNRESOLVED_KEY in raw)) {
+    // Legacy resolved snapshot: load verbatim (no substitution).
+    try {
+      return validateRecipe(raw);
+    } catch {
+      return null;
+    }
+  }
+
+  const { [SAVED_RECIPE_UNRESOLVED_KEY]: _marker, ...unresolved } = raw as Record<string, unknown>;
+  // Deliberately outside a try/catch: substitution and validation errors on
+  // a snapshot we wrote ourselves are actionable operator errors (a rotated
+  // secret removed from the environment), not corruption to shrug off.
+  const substituted = substituteEnvVars(unresolved, path);
+  const recipe = validateRecipe(substituted);
+  return resolveSystemPrompt(recipe);
 }
 
 export function clearSavedRecipe(dataDir: string): void {