@frontera-sdk/cli 1.52.42 → 1.52.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.52.42",
+  "version": "1.52.44",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -40,8 +40,8 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
     "@faker-js/faker": "10.6.0",
-    "@frontera-sdk/core": "1.52.42",
-    "@frontera-sdk/functions": "1.52.42",
+    "@frontera-sdk/core": "1.52.44",
+    "@frontera-sdk/functions": "1.52.44",
     "ai": "^6.0.116",
     "axe-core": "4.12.1",
     "gray-matter": "^4.0.3",
@@ -49,7 +49,7 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.52.42",
+    "@frontera-sdk/forge-contracts": "1.52.44",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/commands/local/check.ts

@@ -26,6 +26,7 @@ import { agentFilesProblem, caseConcurrency, findCaseFiles, runCases, selectCase
 import { findWorkflowTestFiles, recordWorkflowTestRun, runWorkflowTests, workflowFileState } from '../../local/local-workflow-tests'
 import { vendoredSdkLine, vendoredSdkState } from '../../local/local-vendored-sdk'
 import { withFix } from '../../local/fix-words'
+import { runtimeKeyCustodianProblem } from '../../local/local-key-custodian'
 import { ensureAppPackages } from '../../project-bootstrap'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
 
@@ -53,8 +54,10 @@ import { flagBool, flagString, type Command, type CommandContext } from '../type
  * case with `realActions` or a `decision`), so after the apply the database
  * is kept as a baseline (`local-db-snapshot.ts`, taken again only when what
  * is applied changed), and after the tests it is restored: each check starts
- * from the data the project's files make. `--keep-state` keeps what the tests
- * wrote, to look at it.
+ * from the data the project's files make. The run history (conversations,
+ * runs, evaluations) is kept across it (`local-history-carry.ts`), so one
+ * check's results can be compared with the last. `--keep-state` keeps what the
+ * tests wrote, to look at it.
  *
  * Knowledge documents are read by a background job whose work lands in the
  * database: before the baseline and the tests, the check waits (bounded)
@@ -373,8 +376,13 @@ async function check(ctx: CommandContext) {
       continue
     }
     if (step === 'start') {
-      if (running(project)) record({ step, status: 'skipped', note: 'the runtime is already running', ms: 0 })
-      else await command(step, root, self(['local', 'start']), 'frontera local start')
+      if (running(project)) {
+        // Running, with keys it can't read: every later step would fail on a secret or an Action record.
+        const state = readState(project)!
+        const keyProblem = await runtimeKeyCustodianProblem(`http://127.0.0.1:${state.ports.service}`)
+        if (keyProblem) record({ step, status: 'failed', note: keyProblem, ms: 0 })
+        else record({ step, status: 'skipped', note: 'the runtime is already running', ms: 0 })
+      } else await command(step, root, self(['local', 'start']), 'frontera local start')
       continue
     }
     if (step === 'apply') {
@@ -560,10 +568,9 @@ async function check(ctx: CommandContext) {
       })
       recordRun(project, results)
       const bad = results.filter((r) => !r.passed && !r.notRun)
-      // Each failing case's conversation, last turn's trace and reply, read before the rollback takes the conversation.
+      // Each failing case's conversation, last turn's trace and reply, read before the rollback (which keeps the conversation).
       const evidence = await failingCaseEvidence(project, results)
-      const rollsBack = baselineReady && !!testData && !testData.kept
-      for (const [i, e] of evidence) ctx.output.note(`     ${results[i]!.agent} · ${results[i]!.name}: ${evidenceLine(e, { rolledBack: rollsBack })}`)
+      for (const [i, e] of evidence) ctx.output.note(`     ${results[i]!.agent} · ${results[i]!.name}: ${evidenceLine(e)}`)
       const notRun = notRunGroups(results)
       for (const g of notRun) {
         if (g.skipped) ctx.output.note(`   – ${g.skipped} more case${g.skipped === 1 ? '' : 's'} not sent: ${g.what}`)
@@ -604,9 +611,10 @@ async function check(ctx: CommandContext) {
     const state = readState(project)
     if (state?.credentials && running(project)) {
       const restored = await restoreBaseline(project, state.credentials.organizationId, { serviceAnswers: () => waitForDatabaseReady(`http://127.0.0.1:${state.ports.service}`) })
-      // Traces live outside the platform database: a failing case's trace outlives the rollback, its conversation does not.
+      // The run history is kept across the rollback; when it couldn't be, a failing case's conversation went with it (its trace stays: traces live outside the database).
       const traced = steps.some((st) => st.failures?.some((f) => f.traceId))
-      testData = { ...testData, rolledBack: restored.ok, ms: restored.ms, note: restored.ok ? `the tests’ writes were rolled back: ${restored.note}${traced ? '; the failing cases’ conversations went with them, their traces stay (trace_get, Studio’s Traces)' : ''}` : `the tests’ writes were not rolled back: ${restored.note}` }
+      const historyLost = restored.history?.mode === 'keep' && !restored.history.ok
+      testData = { ...testData, rolledBack: restored.ok, ms: restored.ms, note: restored.ok ? `the tests’ writes were rolled back: ${restored.note}${traced && historyLost ? '; the failing cases’ conversations went with them, their traces stay (trace_get, Studio’s Traces)' : ''}` : `the tests’ writes were not rolled back: ${restored.note}` }
       ctx.output.note(`── test data: ${testData.note}${restored.ok ? ' (`--keep-state` keeps them)' : ''}`)
       // The documents the baseline holds unread are read again: their reading went with the database the restore replaced.
       const ingest = restored.ok ? localIngestApi(`http://127.0.0.1:${state.ports.service}`, state.credentials) : null

package/src/commands/local/index-commands.ts

@@ -59,6 +59,7 @@ import { localSchema } from './schema'
 import { localSync } from './sync'
 import { keylessEmbeddingsStatus, KEYLESS_RETRIEVAL_NOTE } from '../../local/local-org-settings'
 import { withFix } from '../../local/fix-words'
+import { isKeyCustodianProblem, KEY_CUSTODIAN_FIX, runtimeKeyCustodianProblem } from '../../local/local-key-custodian'
 
 /**
  * `frontera local …`: Frontera's runtimes on this machine, for FDEs and the coding agents working with them.
@@ -302,7 +303,8 @@ async function start(ctx: CommandContext): Promise<{ data: unknown; text: string
   if (state.phase !== 'ready') {
     throw new CliError(`the local runtime did not start: ${state.error ?? state.phase}`, {
       code: 'LOCAL_START',
-      hint: 'see `frontera local logs <component>`; fix the cause and run `frontera local start` again',
+      // Keys a restart can't bring back: the error carries its fix, a reset.
+      hint: isKeyCustodianProblem(state.error) ? KEY_CUSTODIAN_FIX : 'see `frontera local logs <component>`; fix the cause and run `frontera local start` again',
     })
   }
   const profile = await registerLocalProfile(project, state)
@@ -411,6 +413,8 @@ async function status(ctx: CommandContext) {
   const stuck = (state.phase === 'ready' && isAlive(state.supervisorPid) && state.credentials ? await stuckKnowledge(`http://127.0.0.1:${state.ports.service}`, state.credentials, readBaseline(project, state.credentials.organizationId)?.restoredAt) : null) ?? []
   // What the runtime holds with no file in the project (an Agent whose folder was deleted): said with its fix.
   const orphans = (state.phase === 'ready' && isAlive(state.supervisorPid) && state.credentials ? await projectOrphans(project, `http://127.0.0.1:${state.ports.service}`, state.credentials).catch(() => null) : null) ?? []
+  // Encryption keys the runtime can't read (data keys a hosted OpenBao locked): every secret and governed Action record fails until a reset.
+  const keyProblem = state.phase === 'ready' && isAlive(state.supervisorPid) ? await runtimeKeyCustodianProblem(`http://127.0.0.1:${state.ports.service}`) : null
   return {
     data: {
       ...rest,
@@ -431,9 +435,11 @@ async function status(ctx: CommandContext) {
       ...(stuck.length ? { knowledgeStuck: stuck } : {}),
       // On the runtime, not in the files: each with what fixes it (`local dev` archives an Agent or workflow whose file was deleted).
       ...(orphans.length ? { notInProject: orphans } : {}),
+      ...(keyProblem ? { keyCustodian: { problem: keyProblem, fix: KEY_CUSTODIAN_FIX } } : {}),
     },
     text: [
       renderStatus({ ...state, components }, project, undefined, live, setIds, personas, secrets, liveApps ?? null, down),
+      ...(keyProblem ? ['', 'Encryption keys', `  ✕ ${keyProblem}`] : []),
       ...(stuck.length ? ['', 'Knowledge', ...stuck.map((k) => `  warning: ${k.problem}`)] : []),
       ...(orphans.length ? ['', 'On the runtime, not in the project', ...orphans.map((o) => `  warning: ${orphanLine(o)}`)] : []),
       ...(devServers.length ? ['', 'App dev servers', ...devServers.map((s) => `  ${devServerLine(s)}`)] : []),

package/src/commands/local/snapshot.ts

@@ -1,6 +1,7 @@
 import { CliError, UsageError } from '../../errors'
 import { appsLostWords } from '../../local/local-app-restore'
 import { BASELINE_DB, readBaseline, restoreBaseline, saveBaseline, secretsWords } from '../../local/local-db-snapshot'
+import { historyWords } from '../../local/local-history-carry'
 import { localIngestApi, settleKnowledge } from '../../local/local-knowledge-ingestion'
 import { localProject } from '../../local/local-project'
 import { projectSecretLines } from '../../local/local-project-secrets'
@@ -15,7 +16,8 @@ import { flagBool, type Command } from '../types'
  * same, by hand: save after setting up data to come back to, restore to throw
  * away what was written since. The catalog of managed datasets, object
  * storage and local traces are not part of it. Workspace secrets are
- * configuration, not data: a restore keeps them as they are now, unless
+ * configuration, not data, and the run history (conversations, runs,
+ * evaluations) is what happened: a restore keeps both as they are now, unless
  * `--exact` puts the baseline's back too.
  */
 
@@ -31,6 +33,7 @@ export const localSnapshot: Command = {
     details: [
       'save keeps the database as it is now as the baseline, replacing the one before. restore puts the database back as the baseline holds it; the service, job engine and runner keep running and reconnect, and the command returns once the service reaches the database again (it waits up to 30 seconds).',
       'Workspace secrets are configuration, not data: restore keeps them as they are now (set, changed or deleted since the baseline), and `local check` keeps them across its rollback too. `--exact` puts the baseline\'s secrets back as well.',
+      'The run history is kept the same way: conversations (an Agent test case\'s included), Agent sessions and runs, workflow and Function runs and evaluation runs are as they were before the restore, so results can be compared across runs; the records those runs wrote are rolled back. A history row that names a record the restore took away is left out and counted. `--exact` puts the baseline\'s history back as well.',
       'Items applied after the baseline count as not applied once it is restored: the next `frontera local dev` applies them again (a running one does so at once).',
       'Knowledge documents are read by a background job. save waits (up to two minutes) until no document is still being read, so the baseline never holds one half-read; restore queues any document the baseline holds unread to be read again, and waits for it.',
     ],
@@ -64,7 +67,7 @@ export const localSnapshot: Command = {
     }
     const exact = flagBool(ctx, 'exact')
     const restored = await ctx.output.task('Restoring the database from the baseline', () =>
-      restoreBaseline(project, organizationId, { serviceAnswers: () => waitForDatabaseReady(`http://127.0.0.1:${state.ports.service}`) }, { secrets: exact ? 'baseline' : 'keep' }),
+      restoreBaseline(project, organizationId, { serviceAnswers: () => waitForDatabaseReady(`http://127.0.0.1:${state.ports.service}`) }, { secrets: exact ? 'baseline' : 'keep', history: exact ? 'baseline' : 'keep' }),
     )
     if (!restored.ok) throw new CliError(restored.note, { code: 'LOCAL_SNAPSHOT_FAILED', hint: 'see `frontera local logs postgres` and `frontera local logs service`' })
     // The documents the baseline holds unread are read again: their reading went with the database the restore replaced.
@@ -85,6 +88,8 @@ export const localSnapshot: Command = {
         ...(lost.length ? { appsLost: lost.map((a) => ({ app: a.name, dir: a.dir, deployment: a.lost, baselineDeployment: a.back })) } : {}),
         // Names and counts only: what became of the workspace secrets.
         workspaceSecrets: restored.secrets?.mode === 'keep' ? { kept: restored.secrets.ok, count: restored.secrets.kept, setAgain: restored.secrets.notKept, ...(restored.secrets.problem ? { problem: restored.secrets.problem } : {}) } : { kept: false, exact: exact },
+        // Counts only: what became of the run history.
+        runHistory: restored.history?.mode === 'keep' ? { kept: restored.history.ok, rows: restored.history.rows, notKept: restored.history.notKept, ...(restored.history.problem ? { problem: restored.history.problem } : {}) } : { kept: false, exact },
         ...(secrets.length ? { secrets } : {}),
         ...(knowledge.length ? { knowledge: knowledge.map((l) => l.replace(/^warning:\s*/, '')) } : {}),
       },
@@ -92,6 +97,7 @@ export const localSnapshot: Command = {
         `Restored the database from the baseline: what was written since is gone (${restored.ms} ms).${items ? ` ${items} item${items === 1 ? '' : 's'} applied after the baseline will apply again on the next \`frontera local dev\`.` : ''}`,
         ...(lost.length ? [`  ${appsLostWords(lost).replace(/^./, (c) => c.toUpperCase())}.`] : []),
         ...(restored.secrets ? [`  ${secretsWords(restored.secrets).replace(/^./, (c) => c.toUpperCase())}${restored.secrets.mode === 'keep' && restored.secrets.ok && !restored.secrets.notKept.length ? ': secrets are configuration, not test data (`--exact` restores the baseline’s).' : '.'}`] : []),
+        ...(restored.history ? [`  ${historyWords(restored.history).replace(/^./, (c) => c.toUpperCase())}.`] : []),
         ...secrets.map((l) => `  warning: ${l}`),
         ...knowledge.map((l) => `  ${l}`),
       ].join('\n'),

package/src/commands/local/sync-request.ts

@@ -12,8 +12,10 @@ import { adoptProposedLessons } from '../../local/local-lessons'
 import { localProject, type LocalProject } from '../../local/local-project'
 import { HISTORY_KINDS, projectAtRevision } from '../../local/local-sync-base'
 import { normalizeOrigin, unwrap } from '../../local/local-sync-client'
-import { getSyncKey, readLink, type SyncLink } from '../../local/local-sync-link'
+import { getSyncKey, readLink, setModelMapping, type SyncLink } from '../../local/local-sync-link'
 import { itemTitle } from '../../local/local-sync-names'
+import { checkBody, markMissingModels, markRefused, type WorkspaceModel } from '../../local/local-sync-precheck'
+import { rows } from '../../local/local-sync-remote'
 import { evalsDetail, evalsLine, lastRender, sessionScreenshots } from '../../local/local-request-evidence'
 import { readAppliedRun, readLastRun, recordApplied, recordRun } from '../../local/local-test-baseline'
 import { agentFilesProblem, runCases, selectCaseFiles } from '../../local/local-test-runner'
@@ -330,6 +332,9 @@ function itemJson(item: PushItem) {
     proposable: item.proposable,
     blocked: item.blocked,
     reason: item.reason,
+    ...(item.fix ? { fix: item.fix } : {}),
+    ...(item.sample ? { sample: true } : {}),
+    ...(item.missingModels?.length ? { missingModels: item.missingModels } : {}),
     files: item.diff,
     notes: item.notes,
     ...(item.assets ? { assets: item.assets.map((a) => ({ path: a.path, bytes: a.bytes, change: a.change })) } : {}),
@@ -404,8 +409,41 @@ async function deletionUsers(project: LocalProject, link: SyncLink, items: PushI
   }
 }
 
+/**
+ * The workspace's checks for what would be proposed, run before anything is
+ * sent (`POST /v1/change-requests/check`); each item they refuse is blocked
+ * with its reason and fix. A platform without the check leaves them to
+ * Propose: `checked` says which.
+ */
+async function precheck(api: Platform, items: PushItem[]): Promise<{ checked: boolean; refused: string[]; problem?: string }> {
+  const body = checkBody(items)
+  if (!body.length) return { checked: true, refused: [] }
+  try {
+    const answer = await api.call<{ checks?: unknown[] }>('POST', '/v1/change-requests/check', { items: body }, { timeoutMs: 120_000 })
+    return { checked: true, refused: markRefused(items, checksOf(answer)) }
+  } catch (err) {
+    if (err instanceof CliError && (err.code === 'NOT_FOUND' || err.code === 'SYNC_CHECKS')) {
+      // An older platform has no check; a refusal of the check itself names the items as the push would.
+      if (err.code === 'SYNC_CHECKS') return { checked: true, refused: markRefused(items, checksOf(err.details)) }
+      return { checked: false, refused: [] }
+    }
+    return { checked: false, refused: [], problem: (err as Error).message.split('\n')[0] }
+  }
+}
+
+/** The workspace's chat models, offered in place of one only this computer has; empty when the platform can't list them. */
+async function workspaceModels(api: Platform): Promise<WorkspaceModel[]> {
+  try {
+    const answer = await api.call<unknown>('GET', '/v1/sync/models')
+    return rows<{ slug?: string; name?: string; kind?: string }>(answer).flatMap((m) => (m.slug && (m.kind ?? 'text') === 'text' ? [{ slug: m.slug, name: m.name ?? m.slug, kind: m.kind ?? 'text' }] : []))
+  } catch {
+    return []
+  }
+}
+
 function previewText(link: SyncLink, items: PushItem[], kept: { title: string } | null, orgNote: string | null, available: boolean, usedBy: Map<string, string[]> = new Map()): string {
-  const ok = items.filter((i) => i.proposable)
+  const ok = items.filter((i) => i.proposable && !i.sample)
+  const samples = items.filter((i) => i.proposable && i.sample)
   const not = items.filter((i) => !i.proposable)
   const name = link.workspaceName ?? link.workspace
   const lines = [
@@ -413,7 +451,8 @@ function previewText(link: SyncLink, items: PushItem[], kept: { title: string }
     // Each item's notes under it.
     ...ok.flatMap((i) => [`  [x] ${pushItemLine(i)}`, ...(usedBy.has(i.ref) ? [`      ! Still used by ${usedBy.get(i.ref)!.join(', ')}: applying would be refused`] : []), ...i.notes.map((n) => `      · ${n}`)]),
   ]
-  if (not.length) lines.push('', 'Not proposed:', ...not.map((i) => `  [ ] ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`))
+  if (samples.length) lines.push('', 'Samples from setting up the project, left out unless named:', ...samples.map((i) => `  [ ] ${KIND_WORD[i.kind]} ${i.title}`))
+  if (not.length) lines.push('', 'Not proposed:', ...not.flatMap((i) => [`  [ ] ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`, ...(i.fix ? [`      Fix: ${i.fix}`] : [])]))
   if (orgNote) lines.push('', orgNote)
   if (!available) lines.push('', 'This platform does not take change requests yet.')
   if (ok.length && available) lines.push('', 'Propose with `frontera local sync push -t "<title>"`, or name items to propose only those.')
@@ -443,6 +482,36 @@ async function releaseItems(api: Platform, asked: Array<{ slug: string; deployme
   return out
 }
 
+/**
+ * `frontera local sync map-model <local model> <workspace model>`: the
+ * workspace's model a model only this computer has goes as when proposed
+ * (`sync.models` in frontera.yaml); the files keep naming the local one.
+ * `--remove` stops mapping it; with no model, the mappings are listed.
+ */
+export async function syncMapModel(ctx: CommandContext): Promise<{ data: unknown; text: string }> {
+  const project = localProject(ctx.cwd)
+  const link = needLink(project)
+  const [local, workspace] = ctx.positional.slice(1)
+  const name = link.workspaceName ?? link.workspace
+  if (!local) {
+    const models = link.models ?? {}
+    const lines = Object.entries(models).map(([from, to]) => `  ${from} → ${to}`)
+    return { data: { models }, text: lines.length ? [`Models proposed to ${name} as the workspace’s:`, ...lines].join('\n') : `No models mapped. \`frontera local sync push --preview\` names any model ${name} doesn’t have.` }
+  }
+  if (flagBool(ctx, 'remove')) {
+    setModelMapping(project.root, local, null)
+    return { data: { local, workspace: null }, text: `${local} is no longer mapped: an item that names it isn’t proposed until it is mapped again.` }
+  }
+  if (!workspace) throw new UsageError('name the workspace model it goes as', `frontera local sync map-model ${local} <workspace model>; \`push --preview\` lists ${name}’s models`)
+  const offered = await workspaceModels(platformFor(project, link))
+  if (offered.length && !offered.some((m) => m.slug === workspace)) {
+    throw new UsageError(`${name} has no chat model ${workspace}`, `choose one of: ${offered.map((m) => m.slug).slice(0, 12).join(', ')}${offered.length > 12 ? ', …' : ''}`)
+  }
+  setModelMapping(project.root, local, workspace)
+  const label = offered.find((m) => m.slug === workspace)?.name ?? workspace
+  return { data: { local, workspace }, text: `${local} goes to ${name} as ${label} when proposed; the project keeps using ${local} here (sync.models in frontera.yaml).` }
+}
+
 export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; text: string }> {
   const project = localProject(ctx.cwd)
   const link = needLink(project)
@@ -462,6 +531,11 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
     ? { names: new Set(documentNames), pulled: readPulledDocuments(project.root, link.workspace).bases, platform: await platformDocuments(platformFor(project, link), documentNames, remote.items) }
     : undefined
   const all = pushCandidates({ root: project.root, plan, lock, snapshot, remote: remote.items, ...(documents ? { documents } : {}) })
+  // Before anything is sent: models only this computer has, then the workspace's own checks.
+  const known = snapshot.names?.model ? new Set(Object.keys(snapshot.names.model)) : null
+  const missing = known ? markMissingModels(all, known) : new Map<string, string[]>()
+  const api = platformFor(project, link)
+  const checked = available ? await precheck(api, all) : { checked: false, refused: [] as string[] }
   const kept = currentRequest(readRequests(project.root, link.workspace))
   const updating = kept && isOpen(kept.state) ? kept : null
   const orgStored = !!getSyncKey(project, 'organization')
@@ -474,6 +548,8 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
     if (unknown.length) throw new UsageError(`nothing to propose in ${unknown.join(', ')}: ${unknown.length === 1 ? 'it matches' : 'they match'} the workspace, or the project has no such item`, 'list what can be proposed with `frontera local sync push --preview`')
     chosen = named.map((r) => byRef.get(r)!)
   } else chosen = all
+  // Samples from setting up the project go only when named.
+  const leftSamples = named.length ? [] : chosen.filter((i) => i.proposable && i.sample)
   const orgNote = needsOrganizationKey(chosen) ? (orgStored ? 'Blueprint changes are applied with the organization key stored for this project.' : 'Blueprint changes need the organization key to apply: connect again with `--org-key -` before applying.') : null
 
   if (preview) {
@@ -484,7 +560,15 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
         available,
         request: updating ? { id: updating.id, title: updating.title, state: updating.state, items: updating.refs.length, refs: updating.refs } : null,
         items: chosen.map((i) => ({ ...itemJson(i), ...(usedBy.has(i.ref) ? { usedBy: usedBy.get(i.ref) } : {}) })),
-        counts: { proposable: chosen.filter((i) => i.proposable).length, blocked: chosen.filter((i) => !i.proposable).length },
+        counts: { proposable: chosen.filter((i) => i.proposable && !i.sample).length, samples: leftSamples.length, blocked: chosen.filter((i) => !i.proposable).length },
+        // Whether the workspace's checks ran before proposing; a platform without them checks at Propose.
+        checked: checked.checked,
+        ...(('problem' in checked && checked.problem) ? { checkProblem: checked.problem } : {}),
+        models: {
+          missing: [...missing].map(([slug, refs]) => ({ slug, refs })),
+          workspace: missing.size ? await workspaceModels(api) : [],
+          mapped: link.models ?? {},
+        },
         organizationKey: { needed: needsOrganizationKey(chosen), stored: orgStored },
         fetchedAt: snapshot.fetchedAt,
       },
@@ -503,12 +587,11 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
       details: { blocked: stopping.map((i) => ({ ref: i.ref, code: i.blocked, message: i.reason })) },
     })
   }
-  const going = chosen.filter((i) => i.proposable)
+  const going = chosen.filter((i) => i.proposable && !leftSamples.includes(i))
   const releaseAsks = parseReleases(flagString(ctx, 'release'))
   if (!going.length && !releaseAsks.length) throw new CliError('nothing to propose: nothing changed here since the last pull', { code: 'SYNC_NOTHING_TO_PUSH', hint: 'change an item in the project first; `frontera local sync status` shows where it stands' })
   const title = flagString(ctx, 'title')?.trim()
   const description = flagString(ctx, 'description')
-  const api = platformFor(project, link)
   // The current request still taking pushes is updated; one applied or closed (here or on the platform) is not.
   let target = updating
   if (target) {
@@ -554,14 +637,16 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
       request: { id: view.request.id, title: view.request.title, state: view.request.state, items: view.items.length, refs: view.items.map((i) => i.ref) },
       pushed: [...going.map((i) => i.ref), ...releases.map((r) => r.ref)],
       releases: releases.map((r) => ({ ref: r.ref, deployment: r.deployment })),
-      notProposed: notProposed.map((i) => ({ ref: i.ref, code: i.blocked, message: i.reason })),
+      notProposed: notProposed.map((i) => ({ ref: i.ref, code: i.blocked, message: i.reason, ...(i.fix ? { fix: i.fix } : {}) })),
+      samples: leftSamples.map((i) => i.ref),
       organizationKey: { needed: needsOrganizationKey(view.items), stored: orgStored },
     },
     text: [
       `${target ? `Updated “${view.request.title}” in` : `Proposed “${view.request.title}” to`} ${link.workspaceName ?? link.workspace}: ${plural(view.items.length, 'item')}.`,
       ...going.map((i) => `  ${pushItemLine(i)}`),
       ...releases.map((r) => `  Custom App ${r.slug}: release ${r.deployment}${r.chosen ? ' (its newest deployment)' : ''}; Apply promotes it last`),
-      ...(notProposed.length ? ['', 'Not proposed:', ...notProposed.map((i) => `  ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`)] : []),
+      ...(notProposed.length ? ['', 'Not proposed:', ...notProposed.flatMap((i) => [`  ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`, ...(i.fix ? [`    Fix: ${i.fix}`] : [])])] : []),
+      ...(leftSamples.length ? ['', `Left out: ${plural(leftSamples.length, 'sample')} from setting up the project (${leftSamples.map((i) => i.title).join(', ')}); name ${leftSamples.length === 1 ? 'it' : 'them'} to propose`] : []),
       ...(orgNote ? ['', orgNote] : []),
       '',
       'Apply it with `frontera local sync request apply`; see it with `frontera local sync request`.',
@@ -812,7 +897,8 @@ async function apply(ctx: CommandContext) {
   if (force && !reason) throw new UsageError('--force needs --reason', 'frontera local sync request apply --force --reason "why it applies without its required checks"')
   let answer: View
   try {
-    answer = await platformFor(project, link).call<View>('POST', `/v1/change-requests/${view.request.id}/apply`, { ...(migration ? { migrationInstruction: migration } : {}), ...(force ? { force: { reason } } : {}) }, { organizationKey, timeoutMs: 15 * 60_000 })
+    // The key in the body: the platform's edge strips `x-frontera-*` headers a client sends. The header stays for an older platform.
+    answer = await platformFor(project, link).call<View>('POST', `/v1/change-requests/${view.request.id}/apply`, { ...(migration ? { migrationInstruction: migration } : {}), ...(force ? { force: { reason } } : {}), ...(organizationKey ? { organizationKey } : {}) }, { organizationKey, timeoutMs: 15 * 60_000 })
   } catch (err) {
     if (err instanceof CliError && err.code === 'SYNC_APPLY_GATED') {
       const gate = (err.details as { gate?: Gate } | undefined)?.gate

package/src/commands/local/sync.ts

@@ -35,6 +35,8 @@ import {
   type SyncKind,
 } from '../../local/local-sync-plan'
 import { readWorkspace, type SyncSource } from '../../local/local-sync-remote'
+import { rememberLocalCatalog } from '../../local/local-sync-models'
+import { runningTarget, runtimeCatalog } from '../../local/local-providers'
 import { buildStatusText, projectBuildSummary } from '../../local/local-build-summary'
 import { kindTitle } from '../../local/local-sync-names'
 import { describeUnresolved } from '../../local/local-sync-refs'
@@ -59,7 +61,7 @@ import {
 } from '../../local/local-sync-snapshot'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
 import { currentRequest, readRequests } from '../../local/local-sync-push'
-import { syncPush, syncRequest } from './sync-request'
+import { syncMapModel, syncPush, syncRequest } from './sync-request'
 
 /**
  * `frontera local sync`: a local project's link to one platform workspace.
@@ -231,7 +233,16 @@ function sourceIfKeyed(project: LocalProject, link: SyncLink): SyncSource | unde
  * unchanged copies only, `online` from the platform too, at the lock's
  * revision. `bases` says what was found and what was not.
  */
+/** This computer's model catalog, kept while its runtime runs, so models are matched by what they are offline too. */
+async function refreshLocalCatalog(project: LocalProject): Promise<void> {
+  const target = runningTarget(project.root)
+  if (!target) return
+  const models = await runtimeCatalog(target).catch(() => null)
+  if (models?.length) rememberLocalCatalog(project.root, models)
+}
+
 export async function planFor(project: LocalProject, link: SyncLink, opts: { kinds?: Set<SyncKind>; drafts?: Set<string>; fetch?: 'auto' | 'always' | 'never'; repair?: 'offline' | 'online' } = {}) {
+  await refreshLocalCatalog(project)
   const local = localItems(project).filter((l) => !opts.kinds || opts.kinds.has(l.kind))
   const readFromBase = (path: string) => readBase(project.root, path)
   const noBases: BaseRepair[] = []
@@ -397,8 +408,12 @@ async function checkKeys(platform: string, keys: { workspace: string; organizati
     org = syncClient(platform, keys.organization)
     const orgMe = await org.find<WhoAmI>('/v1/whoami').catch(() => null)
     if (orgMe?.orgId && orgMe.orgId !== me.orgId) throw new CliError('the organization key belongs to another organization than the workspace', { code: 'USAGE', hint: 'use a key from the organization that owns the workspace' })
-    // The lifecycle is what an organization key is for here; reading it proves the key.
-    await org.get('/v1/blueprint/lifecycle')
+    // The lifecycle is what an organization key is for here; reading it proves the key. The read is authorized before
+    // the lookup, so a 404 (an organization that has never published a Blueprint: no lifecycle yet) proves it too.
+    await org.find('/v1/blueprint/lifecycle').catch((err: Error) => {
+      if (err instanceof CliError && (err.code === 'UNAUTHORIZED' || err.code === 'FORBIDDEN')) throw err
+      throw new CliError(`the organization key couldn’t read the organization’s Blueprint: ${err.message.split('\n')[0]}`, { code: 'SYNC_ORG_KEY_UNREADABLE', hint: 'check the key is a current organization key (sk-org-…) for this platform, then connect again' })
+    })
   }
   return { me, identity }
 }
@@ -425,6 +440,8 @@ const connect = async (ctx: CommandContext) => {
     organization: keys.organization ? me.orgId! : previous?.organization,
     organizationName: identity?.organization.name ?? previous?.organizationName,
     blueprint: (blueprintFlag as SyncLink['blueprint'] | undefined) ?? (previous?.blueprint === 'organization' && keys.organization ? 'organization' : 'workspace'),
+    // The models mapped for this workspace stay; another workspace has its own catalog.
+    ...(previous?.models && previous.workspace === me.workspaceId ? { models: previous.models } : {}),
   }
   // A folder that is not a project yet gets the project file the link lives in.
   if (!existsSync(projectFile(project.root))) writeFileSync(projectFile(project.root), `# A Frontera project. \`frontera local dev\` applies agents/, workflows/, functions/ and blueprint/.\nname: ${basename(project.root)}\n`)
@@ -948,6 +965,7 @@ const SUBCOMMANDS: Record<string, (ctx: CommandContext) => Promise<{ data: unkno
   // Called through, not referenced: `sync-request.ts` imports this module back.
   push: (ctx) => syncPush(ctx),
   request: (ctx) => syncRequest(ctx),
+  'map-model': (ctx) => syncMapModel(ctx),
 }
 
 export const localSync: Command = {
@@ -955,8 +973,8 @@ export const localSync: Command = {
     noun: 'local',
     verb: 'sync',
     args: [
-      { name: 'action', required: true, description: 'connect | fetch | status | pull | diff | resolve | push | request | disconnect' },
-      { name: 'items', required: false, description: 'kind/name … to pull or push, the one to diff or resolve, or show | apply | close after request' },
+      { name: 'action', required: true, description: 'connect | fetch | status | pull | diff | resolve | push | request | map-model | disconnect' },
+      { name: 'items', required: false, description: 'kind/name … to pull or push, the one to diff or resolve, show | apply | close after request, or the local and workspace models after map-model' },
     ],
     flags: {
       platform: 'string',
@@ -994,6 +1012,7 @@ export const localSync: Command = {
       renders: 'boolean',
       screenshots: 'string',
       trace: 'string',
+      remove: 'boolean',
     },
     aliases: { t: 'title', d: 'description' },
     summary: 'Link the project to a platform workspace, pull and merge what you choose, and propose changes back',
@@ -1024,6 +1043,8 @@ export const localSync: Command = {
       'frontera local sync request apply',
       'frontera local sync request apply --force --reason "hotfix, checked by hand"',
       'frontera local sync request close',
+      'frontera local sync map-model llama-4-70b claude-haiku-5-5',
+      'frontera local sync map-model llama-4-70b --remove',
       'frontera local sync disconnect --forget-link',
     ],
     offline: true,
@@ -1032,7 +1053,7 @@ export const localSync: Command = {
     const action = ctx.positional[0]
     const run = action ? SUBCOMMANDS[action] : undefined
     const named = action ? `\`${action}\`` : '(none given)'
-    if (!run) throw new UsageError(`unknown sync action ${named}`, 'use connect, fetch, status, pull, diff, resolve, push, request or disconnect')
+    if (!run) throw new UsageError(`unknown sync action ${named}`, 'use connect, fetch, status, pull, diff, resolve, push, request, map-model or disconnect')
     return run(ctx)
   },
 }

package/src/commands/registry.ts

@@ -222,7 +222,8 @@ export function nounSummary(noun: string): string {
 
 const KEYS_ARE_SETTINGS_ONLY =
   'organization keys are managed in Organization settings → API Keys, workspace keys in '
-  + 'Workspace settings → API Keys — by a signed-in administrator, never by the CLI: a '
+  + 'Workspace settings → API Keys, and an agent’s server and public website keys under the '
+  + 'agent’s API keys — by a signed-in administrator, never by the CLI: a '
   + 'credential that mints credentials is the escalation that separation exists to prevent'
 
 /**

package/src/local/local-case-evidence.ts

@@ -11,8 +11,9 @@ import type { CaseResult } from './local-test-runner'
  * matching traces by their time.
  *
  * Traces are kept by the local traces store, outside the platform database:
- * `local check` rolls back the database after its tests (the conversation goes
- * with it), and the trace stays readable (`trace_get`, Studio's Traces page).
+ * `local check` rolls back the database after its tests, keeping the run
+ * history (the conversation included) unless that fails, and the trace stays
+ * readable either way (`trace_get`, Studio's Traces page).
  */
 export interface CaseEvidence {
   conversationId?: string

package/src/local/local-db-snapshot.ts

@@ -6,6 +6,7 @@ import { writeFileAtomic } from '../fs-atomic'
 import { loadHashes } from './local-applied'
 import { appDeployments, appsLostByRestore, appsLostWords, markAppsLostByRestore, type AppLostByRestore } from './local-app-restore'
 import { execInContainer, queryInContainer } from './local-docker'
+import { dumpHistory, historyWords, loadHistory, type HistoryCarried } from './local-history-carry'
 import { POSTGRES_DB, POSTGRES_USER } from './local-env'
 import type { LocalProject } from './local-project'
 import { carrySecrets, readSecrets, type QueryFn, type SecretsCarried } from './local-secret-carry'
@@ -34,6 +35,12 @@ import { containerName } from './local-supervisor'
  * encrypted under, copied as stored), unless it is asked for the baseline's
  * (`secrets: 'baseline'`, `frontera local snapshot restore --exact`).
  *
+ * The run history is what happened, not test data either: conversations,
+ * Agent sessions and runs, workflow and Function runs and evaluation runs are
+ * kept as they are now (`local-history-carry.ts`), so a change's results can be
+ * compared with the last ones, unless the baseline's are asked for
+ * (`history: 'baseline'`, `--exact`). The records those runs wrote go back.
+ *
  * The service, job engine and runner keep running: connections to the
  * database are refused for the second or two it takes (`ALLOW_CONNECTIONS
  * false`), the open ones ended (`pg_terminate_backend`), and the pools
@@ -103,6 +110,8 @@ export interface SnapshotOutcome {
   appsLost?: AppLostByRestore[]
   /** restore: the workspace secrets kept as they were before it, or `baseline` when the baseline's were put back. */
   secrets?: (SecretsCarried & { mode: 'keep' }) | { mode: 'baseline' }
+  /** restore: the run history kept as it was before it, or `baseline` when the baseline's was put back. */
+  history?: (HistoryCarried & { mode: 'keep' }) | { mode: 'baseline' }
 }
 
 /** The secrets part of a restore's line: what was kept, what has to be set again, or that the baseline's are back. */
@@ -284,11 +293,12 @@ function changedSince(baseline: string | null, current: string | null): number {
  * ended, the database dropped and made again from the baseline, the cache
  * emptied. The CLI's record of what is applied is put back with it.
  */
-export async function restoreBaseline(project: LocalProject, organizationId: string, deps: SnapshotDeps = {}, opts: { secrets?: RestoreSecrets } = {}): Promise<SnapshotOutcome> {
+export async function restoreBaseline(project: LocalProject, organizationId: string, deps: SnapshotDeps = {}, opts: { secrets?: RestoreSecrets; history?: RestoreSecrets } = {}): Promise<SnapshotOutcome> {
   const exec = deps.exec ?? execInContainer
   // A stand-in `exec` without a stand-in `query` carries nothing: tests never reach docker.
   const query = deps.query ?? (deps.exec ? undefined : queryInContainer)
   const keepSecrets = (opts.secrets ?? 'keep') === 'keep'
+  const keepHistory = (opts.history ?? 'keep') === 'keep'
   const now = deps.now ?? Date.now
   const psql = psqlFor(project, exec)
   const stored = readBaseline(project, organizationId)
@@ -299,14 +309,18 @@ export async function restoreBaseline(project: LocalProject, organizationId: str
     // The secrets as they are now, read before the database goes: configuration, kept across the restore.
     const pg = containerName(project, 'postgres')
     const held = keepSecrets && query ? readSecrets(query, pg) : null
+    // What happened since the baseline, dumped in the container: kept across the restore too.
+    const happened = keepHistory && query ? dumpHistory(query, pg) : null
     psql(refuse(POSTGRES_DB, false))
     psql(terminate(POSTGRES_DB))
     if (!psql(`DROP DATABASE ${POSTGRES_DB} WITH (FORCE)`)) {
       psql(refuse(POSTGRES_DB, true))
+      if (happened && query && !('problem' in happened)) query(pg, ['rm', '-f', happened.file])
       return { ok: false, ms: now() - started, note: `couldn’t drop ${POSTGRES_DB} to restore it; the database is as the tests left it (see \`frontera local logs postgres\`)` }
     }
     // A new database takes connections: nothing is left refused, whichever way this ends.
     if (!copyWhileHeld(psql, POSTGRES_DB, BASELINE_DB)) {
+      if (happened && query && !('problem' in happened)) query(pg, ['rm', '-f', happened.file])
       return { ok: false, ms: now() - started, note: `the database was dropped and couldn’t be made again from ${BASELINE_DB}: run \`frontera local snapshot restore\` to try again, or \`frontera local reset\`` }
     }
     // Before the cache is emptied and the service reads them: the secrets as they were.
@@ -315,6 +329,11 @@ export async function restoreBaseline(project: LocalProject, organizationId: str
       : held && query
         ? { mode: 'keep', ...('problem' in held ? { ok: false, kept: 0, notKept: [], problem: held.problem } : carrySecrets(query, pg, held)) }
         : undefined
+    const history: SnapshotOutcome['history'] = !keepHistory
+      ? { mode: 'baseline' }
+      : happened && query
+        ? { mode: 'keep', ...('problem' in happened ? { ok: false, rows: 0, notKept: 0, problem: happened.problem } : loadHistory(query, pg, happened)) }
+        : undefined
     // The service's cache holds rows of the database that was dropped.
     exec(`frontera-${project.id}-cache`, ['redis-cli', 'FLUSHALL'])
     await settle(deps)
@@ -335,9 +354,10 @@ export async function restoreBaseline(project: LocalProject, organizationId: str
     // Written last: a watching `local dev` reads it to take the record above.
     writeBaseline(project, { ...stored, restoredAt, restoreMs: ms })
     const kept = secretsWords(secrets)
+    const ran = historyWords(history)
     const lostApps = appsLostWords(appsLost)
-    const tail = `${reapply ? `; ${reapply} item${reapply === 1 ? '' : 's'} applied after the baseline will apply again on the next \`frontera local dev\`` : ''}${lostApps ? `; ${lostApps}` : ''}${kept ? `; ${kept}` : ''}`
-    const withSecrets = secrets ? { secrets } : {}
+    const tail = `${reapply ? `; ${reapply} item${reapply === 1 ? '' : 's'} applied after the baseline will apply again on the next \`frontera local dev\`` : ''}${lostApps ? `; ${lostApps}` : ''}${kept ? `; ${kept}` : ''}${ran ? `; ${ran}` : ''}`
+    const withSecrets = { ...(secrets ? { secrets } : {}), ...(history ? { history } : {}) }
     const counted = { reapply: reapply + appsLost.length, ...(appsLost.length ? { appsLost } : {}) }
     if (!answering) return { ok: false, ms, ...counted, ...withSecrets, note: `restored the database (${ms} ms), but the service isn’t answering since: see \`frontera local logs service\`${tail}` }
     return { ok: true, ms, ...counted, ...withSecrets, note: `restored the database as applied (${ms} ms)${tail}` }