@frontera-sdk/cli 1.52.42 → 1.52.44

package/src/local/local-dev-references.ts

@@ -875,7 +875,8 @@ async function localModels(local: { serviceUrl: string; creds: LocalCredentials
  * A knowledge base: created when the runtime has none by its name, given the
  * file's settings (retrieval mode, chunking, top-K and threshold, hybrid
  * search and reranking, extraction and OCR), then the folder's documents the
- * base does not hold yet are uploaded.
+ * base does not hold yet are uploaded, and those edited here since are
+ * uploaded again in place of the runtime's older copy.
  */
 /**
  * What to say of a knowledge base with no documents in its folder: an Agent
@@ -987,7 +988,7 @@ export async function applyKnowledge(
     return await done({ ok: true, output: '' })
   }
   const sources = await run(['knowledge', 'sources', name, '--json', ...p])
-  const listedSources = parseJson<Array<{ id?: string; fileName?: string; folderId?: string | null; status?: string; updatedAt?: string }>>(sources.output) ?? []
+  const listedSources = parseJson<Array<{ id?: string; fileName?: string; folderId?: string | null; status?: string; updatedAt?: string; sizeBytes?: number | null }>>(sources.output) ?? []
   const key = local?.creds.workspaceKey
   const http = async (method: string, path: string, body?: FormData | Record<string, unknown>) => {
     const res = await fetch(new URL(path, local!.serviceUrl), {
@@ -1008,15 +1009,54 @@ export async function applyKnowledge(
   // A document the runtime holds pending or processing with no ingestion behind it (a rollback took its
   // reading with the database it replaced) is queued to be read again: uploading it again would add a second.
   if (key && id) notes.push(...(await requeueStuckDocuments(project, local!, name, id, listedSources)))
-  const fresh = documents.filter((f) => !have.has(f))
-  if (!fresh.length) return await done({ ok: true, output: '' })
+  // A document edited in place keeps its name: the runtime's older copy is found by content, uploaded over, then taken off.
+  const { loadUploadedDocuments, saveUploadedDocuments, staleDocuments } = await import('./local-knowledge-uploads')
+  const { sha256Of } = await import('./local-knowledge-documents')
+  const contents = documents.flatMap((path) => {
+    try {
+      const bytes = readFileSync(join(project.root, dirname(target.file), path))
+      return [{ path, sha256: sha256Of(bytes), bytes: bytes.byteLength }]
+    } catch {
+      return []
+    }
+  })
+  const onRuntime = listedSources.flatMap((s) => (s.id ? [{ id: s.id, path: documentPath(s.folderId ? folders.get(s.folderId) : null, s.fileName ?? ''), sizeBytes: s.sizeBytes }] : []))
+  const uploaded = key && id ? loadUploadedDocuments(project.stateDir, local!.creds.organizationId, id) : {}
+  const stale = staleDocuments(contents, onRuntime, uploaded)
+  if (stale.length && (!key || !id)) {
+    notes.push(`  warning: Knowledge base ${name}: ${stale.map((s) => s.path).join(', ')} changed here, but the runtime keeps ${stale.length === 1 ? 'its older copy' : 'their older copies'} until it has a workspace key`)
+  }
+  const replacing = key && id ? stale : []
+  // What the runtime now holds for each document, recorded so the next apply tells an edit from no change.
+  const record = async () => {
+    if (!key || !id) return
+    const now = rows<{ id?: string; fileName?: string; folderId?: string | null; createdAt?: string }>(await http('GET', `/v1/workspace-knowledge/${encodeURIComponent(id)}/sources`).catch(() => null))
+    // Folders this apply made are not in `folders` yet.
+    const filedNow = now.some((s) => s.folderId && !folders.has(s.folderId))
+      ? folderPaths((((await http('GET', `/v1/workspace-knowledge/${encodeURIComponent(id)}/folders`).catch(() => null))?.folders ?? []) as Array<{ id: string; parentId?: string | null; name: string }>))
+      : folders
+    const next: typeof uploaded = {}
+    for (const doc of contents) {
+      const copies = now.filter((s) => s.id && documentPath(s.folderId ? filedNow.get(s.folderId) : null, s.fileName ?? '') === doc.path)
+      const newest = copies.sort((a, b) => String(b.createdAt ?? '').localeCompare(String(a.createdAt ?? '')))[0]
+      if (newest?.id) next[doc.path] = { sourceId: newest.id, sha256: doc.sha256 }
+    }
+    saveUploadedDocuments(project.stateDir, local!.creds.organizationId, id, next)
+  }
+  const fresh = [...documents.filter((f) => !have.has(f)), ...replacing.map((s) => s.path)]
+  if (!fresh.length) {
+    await record()
+    return await done({ ok: true, output: '' })
+  }
   const top = fresh.filter((f) => !f.includes('/'))
   const filed = fresh.filter((f) => f.includes('/'))
   const lines: string[] = []
+  const sent = new Set<string>()
   if (top.length) {
-    const uploaded = await run(['knowledge', 'upload', name, ...top.map((f) => join(dirname(target.file), f)), ...p])
-    if (!uploaded.ok) return await done(uploaded)
-    if (uploaded.output.trim()) lines.push(uploaded.output.trim())
+    const uploadedTop = await run(['knowledge', 'upload', name, ...top.map((f) => join(dirname(target.file), f)), ...p])
+    if (!uploadedTop.ok) return await done(uploadedTop)
+    if (uploadedTop.output.trim()) lines.push(uploadedTop.output.trim())
+    for (const f of top) sent.add(f)
   }
   if (filed.length && (!key || !id)) {
     notes.push(`  warning: Knowledge base ${name}: ${filed.length} document${filed.length === 1 ? ' in a folder waits' : 's in folders wait'} until the runtime has a workspace key`)
@@ -1048,11 +1088,23 @@ export async function applyKnowledge(
         form.append('folderId', await folderFor(folder!))
         await http('POST', `/v1/workspace-knowledge/${encodeURIComponent(id!)}/sources`, form)
         lines.push(`  uploaded ${path}`)
+        sent.add(path)
       } catch (err) {
         notes.push(`  warning: Knowledge base ${name}: ${path} wasn’t uploaded (${(err as Error).message})`)
       }
     }
   }
+  // The older copies come off only once the new content is up, so the base is never without the document.
+  for (const doc of replacing) {
+    if (!sent.has(doc.path)) continue
+    try {
+      for (const sourceId of doc.replaces) await http('DELETE', `/v1/workspace-knowledge/${encodeURIComponent(id!)}/sources/${encodeURIComponent(sourceId)}`)
+      lines.push(`  replaced ${doc.path}: it changed here`)
+    } catch (err) {
+      notes.push(`  warning: Knowledge base ${name}: ${doc.path}’s older copy wasn’t taken off (${(err as Error).message}); search may find both`)
+    }
+  }
+  await record()
   return await done({ ok: true, output: lines.join('\n') })
 }
 

package/src/local/local-env.ts

@@ -118,6 +118,21 @@ export const SERVICE_OUTBOUND = [
   'AUTOMATION_RUNNER_URL',
 ] as const
 
+/** The service's settings for a hosted key custodian (OpenBao / Vault transit), blanked on the local runtime. */
+export const KEY_CUSTODIAN_SETTINGS = [
+  'BAO_ADDR',
+  'BAO_TOKEN',
+  'BAO_CACERT',
+  'VAULT_ADDR',
+  'VAULT_TOKEN',
+  'SECRETS_TRANSIT_AUTH',
+  'SECRETS_TRANSIT_MOUNT',
+  'SECRETS_TRANSIT_KEY',
+  'SECRETS_TRANSIT_K8S_ROLE',
+  'SECRETS_TRANSIT_K8S_MOUNT',
+  'SECRETS_TRANSIT_K8S_TOKEN_FILE',
+] as const
+
 /** What the Function runner dials on this machine. */
 export const RUNNER_OUTBOUND = ['SERVICE_URL', 'S3_ENDPOINT', 'INNGEST_BASE_URL'] as const
 
@@ -182,6 +197,12 @@ export function serviceEnv(args: {
     DAYTONA_API_KEY: '',
     DAYTONA_API_URL: '',
     DAYTONA_TARGET: '',
+    // The runtime holds its own keys: ENCRYPTION_KEY from its secrets.json wraps every data key.
+    // A checkout's .env can name a hosted OpenBao instead (the service loads it from its
+    // directory), and every data key wrapped there is unreadable once that OpenBao goes away.
+    // Empty values win over the file.
+    SECRETS_KEY_PROVIDER: 'env',
+    ...Object.fromEntries(KEY_CUSTODIAN_SETTINGS.map((key) => [key, ''])),
     // Traces go to the runtime's own local traces, read back by Studio.
     LANGFUSE_BASE_URL: `http://127.0.0.1:${ports.traces}`,
     LANGFUSE_PUBLIC_KEY: LOCAL_TRACE_KEYS.publicKey,

package/src/local/local-history-carry.ts

@@ -0,0 +1,103 @@
+import { randomBytes } from 'node:crypto'
+
+import { POSTGRES_DB, POSTGRES_USER } from './local-env'
+import type { QueryFn } from './local-secret-carry'
+
+/**
+ * The run history carried across a database restore.
+ *
+ * A restore (`local check`'s rollback, `frontera local snapshot restore`)
+ * throws away what was written since the baseline. What happened is not test
+ * data: the conversations (an Agent test case's included), Agent sessions and
+ * runs, workflow and Function runs and evaluation runs are how a change is
+ * compared with the one before it. So a restore keeps them as they are now,
+ * unless asked for the baseline's (`--exact`). The records those runs wrote
+ * are still rolled back.
+ *
+ * The rows are dumped inside the database container before the database is
+ * dropped (`pg_dump --data-only --inserts --on-conflict-do-nothing`), then
+ * loaded into the restored one, a row a statement: a row the baseline holds
+ * stays as the baseline holds it, and a row that names something the restore
+ * took away (a work item a test made) is left out and counted. Nothing leaves
+ * the container, and the dump is removed once loaded.
+ */
+
+/** The tables that hold what happened, parents before children (pg_dump orders them by their keys too). */
+export const HISTORY_TABLES = [
+  'conversations',
+  'messages',
+  'message_feedback',
+  'conversation_labels',
+  'conversation_files',
+  'trace_annotations',
+  'session_handoffs',
+  'agent_sessions',
+  'agent_session_events',
+  'agent_session_analyses',
+  'agent_timeline_events',
+  'agent_exchanges',
+  'pi_runs',
+  'pi_run_events',
+  'pi_model_calls',
+  'workflow_runs',
+  'workflow_run_nodes',
+  'workflow_step_test_results',
+  'function_runs',
+  'function_run_steps',
+  'ctx_agent_turns',
+  'dataset_runs',
+  'dataset_run_items',
+  'knowledge_eval_runs',
+  'knowledge_eval_run_fixtures',
+  'scheduled_task_runs',
+  'agent_routine_runs',
+] as const
+
+/** The history dumped from the current database, waiting in the container for the restored one. */
+export interface HistoryHeld {
+  file: string
+  rows: number
+}
+
+export interface HistoryCarried {
+  ok: boolean
+  /** Rows dumped before the restore (those the baseline already held included). */
+  rows: number
+  /** Rows left out: they name something the restored database lacks. */
+  notKept: number
+  /** Why nothing was carried, when it failed. */
+  problem?: string
+}
+
+const sh = (script: string) => ['sh', '-c', script]
+
+/** Dump the history tables as they are now into a file in the container, or why it could not be. */
+export function dumpHistory(query: QueryFn, container: string): HistoryHeld | { problem: string } {
+  const file = `/tmp/frontera-history-${randomBytes(6).toString('hex')}.sql`
+  const tables = HISTORY_TABLES.map((t) => `-t public.${t}`).join(' ')
+  const res = query(container, sh(`pg_dump -U ${POSTGRES_USER} -d ${POSTGRES_DB} --data-only --inserts --on-conflict-do-nothing ${tables} -f ${file} || exit 1; grep -c '^INSERT INTO' ${file}; exit 0`))
+  const rows = Number.parseInt(res.out.trim().split('\n').pop() ?? '', 10)
+  if (!res.ok || !Number.isFinite(rows)) {
+    query(container, sh(`rm -f ${file}`))
+    return { problem: 'the run history could not be read' }
+  }
+  return { file, rows }
+}
+
+/** Load the dumped history into the restored database, then remove the dump. */
+export function loadHistory(query: QueryFn, container: string, held: HistoryHeld): HistoryCarried {
+  // No ON_ERROR_STOP: each row is its own statement, and one the restored database refuses is counted, not fatal.
+  const res = query(container, sh(`psql -U ${POSTGRES_USER} -d ${POSTGRES_DB} -q -f ${held.file} 2>&1 | grep -c 'ERROR:'; rm -f ${held.file}`))
+  const notKept = Number.parseInt(res.out.trim().split('\n').pop() ?? '', 10)
+  if (!res.ok || !Number.isFinite(notKept)) return { ok: false, rows: held.rows, notKept: 0, problem: 'the run history could not be written back' }
+  return { ok: true, rows: held.rows, notKept }
+}
+
+/** What a restore does with the run history, in words. */
+export function historyWords(history: (HistoryCarried & { mode: 'keep' }) | { mode: 'baseline' } | undefined): string {
+  if (!history) return ''
+  if (history.mode === 'baseline') return 'the run history is as the baseline holds it (--exact)'
+  if (!history.ok) return `the run history couldn’t be kept (${history.problem ?? 'unknown'}), so conversations and runs are as the baseline holds them`
+  const kept = 'kept the run history (conversations, runs and evaluations)'
+  return history.notKept ? `${kept}, except ${history.notKept} row${history.notKept === 1 ? '' : 's'} naming records the rollback took away` : kept
+}

package/src/local/local-key-custodian.ts

@@ -0,0 +1,64 @@
+import { withFix } from './fix-words'
+
+/**
+ * The local runtime's key custodian, as its service reports it on
+ * `/v1/health`: whether the keys that lock its secrets and governed Action
+ * records answer. A runtime holds its own keys (`serviceEnv` pins the env
+ * custodian); one whose data keys were wrapped by a hosted OpenBao it no
+ * longer reaches cannot read them again, so the only fix is a clean runtime.
+ * Read by `local start` (which refuses), `local status`, `local check` and
+ * Forge's Runtime page. The report carries categories and a count, never a
+ * key, token or address.
+ */
+
+export interface KeyCustodianReport {
+  state: 'ready' | 'failed' | 'none'
+  provider: 'env' | 'transit' | null
+  reason?: 'unreachable' | 'misconfigured' | 'unreadable-keys'
+  foreignKeys: number
+}
+
+/** What fixes a broken custodian: nothing else can unwrap those data keys. */
+export const KEY_CUSTODIAN_FIX = 'run `frontera local reset` for a clean runtime that holds its own keys (it wipes this runtime’s data)'
+
+/** How every custodian problem starts, so a failed start's error is recognised as one. */
+export const KEY_CUSTODIAN_LEAD = 'the runtime’s encryption keys can’t be read'
+
+/** The problem a report describes, with its fix; null when the keys answer (or the report is from a service that has none). */
+export function keyCustodianProblem(report: KeyCustodianReport | null | undefined): string | null {
+  if (!report) return null
+  const what = 'so its secrets and governed Action records can’t be read or saved'
+  if (report.foreignKeys > 0) {
+    const keys = report.foreignKeys === 1 ? '1 data key was' : `${report.foreignKeys} data keys were`
+    return withFix(`${KEY_CUSTODIAN_LEAD}: ${keys} locked by a key service it doesn’t hold (an OpenBao named in a checkout’s .env), ${what}`, KEY_CUSTODIAN_FIX)
+  }
+  if (report.state !== 'failed') return null
+  const why =
+    report.reason === 'unreachable'
+      ? 'its key service doesn’t answer'
+      : report.reason === 'unreadable-keys'
+        ? 'its stored data keys don’t open with the keys in .frontera/local/secrets.json'
+        : 'its key service is set up wrong'
+  return withFix(`${KEY_CUSTODIAN_LEAD}: ${why}, ${what}`, KEY_CUSTODIAN_FIX)
+}
+
+/** Whether a failed start's error is a custodian problem (its fix is a reset, not a restart). */
+export function isKeyCustodianProblem(error: string | null | undefined): boolean {
+  return !!error && error.includes(KEY_CUSTODIAN_LEAD)
+}
+
+/**
+ * The custodian problem the running service reports, or null: its keys
+ * answer, it can't be reached (other checks say so), or it is a release from
+ * before the report.
+ */
+export async function runtimeKeyCustodianProblem(serviceUrl: string, doFetch: (url: string, init?: RequestInit) => Promise<Response> = fetch): Promise<string | null> {
+  try {
+    const res = await doFetch(`${serviceUrl.replace(/\/+$/, '')}/v1/health`, { signal: AbortSignal.timeout(3000) })
+    if (!res.ok) return null
+    const body = (await res.json().catch(() => null)) as { data?: { keyCustodian?: KeyCustodianReport | null } } | null
+    return keyCustodianProblem(body?.data?.keyCustodian)
+  } catch {
+    return null
+  }
+}

package/src/local/local-knowledge-uploads.ts

@@ -1,5 +1,5 @@
 import { randomBytes } from 'node:crypto'
-import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve, sep } from 'node:path'
 
 import { KNOWLEDGE_DOCUMENT } from './local-dev-references'
@@ -23,10 +23,10 @@ import { rows } from './local-sync-remote'
  * - a name already in the folder, unless the request says to replace it;
  * - a folder or file that is a symbolic link, or resolves outside `knowledge/`.
  *
- * Removing a document takes its file out of the folder. The apply only adds
- * what the runtime lacks, so the server takes the runtime's copy off first
- * (`removeRuntimeCopies`), as it does before a replaced file is written, so
- * the next apply uploads the new content.
+ * Removing a document takes its file out of the folder, and the server takes
+ * the runtime's copy off (`removeRuntimeCopies`), as it does before a replaced
+ * file is written. A file edited in place (by a coding agent, say) the apply
+ * uploads again itself, then takes the older copy off (`staleDocuments`).
  */
 
 /** The extensions `local dev` uploads into a knowledge base, as `KNOWLEDGE_DOCUMENT` matches them. */
@@ -211,6 +211,63 @@ export async function removeRuntimeCopies(call: ServiceCall, knowledgeId: string
   return copies.length
 }
 
+/** What the last apply uploaded for each document, by its path: the runtime's copy and the content it was. */
+export type UploadedDocuments = Record<string, { sourceId: string; sha256: string }>
+
+const uploadsPath = (stateDir: string) => join(stateDir, 'knowledge-uploads.json')
+
+/** The documents the apply uploaded into one knowledge base on this runtime; nothing after a reset (another organization). */
+export function loadUploadedDocuments(stateDir: string, organizationId: string, knowledgeId: string): UploadedDocuments {
+  try {
+    const saved = JSON.parse(readFileSync(uploadsPath(stateDir), 'utf8')) as { organizationId?: string; bases?: Record<string, UploadedDocuments> }
+    if (saved.organizationId === organizationId) return saved.bases?.[knowledgeId] ?? {}
+  } catch {
+    // Missing or unreadable: no copy counts as recorded.
+  }
+  return {}
+}
+
+export function saveUploadedDocuments(stateDir: string, organizationId: string, knowledgeId: string, uploaded: UploadedDocuments): void {
+  let bases: Record<string, UploadedDocuments> = {}
+  try {
+    const saved = JSON.parse(readFileSync(uploadsPath(stateDir), 'utf8')) as { organizationId?: string; bases?: Record<string, UploadedDocuments> }
+    if (saved.organizationId === organizationId && saved.bases) bases = saved.bases
+  } catch {
+    // Starts afresh.
+  }
+  try {
+    mkdirSync(stateDir, { recursive: true })
+    writeFileSync(uploadsPath(stateDir), `${JSON.stringify({ organizationId, bases: { ...bases, [knowledgeId]: uploaded } })}\n`, { mode: 0o600 })
+  } catch {
+    // Losing this only means the next apply judges an edit by the copy's size.
+  }
+}
+
+/**
+ * The documents the runtime holds an older copy of, each with the copies to
+ * take off once the new content is up. A copy the last apply recorded is
+ * older when the file's content differs from what was uploaded; a copy no
+ * apply here recorded (uploaded before the record, or by hand) is older when
+ * its size differs, and otherwise taken as the file's.
+ */
+export function staleDocuments(
+  local: Array<{ path: string; sha256: string; bytes: number }>,
+  runtime: Array<{ id: string; path: string; sizeBytes?: number | null }>,
+  uploaded: UploadedDocuments,
+): Array<{ path: string; replaces: string[] }> {
+  const out: Array<{ path: string; replaces: string[] }> = []
+  for (const doc of local) {
+    const copies = runtime.filter((s) => s.path === doc.path)
+    if (!copies.length) continue
+    const was = uploaded[doc.path]
+    const stale = was && copies.some((c) => c.id === was.sourceId)
+      ? was.sha256 !== doc.sha256
+      : copies.length === 1 && typeof copies[0]!.sizeBytes === 'number' && copies[0]!.sizeBytes !== doc.bytes
+    if (stale) out.push({ path: doc.path, replaces: copies.map((c) => c.id) })
+  }
+  return out
+}
+
 /** The project's documents for a knowledge base, each with whether the runtime holds it yet. */
 export function projectDocuments(root: string, folder: string, onRuntime: ReadonlySet<string> | null): Array<{ path: string; onRuntime: boolean | null }> {
   return documentPaths(root, folder).map((path) => ({ path, onRuntime: onRuntime ? onRuntime.has(path) : null }))

package/src/local/local-scaffold.ts

@@ -587,6 +587,53 @@ export function ensureProjectBunfig(root: string): boolean {
   return true
 }
 
+/** The example Agent, workflow, Function, evaluation and object type, with the sample dataset they use. */
+function sampleFiles(name: string, agentModel?: string): Record<string, string> {
+  return {
+    'agents/assistant/agent.json': AGENT(name, agentModel),
+    'agents/assistant/operating.json': OPERATING,
+    'agents/assistant/bindings.json': BINDINGS,
+    'agents/assistant/evals/regression.yaml': EVALS,
+    'workflows/hello.yaml': WORKFLOW,
+    'workflows/tests/hello.yaml': WORKFLOW_TESTS,
+    'functions/word-count.ts': FUNCTION,
+    'functions/word-count.test.ts': FUNCTION_TEST,
+    'datasets/tickets.json': DATASET,
+    'datasets/tickets.csv': DATASET_ROWS,
+    'blueprint/object-types/Ticket.yaml': OBJECT_TYPE,
+  }
+}
+
+/** The sample Agent as compared: its model and the project's name in its description are set per project. */
+function sampleAgent(text: string): unknown {
+  try {
+    const doc = JSON.parse(text) as { config?: Record<string, unknown>; modelConfigs?: unknown }
+    const { description: _description, defaultMode: _defaultMode, ...config } = doc.config ?? {}
+    const { modelConfigs: _models, ...rest } = doc
+    return { ...rest, config }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Whether an item's files are still exactly what setting up the project wrote
+ * for its sample: the example, not the project's own work, so a linked
+ * project does not propose it by default: the sample Ticket type would
+ * otherwise overwrite a workspace's own. Edited, it is the project's.
+ */
+export function isScaffoldSample(files: Record<string, string>): boolean {
+  const sample = sampleFiles('')
+  const paths = Object.keys(files)
+  if (!paths.length) return false
+  return paths.every((path) => {
+    const expected = sample[path]
+    if (expected === undefined) return false
+    if (path === 'agents/assistant/agent.json') return JSON.stringify(sampleAgent(files[path]!)) === JSON.stringify(sampleAgent(expected))
+    return files[path] === expected
+  })
+}
+
 /** `samples: false` leaves out the example Agent, workflow, Function and object type: a project started from a workspace gets the workspace's own. */
 export function solutionScaffoldFiles(name: string, opts: { agentModel?: string; samples?: boolean } = {}): Record<string, string> {
   const sdk = vendored.files as Record<string, string>
@@ -610,19 +657,7 @@ export function solutionScaffoldFiles(name: string, opts: { agentModel?: string;
   out['.codex/config.toml'] = CODEX_MCP_TOML
   out['fixtures/README.md'] = FIXTURES_README
   out['bunfig.toml'] = PROJECT_BUNFIG
-  if (opts.samples !== false) {
-    out['agents/assistant/agent.json'] = AGENT(name, opts.agentModel)
-    out['agents/assistant/operating.json'] = OPERATING
-    out['agents/assistant/bindings.json'] = BINDINGS
-    out['agents/assistant/evals/regression.yaml'] = EVALS
-    out['workflows/hello.yaml'] = WORKFLOW
-    out['workflows/tests/hello.yaml'] = WORKFLOW_TESTS
-    out['functions/word-count.ts'] = FUNCTION
-    out['functions/word-count.test.ts'] = FUNCTION_TEST
-    out['datasets/tickets.json'] = DATASET
-    out['datasets/tickets.csv'] = DATASET_ROWS
-    out['blueprint/object-types/Ticket.yaml'] = OBJECT_TYPE
-  }
+  if (opts.samples !== false) Object.assign(out, sampleFiles(name, opts.agentModel))
   out['package.json'] =
     JSON.stringify(
       {

package/src/local/local-schemas.ts

@@ -134,7 +134,7 @@ const EVALS_SCHEMA: JsonSchema = {
           conversation: {
             type: 'array',
             minItems: 1,
-            description: 'One turn per item. Only the user turns are sent, in order, each as soon as the reply before it ends; an assistant turn is kept for whoever reads the case. `waitSeconds` on a user turn keeps a gap before it (`- { user: "Still there?", waitSeconds: 60 }` sends it a minute after the reply before).',
+            description: 'One turn per item. Only the user turns are sent, in order, each as soon as the reply before it ends; an assistant turn is kept for whoever reads the case. `waitSeconds` on a user turn keeps a gap before it (`- { user: "Still there?", waitSeconds: 60 }` sends it a minute after the reply before). A case of more than one turn runs on this computer only: the workspace\'s evaluation datasets hold single questions, so `frontera local sync push` proposes the file\'s single-question cases and keeps the rest here.',
             items: {
               type: 'object',
               properties: {

package/src/local/local-studio-server.ts

@@ -299,7 +299,7 @@ export function startStudioServer(opts: StudioServerOptions) {
         if (!(file instanceof Blob)) return json({ error: 'send the document as the multipart field "file"' }, 400)
         const name = checkUpload((file as File).name ?? '', file.size)
         const replace = url.searchParams.get('replace') === '1'
-        // Replacing: the runtime's copy goes first, so the apply uploads the new content (it only adds what the runtime lacks).
+        // Replacing: the runtime's copy goes first, so the apply uploads the new content as a document the runtime lacks.
         if (replace && id && documentInFolder(project.root, folder, name)) {
           const call = serviceCall()
           if (call) {

package/src/local/local-supervisor.ts

@@ -32,6 +32,7 @@ import {
   type LocalConfig,
   type LocalSecrets,
 } from './local-env'
+import { runtimeKeyCustodianProblem } from './local-key-custodian'
 import { localEmbeddingsReachable, providerEnv } from './local-keys'
 import { applyProviderSetup, readProviderSetup, rememberSlugs, writeProviderSetup } from './local-providers'
 import type { PortBlock } from './local-ports'
@@ -484,6 +485,7 @@ async function startService(
     running.children.set('service', child)
     const ok = await waitForHttp(`http://127.0.0.1:${ports.service}/health`, 120_000, () => child.exitCode === null)
     if (!ok) throw new Error('the service did not become healthy; see `frontera local logs service`')
+    await refuseBrokenKeyCustodian(ports)
     set('service', { status: 'running', pid: child.pid, startedAt: new Date().toISOString() })
     keepDocs(project, { bundle: customerDocsBundle(config.platformSource) }, log)
     refreshCheckoutDocs(project, config.platformSource, log)
@@ -508,10 +510,21 @@ async function startService(
   followLogs(name, log)
   const ok = await waitForHttp(`http://127.0.0.1:${ports.service}/health`, 180_000)
   if (!ok) throw new Error('the service did not become healthy; see `frontera local logs service`')
+  await refuseBrokenKeyCustodian(ports)
   set('service', { status: 'running', container: name, startedAt: new Date().toISOString() })
   keepDocs(project, { fromContainer: (dest) => copyFromContainer(name, IMAGE_DOCS_PATH, dest) }, log)
 }
 
+/**
+ * A service whose encryption keys can't be read fails every secret and
+ * governed Action record later with a 500: the start stops here instead, with
+ * the fix (`local-key-custodian.ts`).
+ */
+async function refuseBrokenKeyCustodian(ports: PortBlock): Promise<void> {
+  const problem = await runtimeKeyCustodianProblem(`http://127.0.0.1:${ports.service}`)
+  if (problem) throw new Error(problem)
+}
+
 /** The release's documentation, for the solution's coding agents (`frontera mcp`). */
 function keepDocs(project: LocalProject, from: { bundle?: string | null; fromContainer?: (dest: string) => boolean }, log: string): void {
   if (!from.bundle && !from.fromContainer) {

package/src/local/local-sync-link.ts

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process'
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { parseDocument } from 'yaml'
@@ -28,6 +28,11 @@ export interface SyncLink {
   /** Names shown in Forge and `sync status`; refreshed on connect. */
   workspaceName?: string
   organizationName?: string
+  /**
+   * A model this computer names (a local provider's, by catalog slug) and the
+   * workspace's model it goes as when proposed (`local-sync-portable.ts`).
+   */
+  models?: Record<string, string>
 }
 
 export function projectFile(root: string): string {
@@ -40,6 +45,9 @@ export function readLink(root: string): SyncLink | null {
   const doc = parseDocument(readFileSync(file, 'utf8')).toJS() as { sync?: Partial<SyncLink> } | null
   const s = doc?.sync
   if (!s || typeof s.platform !== 'string' || typeof s.workspace !== 'string') return null
+  const models = s.models && typeof s.models === 'object' && !Array.isArray(s.models)
+    ? Object.fromEntries(Object.entries(s.models as Record<string, unknown>).filter((e): e is [string, string] => typeof e[1] === 'string' && !!e[0] && !!e[1]))
+    : {}
   return {
     platform: s.platform,
     workspace: s.workspace,
@@ -47,9 +55,41 @@ export function readLink(root: string): SyncLink | null {
     blueprint: s.blueprint === 'organization' ? 'organization' : 'workspace',
     workspaceName: typeof s.workspaceName === 'string' ? s.workspaceName : undefined,
     organizationName: typeof s.organizationName === 'string' ? s.organizationName : undefined,
+    ...(Object.keys(models).length ? { models } : {}),
   }
 }
 
+const mapped = new Map<string, { mtimeMs: number; models: Record<string, string> }>()
+
+/** The project's model mapping (`sync.models`), empty when it has none or no link; read once per change of the file. */
+export function modelMap(root: string): Record<string, string> {
+  const file = projectFile(root)
+  let mtimeMs = -1
+  try {
+    mtimeMs = statSync(file).mtimeMs
+  } catch {
+    return {}
+  }
+  const known = mapped.get(file)
+  if (known && known.mtimeMs === mtimeMs) return known.models
+  const models = readLink(root)?.models ?? {}
+  mapped.set(file, { mtimeMs, models })
+  return models
+}
+
+/** Map a local model to a workspace model when proposed, or (`workspace` null) stop mapping it. */
+export function setModelMapping(root: string, local: string, workspace: string | null): SyncLink {
+  const link = readLink(root)
+  if (!link) throw new Error('the project is not linked to a workspace')
+  const models = { ...(link.models ?? {}) }
+  if (workspace) models[local] = workspace
+  else delete models[local]
+  const next: SyncLink = { ...link, models }
+  if (!Object.keys(models).length) delete next.models
+  writeLink(root, next)
+  return next
+}
+
 /** Write the link into `frontera.yaml`, keeping the rest of the file and its comments. */
 export function writeLink(root: string, link: SyncLink | null): void {
   const file = projectFile(root)
@@ -58,11 +98,12 @@ export function writeLink(root: string, link: SyncLink | null): void {
   if (!link) {
     doc.delete('sync')
   } else {
-    const value: Record<string, string> = { platform: link.platform, workspace: link.workspace }
+    const value: Record<string, unknown> = { platform: link.platform, workspace: link.workspace }
     if (link.workspaceName) value.workspaceName = link.workspaceName
     if (link.organization) value.organization = link.organization
     if (link.organizationName) value.organizationName = link.organizationName
     value.blueprint = link.blueprint
+    if (link.models && Object.keys(link.models).length) value.models = link.models
     const existing = doc.get('sync', true) as { commentBefore?: string } | undefined
     const node = doc.createNode(value) as unknown as { commentBefore?: string }
     node.commentBefore = existing?.commentBefore ?? ' The platform workspace this project pulls from (`frontera local sync`). Keys are in your keychain, not here.'