@frontera-sdk/cli 1.52.38 → 1.52.40

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

@@ -0,0 +1,107 @@
+import { randomBytes } from 'node:crypto'
+
+import { POSTGRES_DB, POSTGRES_USER } from './local-env'
+
+/**
+ * The workspace secrets carried across a database restore.
+ *
+ * A restore (`frontera local snapshot restore`, `local check`'s rollback)
+ * throws away what was written since the baseline: test data. Workspace
+ * secrets are configuration, set by the person (`frontera secret set`), not
+ * by a test, so a restore keeps them as they are now unless asked to put the
+ * baseline's back (`--exact`).
+ *
+ * The rows are copied as stored, never decrypted: a value is `enc:v2`
+ * ciphertext under its workspace's data key version, and that key is a
+ * wrapped row in `workspace_deks` that only the service can unwrap. So the
+ * key versions the restored database lacks come with the secrets, and the
+ * value decrypts there exactly as before. A value under a key version the
+ * restored database holds as a different key would not decrypt: it is left
+ * as the baseline holds it and named, to be set again. Values never leave
+ * the database container as plain text, and nothing here is written to disk.
+ */
+
+export type QueryFn = (container: string, cmd: string[], input?: string) => { ok: boolean; out: string }
+
+/** What the current database holds, read before it is dropped: its workspaces, their secrets and data keys, as JSON. */
+export interface SecretsHeld {
+  json: string
+  count: number
+}
+
+export interface SecretsCarried {
+  ok: boolean
+  /** How many secrets are as they were before the restore. */
+  kept: number
+  /** Secrets whose value would not decrypt in the restored database, by name: set them again. */
+  notKept: string[]
+  /** Why nothing was carried, when it failed. */
+  problem?: string
+}
+
+const psqlArgs = (extra: string[]) => ['psql', '-U', POSTGRES_USER, '-d', POSTGRES_DB, '-v', 'ON_ERROR_STOP=1', '-q', '-At', ...extra]
+
+export const READ_SECRETS_SQL = `SELECT json_build_object(
+  'workspaces', coalesce((SELECT json_agg(id) FROM workspaces), '[]'::json),
+  'secrets', coalesce((SELECT json_agg(s) FROM workspace_secrets s), '[]'::json),
+  'deks', coalesce((SELECT json_agg(d) FROM workspace_deks d), '[]'::json))`
+
+/** The secrets and data keys as the database holds them now, or why they could not be read. */
+export function readSecrets(query: QueryFn, container: string): SecretsHeld | { problem: string } {
+  const res = query(container, psqlArgs(['-c', READ_SECRETS_SQL.replace(/\s+/g, ' ')]))
+  if (!res.ok) return { problem: 'the current secrets could not be read' }
+  try {
+    const parsed = JSON.parse(res.out) as { secrets?: unknown[] }
+    return { json: res.out, count: Array.isArray(parsed.secrets) ? parsed.secrets.length : 0 }
+  } catch {
+    return { problem: 'the current secrets could not be read' }
+  }
+}
+
+/**
+ * The SQL that puts the held secrets into the restored database, in one
+ * transaction: the data key versions it lacks are added, each workspace's
+ * secrets replaced by the held ones (a secret deleted since the baseline
+ * stays deleted), except those under a key version it holds differently.
+ * Answers one JSON line: how many were kept, and the names that weren't.
+ */
+export function carrySql(json: string, tag = `carry_${randomBytes(6).toString('hex')}`): string {
+  if (json.includes(`$${tag}$`)) throw new Error('the held secrets contain the quoting tag')
+  const q = `$${tag}$`
+  return [
+    'BEGIN;',
+    `CREATE TEMP TABLE carry ON COMMIT DROP AS SELECT ${q}${json}${q}::json AS j;`,
+    // Only workspaces both databases have: one made after the baseline is gone with it.
+    `CREATE TEMP TABLE carry_ws ON COMMIT DROP AS SELECT (value #>> '{}')::uuid AS id FROM json_array_elements((SELECT j->'workspaces' FROM carry)) WHERE (value #>> '{}')::uuid IN (SELECT id FROM workspaces);`,
+    `CREATE TEMP TABLE carry_deks ON COMMIT DROP AS SELECT * FROM json_populate_recordset(NULL::workspace_deks, (SELECT j->'deks' FROM carry)) WHERE workspace_id IN (SELECT id FROM carry_ws);`,
+    `CREATE TEMP TABLE carry_secrets ON COMMIT DROP AS SELECT * FROM json_populate_recordset(NULL::workspace_secrets, (SELECT j->'secrets' FROM carry)) WHERE workspace_id IN (SELECT id FROM carry_ws);`,
+    // A key version the restored database holds as another key: a value under it would not decrypt there.
+    `CREATE TEMP TABLE carry_skip ON COMMIT DROP AS SELECT s.workspace_id, s.name FROM carry_secrets s JOIN carry_deks c ON c.workspace_id = s.workspace_id AND s.encrypted_value LIKE 'enc:v2:dek.' || c.version || ':%' JOIN workspace_deks d ON d.workspace_id = c.workspace_id AND d.version = c.version AND d.wrapped_dek <> c.wrapped_dek;`,
+    `INSERT INTO workspace_deks SELECT c.* FROM carry_deks c WHERE NOT EXISTS (SELECT 1 FROM workspace_deks d WHERE d.workspace_id = c.workspace_id AND d.version = c.version) ON CONFLICT DO NOTHING;`,
+    `DELETE FROM workspace_secrets t WHERE t.workspace_id IN (SELECT id FROM carry_ws) AND NOT EXISTS (SELECT 1 FROM carry_skip k WHERE k.workspace_id = t.workspace_id AND k.name = t.name);`,
+    `INSERT INTO workspace_secrets SELECT s.* FROM carry_secrets s WHERE NOT EXISTS (SELECT 1 FROM carry_skip k WHERE k.workspace_id = s.workspace_id AND k.name = s.name) ON CONFLICT DO NOTHING;`,
+    `SELECT json_build_object('kept', (SELECT count(*) FROM workspace_secrets t JOIN carry_secrets s ON s.id = t.id AND s.encrypted_value = t.encrypted_value), 'notKept', coalesce((SELECT json_agg(name ORDER BY name) FROM carry_skip), '[]'::json));`,
+    'COMMIT;',
+    '',
+  ].join('\n')
+}
+
+/** Put the held secrets into the restored database (`carrySql`), and say what became of them. */
+export function carrySecrets(query: QueryFn, container: string, held: SecretsHeld): SecretsCarried {
+  let sql: string
+  try {
+    sql = carrySql(held.json)
+  } catch (err) {
+    return { ok: false, kept: 0, notKept: [], problem: (err as Error).message }
+  }
+  const res = query(container, psqlArgs(['-f', '-']), sql)
+  if (!res.ok) return { ok: false, kept: 0, notKept: [], problem: 'the restored database refused them' }
+  try {
+    const line = res.out.split('\n').map((l) => l.trim()).filter(Boolean).at(-1) ?? '{}'
+    const said = JSON.parse(line) as { kept?: number; notKept?: string[] }
+    return { ok: true, kept: Number(said.kept ?? 0), notKept: Array.isArray(said.notKept) ? said.notKept.filter((n) => typeof n === 'string') : [] }
+  } catch {
+    // Committed, but its answer could not be read: what the runtime lists says the rest.
+    return { ok: true, kept: held.count, notKept: [] }
+  }
+}

package/src/local/local-secrets.ts

@@ -115,27 +115,57 @@ export function needsValueLine(name: string, who: string): string {
 /** The build's lines for the secrets `names` that the local runtime has no value for. */
 export async function missingSecretLines(names: string[], who: string, serviceUrl: string, creds: LocalCredentials): Promise<string[]> {
   if (!names.length) return []
-  const have = await localSecretNames(serviceUrl, creds)
-  if (!have) return []
-  return names.filter((n) => !have.has(n)).map((n) => needsValueLine(n, who))
+  const presence = await localSecretPresence(serviceUrl, creds)
+  if (!presence) return []
+  return names.filter((n) => !hasSecretValue(presence, n)).map((n) => needsValueLine(n, who))
 }
 
-/** The secret names the local runtime holds (never their values); `null` when it could not say. */
-export async function localSecretNames(serviceUrl: string, creds: LocalCredentials): Promise<Set<string> | null> {
+/**
+ * What the local runtime holds of its secrets, never their values: each name
+ * the secrets list route lists, and those of them it says have no value
+ * (`hasValue: false` on a row; a runtime that does not say counts a listed
+ * secret as having one).
+ */
+export interface SecretPresence {
+  names: Set<string>
+  withoutValue: Set<string>
+}
+
+/** Whether the runtime has a value for `name`: listed, and not said to be without one. */
+export function hasSecretValue(presence: SecretPresence, name: string): boolean {
+  return presence.names.has(name) && !presence.withoutValue.has(name)
+}
+
+/** The secrets list route's answer, read as `SecretPresence`; `null` when it could not say. */
+export async function localSecretPresence(serviceUrl: string, creds: LocalCredentials, deps: { fetch?: (url: string | URL, init?: RequestInit) => Promise<Response> } = {}): Promise<SecretPresence | null> {
   if (!creds.workspaceKey || !creds.workspaceId) return null
   try {
-    const res = await fetch(new URL(`/v1/workspaces/${encodeURIComponent(creds.workspaceId)}/secrets`, serviceUrl), {
+    const res = await (deps.fetch ?? fetch)(new URL(`/v1/workspaces/${encodeURIComponent(creds.workspaceId)}/secrets`, serviceUrl), {
       headers: { authorization: `Bearer ${creds.workspaceKey}` },
+      signal: AbortSignal.timeout(5000),
     })
     if (!res.ok) return null
-    const body = (await res.json()) as { data?: Array<{ name?: string }> } | Array<{ name?: string }>
+    const body = (await res.json()) as { data?: Array<{ name?: string; hasValue?: unknown }> } | Array<{ name?: string; hasValue?: unknown }>
     const rows = Array.isArray(body) ? body : (body.data ?? [])
-    return new Set(rows.flatMap((r) => (typeof r.name === 'string' ? [r.name] : [])))
+    const names = new Set<string>()
+    const withoutValue = new Set<string>()
+    for (const r of rows) {
+      if (typeof r.name !== 'string') continue
+      names.add(r.name)
+      if (r.hasValue === false) withoutValue.add(r.name)
+    }
+    return { names, withoutValue }
   } catch {
     return null
   }
 }
 
+/** The secret names the local runtime holds a value for (never the values); `null` when it could not say. */
+export async function localSecretNames(serviceUrl: string, creds: LocalCredentials): Promise<Set<string> | null> {
+  const presence = await localSecretPresence(serviceUrl, creds)
+  return presence ? new Set([...presence.names].filter((n) => !presence.withoutValue.has(n))) : null
+}
+
 /**
  * A Plugin file as a push sends it: every header, key-like setting and
  * environment value empty, as the pull writes them. The platform keeps its

package/src/local/local-seed.ts

@@ -1,6 +1,6 @@
 import { appendFileSync } from 'node:fs'
 
-import { findProvider, getKey, keylessEmbeddings, LOCAL_PROVIDERS } from './local-keys'
+import { findProvider, getKey, LOCAL_PROVIDERS, localEmbeddingsReachable } from './local-keys'
 import type { LocalCredentials } from './local-state'
 
 /**
@@ -174,11 +174,35 @@ const EMBEDDING: Array<{ provider: string; model: string }> = [
   { provider: 'openrouter', model: 'openai/text-embedding-3-small' },
 ]
 
+/**
+ * The runtime's embedding choice, when it has one its credentials can run
+ * (`/v1/config/embedding` lists only credentialed providers): one chosen
+ * before, by `local dev` to match the workspace or by its owner, is kept.
+ */
+async function credentialedEmbedding(serviceUrl: string, token: string, orgId: string): Promise<{ provider: string; model: string } | null> {
+  try {
+    const res = await call<{ data?: EmbeddingView } & EmbeddingView>(serviceUrl, '/v1/config/embedding', { token, orgId })
+    if (res.status >= 300) return null
+    const view = res.body?.data ?? res.body
+    const { provider, model } = view ?? {}
+    if (typeof provider !== 'string' || !provider || typeof model !== 'string' || !model) return null
+    return Array.isArray(view?.providers) && view.providers.some((p) => p?.id === provider) ? { provider, model } : null
+  } catch {
+    return null
+  }
+}
+
+interface EmbeddingView {
+  provider?: string | null
+  model?: string | null
+  providers?: Array<{ id?: string }>
+}
+
 /**
  * Copy the FDE's stored keys into the local organization's credentials, and
- * pick an embedding model when one is possible. Returns what was applied, for
- * the status line; failures are logged, never fatal — a runtime without a model
- * key still starts, and says so.
+ * pick an embedding model when one is possible and none that runs is chosen
+ * yet. Returns what was applied, for the status line; failures are logged,
+ * never fatal — a runtime without a model key still starts, and says so.
  */
 export async function applyModelKeys(args: { serviceUrl: string; password: string; organizationId: string; logFile: string }): Promise<string[]> {
   const applied: string[] = []
@@ -202,33 +226,56 @@ export async function applyModelKeys(args: { serviceUrl: string; password: strin
     if (res.status >= 200 && res.status < 300) applied.push(p.id)
     else log(args.logFile, `storing the ${findProvider(p.id)?.label} key answered ${res.status}: ${JSON.stringify(res.body).slice(0, 200)}`)
   }
-  let embedding = EMBEDDING.find((e) => applied.includes(e.provider))
-  if (!embedding && keylessEmbeddings()) {
-    // A placeholder OpenAI credential: the service's OpenAI client is pointed
-    // at the local embeddings (see serviceEnv), which embed without a key.
-    const res = await call(args.serviceUrl, '/v1/admin/provider-credentials/openai', {
-      method: 'PUT',
-      token,
-      orgId: args.organizationId,
-      body: { fields: { apiKey: 'local-embeddings' } },
-    })
-    if (res.status >= 200 && res.status < 300) {
-      embedding = EMBEDDING[0]
-      applied.push('local-embeddings')
-    } else log(args.logFile, `storing the local embeddings credential answered ${res.status}: ${JSON.stringify(res.body).slice(0, 200)}`)
+  // A choice that runs with this runtime's keys stays: the workspace's model (`mirrorOrgSettings`) or the owner's.
+  // The local embeddings' stand-in OpenAI credential is not a key: a real key's model replaces it when the provider takes it.
+  const kept = await credentialedEmbedding(args.serviceUrl, token, args.organizationId)
+  const standIn = !!kept && isLocalEmbeddings(kept)
+  if (kept && !standIn) {
+    log(args.logFile, `kept the embedding model ${kept.provider} / ${kept.model}`)
+    return applied
   }
-  if (embedding) {
-    const res = await call(args.serviceUrl, '/v1/config/embedding', {
-      method: 'PUT',
-      token,
-      orgId: args.organizationId,
-      body: embedding,
-    })
-    if (res.status >= 300) log(args.logFile, `setting the embedding model answered ${res.status}: ${JSON.stringify(res.body).slice(0, 200)}`)
+  const setEmbedding = async (embedding: { provider: string; model: string }) => {
+    const res = await call(args.serviceUrl, '/v1/config/embedding', { method: 'PUT', token, orgId: args.organizationId, body: embedding })
+    if (res.status < 300) return true
+    log(args.logFile, `setting the embedding model ${embedding.provider} / ${embedding.model} answered ${res.status}: ${JSON.stringify(res.body).slice(0, 300)}`)
+    return false
+  }
+  for (const embedding of EMBEDDING.filter((e) => applied.includes(e.provider))) {
+    if (await setEmbedding(embedding)) return applied
+  }
+  if (standIn) {
+    applied.push('local-embeddings')
+    return applied
+  }
+  // No key, or the provider refused the one stored (the line above says its answer): the keyless local
+  // embeddings, so knowledge bases still ingest and search here. They need the service's OpenAI client,
+  // which points at them while this computer has no OpenAI key (see serviceEnv).
+  if (!localEmbeddingsReachable()) return applied
+  const res = await call(args.serviceUrl, '/v1/admin/provider-credentials/openai', {
+    method: 'PUT',
+    token,
+    orgId: args.organizationId,
+    body: { fields: { apiKey: LOCAL_EMBEDDINGS_CREDENTIAL } },
+  })
+  if (res.status >= 300) {
+    log(args.logFile, `storing the local embeddings credential answered ${res.status}: ${JSON.stringify(res.body).slice(0, 200)}`)
+    return applied
+  }
+  if (await setEmbedding(EMBEDDING[0]!)) {
+    applied.push('local-embeddings')
+    if (applied.some((p) => p === 'openrouter')) log(args.logFile, 'embedding with the keyless local embeddings: the stored key’s embedding model was refused (see the line above)')
   }
   return applied
 }
 
+/** The placeholder OpenAI credential that sends the service's OpenAI client to the keyless local embeddings. */
+const LOCAL_EMBEDDINGS_CREDENTIAL = 'local-embeddings'
+
+/** Whether a choice is the keyless local embeddings: OpenAI's model while this computer holds no OpenAI key. */
+export function isLocalEmbeddings(embedding: { provider: string | null; model: string | null }): boolean {
+  return embedding.provider === 'openai' && localEmbeddingsReachable()
+}
+
 /**
  * Runtimes started before the echo model was removed still list it: the
  * `local` custom provider, its `local-model` catalog entry, and that model as
@@ -273,6 +320,35 @@ export const PROVIDER_MODELS: Record<string, Array<{ slug: string; modelId: stri
     { slug: 'gemini-3-8-flash', modelId: 'google/gemini-3.8-flash', name: 'Gemini 3.8 Flash' },
     { slug: 'gpt-5-6-terra', modelId: 'openai/gpt-5.6-terra', name: 'GPT-5.6 Terra' },
   ],
+  // Direct from Anthropic, beside OpenRouter's: a stored Anthropic key runs Claude without OpenRouter's
+  // credit. Their slugs name the provider, so they never take the OpenRouter models' slugs.
+  anthropic: [
+    { slug: 'anthropic-claude-haiku-5-5', modelId: 'claude-haiku-5-5', name: 'Claude Haiku 5.5 (Anthropic)' },
+    { slug: 'anthropic-claude-sonnet-5-5', modelId: 'claude-sonnet-5-5', name: 'Claude Sonnet 5.5 (Anthropic)' },
+  ],
+}
+
+/** A model the local catalog offers directly from a provider (not through OpenRouter), and that provider. */
+export interface DirectModel {
+  slug: string
+  name: string
+  provider: string
+  providerLabel: string
+}
+
+/**
+ * The first model offered directly by a provider whose key the runtime holds
+ * (`providers`: the ids the runtime applied keys for, never a key), other than
+ * the provider that refused (`refusedBy`); null when there is none. What a
+ * credit refusal suggests switching to.
+ */
+export function directModelFor(providers: readonly string[] | undefined, refusedBy?: string | null): DirectModel | null {
+  for (const [provider, models] of Object.entries(PROVIDER_MODELS)) {
+    if (provider === 'openrouter' || provider === refusedBy || !providers?.includes(provider) || !models.length) continue
+    const m = models[0]!
+    return { slug: m.slug, name: m.name.replace(/\s*\([^)]*\)$/, ''), provider, providerLabel: findProvider(provider)?.label ?? provider }
+  }
+  return null
 }
 
 /**

package/src/local/local-stand-ins.ts

@@ -34,7 +34,7 @@ import { rows } from './local-sync-remote'
  * - **Documentation** (Frontera's documentation for Agents): its stand-in
  *   `serves: "documentation"`, answering the plugin's tools from the
  *   documentation `local start` copied for the runtime's release (the same
- *   copy `frontera local docs-mcp` serves the project's coding agents). The
+ *   copy `frontera mcp` serves the project's coding agents). The
  *   Agent's documentation tools work here.
  * - **Analytics**: the workspace's analytics tools read its analytics
  *   project, which a local runtime does not have (design §8). The pull

package/src/local/local-state.ts

@@ -1,6 +1,7 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
 import { join } from 'node:path'
 
+import { ignoreInFronteraDir } from '../project-context'
 import { writeFileAtomic } from '../fs-atomic'
 import type { LocalProject } from './local-project'
 
@@ -88,8 +89,8 @@ export function ensureStateDir(project: LocalProject): void {
   } catch {
     // Best effort; a filesystem without modes still works.
   }
-  const ignore = join(project.root, '.frontera', '.gitignore')
-  if (!existsSync(ignore)) writeFileAtomic(ignore, 'local/\n', 0o644)
+  // The runtime's state, and which profile this machine bound the directory to, stay out of git.
+  ignoreInFronteraDir(project.root, ['local/'])
 }
 
 export function readState(project: LocalProject): LocalState | null {
@@ -163,3 +164,43 @@ export function readApplied(project: LocalProject): LastApplied | null {
     return null
   }
 }
+
+/**
+ * An apply under way: `local dev` writes it as it starts applying what is
+ * queued and removes it when the queue is done, so Forge and Studio say
+ * "Applying…" rather than show a half-made count as if it were the result.
+ */
+export interface ApplyingNow {
+  /** When this round of applies began. */
+  since: string
+  /** How many items were queued when it began. */
+  queued: number
+  /** The `local dev` applying them: a record whose process is gone is stale. */
+  pid: number
+  /** What started it, in words: "runtime started", "files changed: agents/desk/agent.json". */
+  trigger?: string
+}
+
+function applyingPath(project: LocalProject): string {
+  return join(project.stateDir, 'applying.json')
+}
+
+/** Say an apply is under way (`entry`), or that it is done (`null`). Never throws. */
+export function recordApplying(project: LocalProject, entry: ApplyingNow | null): void {
+  try {
+    if (entry) writeFileAtomic(applyingPath(project), `${JSON.stringify(entry)}\n`, 0o644)
+    else rmSync(applyingPath(project), { force: true })
+  } catch {
+    // A missed hint must never fail an apply.
+  }
+}
+
+/** The apply under way, or null: none, or its `local dev` is gone. */
+export function readApplying(stateDir: string): ApplyingNow | null {
+  try {
+    const entry = JSON.parse(readFileSync(join(stateDir, 'applying.json'), 'utf8')) as ApplyingNow
+    return entry && typeof entry.since === 'string' && isAlive(entry.pid) ? entry : null
+  } catch {
+    return null
+  }
+}

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

@@ -5,11 +5,15 @@ import { extname, join, normalize } from 'node:path'
 import type { LocalProject } from './local-project'
 import { AgentFileError, saveAgentEdit, type AgentFileEdit } from './local-agent-files'
 import { solutionStatus } from './local-applied'
+import { appCodeStates } from './local-apps'
 import { projectBlueprintOutline } from './local-blueprint-outline'
-import { itemBuild } from './local-build-summary'
-import { logPath, readApplied, readState, type ComponentName } from './local-state'
-import { appendTestCase, renderTestCase } from './local-test-cases'
+import { currentBuildRows, currentBuildSummary } from './local-build-inputs'
+import { appStatusRow, itemBuild } from './local-build-summary'
+import { KnowledgeDocumentError, KNOWLEDGE_UPLOAD_EXTENSIONS, MAX_KNOWLEDGE_UPLOAD_BYTES, checkUpload, documentInFolder, knowledgeFolderOf, projectDocuments, removeKnowledgeDocument, removeRuntimeCopies, runtimeDocuments, saveKnowledgeDocument, type ServiceCall } from './local-knowledge-uploads'
+import { isAlive, logPath, readApplied, readState, type ComponentName } from './local-state'
+import { appendTestCase, decisionOfApprovals, MIXED_DECISIONS_LINE, noteRedactedVariables, redactedVariablesLine, redactedVariablesOfTimeline, renderTestCase, variablesOfTimeline } from './local-test-cases'
 import { findCaseFiles } from './local-test-runner'
+import { workflowTestListing } from './local-workflow-tests'
 import { createTestRuns } from './local-test-runs'
 import { docsCopyPath } from './local-docs'
 import { standInMcp } from './local-stand-ins'
@@ -62,6 +66,16 @@ export function newSessionToken(): string {
   return randomBytes(24).toString('base64url')
 }
 
+/** An Agent's display name from `agents/<slug>/agent.json` (`config.name`), or null when it gives none. */
+export function agentFileName(root: string, slug: string): string | null {
+  try {
+    const name = (JSON.parse(readFileSync(join(root, 'agents', slug, 'agent.json'), 'utf8')) as { config?: { name?: unknown } }).config?.name
+    return typeof name === 'string' && name.trim() ? name.trim() : null
+  } catch {
+    return null
+  }
+}
+
 function sameToken(a: string, b: string): boolean {
   const ab = Buffer.from(a)
   const bb = Buffer.from(b)
@@ -95,7 +109,7 @@ export function startStudioServer(opts: StudioServerOptions) {
   const json = (data: unknown, status = 200) =>
     new Response(JSON.stringify(data), { status, headers: { 'content-type': 'application/json; charset=utf-8' } })
 
-  const localRoute = (url: URL): Response => {
+  const localRoute = (url: URL): Response | Promise<Response> => {
     if (url.pathname === '/__local/state') {
       const state = readState(project)
       if (!state) return json({ error: 'no local runtime state' }, 404)
@@ -125,6 +139,36 @@ export function startStudioServer(opts: StudioServerOptions) {
       if (!/^[a-z-]+\/[A-Za-z0-9][\w./-]{0,200}$/.test(ref)) return json({ error: 'name an item, as agent/<slug>' }, 400)
       return json({ build: itemBuild(project.root, ref, project.id) })
     }
+    // The build in a few numbers, counted as `local status` counts it (the runtime's Action deployments and
+    // secrets read the same way): Studio's footer says its failures, the number `local status` prints.
+    if (url.pathname === '/__local/build-summary') {
+      return currentBuildSummary(project.root, project.id, readState(project)).then((summary) =>
+        json({ summary: summary ? { problems: summary.problems, counts: summary.counts, headline: summary.headline } : null }),
+      )
+    }
+    // The build's rows of one kind (`?kind=function`), each with its state, reason and fix, as `local status` lists
+    // them: Studio's lists mark the ones that didn't apply or need setup, with the same words.
+    if (url.pathname === '/__local/builds') {
+      const kind = url.searchParams.get('kind') ?? ''
+      if (!/^[a-zA-Z-]{1,40}$/.test(kind)) return json({ error: 'name a kind, as function' }, 400)
+      return currentBuildRows(project.root, project.id, readState(project)).then((rows) =>
+        json({
+          rows: (rows ?? [])
+            .filter((r) => r.ref.startsWith(`${kind}/`))
+            .map((r) => ({ ref: r.ref, state: r.state, label: r.label, reason: r.reason, fix: r.fix ?? null, ...(r.warnings?.length ? { warnings: r.warnings } : {}) })),
+        }),
+      )
+    }
+    // Where each Custom App's code is (its folder, not pulled, or none yet), with its one status as `local status` says
+    // it (deployed to this runtime, built, not built, no code): Studio's Apps page says it, and how to work on it.
+    if (url.pathname === '/__local/apps') {
+      return json({
+        apps: appCodeStates(project.root).map((code) => {
+          const row = appStatusRow(project.root, code)
+          return { ...code, status: row.appStatus, label: row.label, fix: row.fix ?? null }
+        }),
+      })
+    }
     // The Blueprint's definitions as the files state them, so they show before anything is applied.
     if (url.pathname === '/__local/blueprint') {
       return json({ objectTypes: projectBlueprintOutline(project.root) })
@@ -132,11 +176,17 @@ export function startStudioServer(opts: StudioServerOptions) {
     // The solution's saved cases (`agents/<slug>/evals/*.yaml`), read fresh each time.
     if (url.pathname === '/__local/test-cases') {
       try {
-        return json({ files: findCaseFiles(project.root) })
+        // Each Agent by the name its agent.json gives it, as the home and Agents say it, not its folder.
+        return json({ files: findCaseFiles(project.root).map((f) => ({ ...f, agentName: agentFileName(project.root, f.agent) })) })
       } catch (err) {
         return json({ error: `a case file could not be read: ${(err as Error).message}` }, 422)
       }
     }
+    // The workflows' test files (`workflows/tests/*.yaml`): `frontera local test` runs them; Evaluations lists them.
+    if (url.pathname === '/__local/workflow-tests') {
+      // Each case by name, with its last run (`frontera local test` keeps it), so Evaluations lists them.
+      return json({ files: workflowTestListing(project.root, project.stateDir) })
+    }
     if (url.pathname === '/__local/test-runs') return json({ runs: testRuns.list() })
     const runMatch = /^\/__local\/test-runs\/([0-9a-f-]+)$/.exec(url.pathname)
     if (runMatch) {
@@ -171,10 +221,122 @@ export function startStudioServer(opts: StudioServerOptions) {
       const agent = (await get(`/v1/config/agents/${encodeURIComponent(body.agentId)}`)) as { agentId?: string }
       const messages = (await get(`/v1/sessions/${encodeURIComponent(body.conversationId)}/messages`)) as unknown
       const list = Array.isArray(messages) ? messages : ((messages as { messages?: unknown[] })?.messages ?? [])
-      const yaml = renderTestCase({ conversationId: body.conversationId, messages: list as never[], savedAt: new Date().toISOString() })
+      // The variables the conversation started with, when its Test setup recorded them: the case replays as the same customer.
+      const session = (await get(`/v1/config/agents/${encodeURIComponent(body.agentId)}/try/conversations/${encodeURIComponent(body.conversationId)}/session`).catch(() => null)) as { timeline?: Array<{ payload?: Record<string, unknown> | null }> } | null
+      const variables = variablesOfTimeline(session?.timeline ?? [])
+      // A sensitive variable is named in the setup, never its value: the case says to fill it in by hand.
+      const redacted = redactedVariablesOfTimeline(session?.timeline ?? [])
+      // The tool approvals it stopped on, as the person decided them: the case answers them the same way.
+      const cards = (await get(`/v1/chat/approvals?conversationId=${encodeURIComponent(body.conversationId)}`).catch(() => [])) as unknown
+      const { decision, mixed } = decisionOfApprovals(Array.isArray(cards) ? cards : [])
+      const yaml = noteRedactedVariables(renderTestCase({ conversationId: body.conversationId, messages: list as never[], savedAt: new Date().toISOString(), ...(variables ? { variables } : {}), ...(decision ? { decision } : {}) }), redacted)
       const path = appendTestCase(project.root, agent.agentId ?? body.agentId, yaml)
-      return json({ path })
+      const notes = [...(redacted.length ? [redactedVariablesLine(redacted, path)] : []), ...(mixed ? [MIXED_DECISIONS_LINE] : [])]
+      return json({ path, ...(decision ? { decision } : {}), ...(redacted.length ? { redactedVariables: redacted } : {}), ...(notes.length ? { note: notes.join(' ') } : {}) })
+    } catch (err) {
+      return json({ error: (err as Error).message }, 502)
+    }
+  }
+
+  /** The local service as the seeded owner, for the routes that act on the runtime themselves; null before it is seeded. */
+  const serviceCall = (): ServiceCall | null => {
+    const creds = readState(project)?.credentials
+    const bearer = creds?.session ?? creds?.workspaceKey
+    if (!creds || !bearer) return null
+    return async (method, path) => {
+      const res = await fetch(new URL(path, opts.serviceUrl), { method, headers: { authorization: `Bearer ${bearer}`, 'x-org-id': creds.organizationId, 'x-workspace-id': creds.workspaceId } })
+      const text = await res.text()
+      if (!res.ok) throw new Error(`the runtime answered ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}`)
+      return text ? (JSON.parse(text) as unknown) : null
+    }
+  }
+
+  /** Whether a `local dev` watcher is applying this project's saved files (Forge keeps one running). */
+  const watching = (): boolean => {
+    try {
+      return isAlive(Number(readFileSync(join(project.stateDir, 'dev.pid'), 'utf8').trim()))
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * A knowledge base's documents as the project's files (`local-knowledge-uploads.ts`):
+   *   GET    /__local/knowledge?base=<name>&id=<knowledge id>   its folder, its documents and whether the runtime has each, its apply state
+   *   POST   /__local/knowledge/documents?base=&id=[&replace=1] save one document (multipart `file`) into its folder
+   *   DELETE /__local/knowledge/documents?base=&id=&sourceId=   take a document off the runtime and out of the folder
+   */
+  const knowledgeRoute = async (req: Request, url: URL): Promise<Response> => {
+    const base = (url.searchParams.get('base') ?? '').trim()
+    const id = url.searchParams.get('id') ?? ''
+    if (!base || base.length > 200) return json({ error: 'name the knowledge base, as base=<name>' }, 400)
+    if (id && !/^[\w-]{1,80}$/.test(id)) return json({ error: 'id is not a knowledge base id' }, 400)
+    const folder = knowledgeFolderOf(project.root, base)
+    try {
+      if (url.pathname === '/__local/knowledge' && req.method === 'GET') {
+        const accepted = { extensions: KNOWLEDGE_UPLOAD_EXTENSIONS, maxBytes: MAX_KNOWLEDGE_UPLOAD_BYTES }
+        if (!folder) return json({ folder: null, documents: [], apply: null, watching: watching(), accepted })
+        const call = id ? serviceCall() : null
+        const onRuntime = call ? await runtimeDocuments(call, id).then((docs) => new Set(docs.map((d) => d.path)), () => null) : null
+        const status = solutionStatus(project, readState(project)?.credentials?.organizationId ?? null, (t) => t.kind === 'knowledge' && t.name === folder)[0]
+        return json({
+          folder: `knowledge/${folder}/`,
+          documents: projectDocuments(project.root, folder, onRuntime),
+          apply: status ? { state: status.state, ...(status.detail ? { detail: status.detail } : {}), ...(status.fix ? { fix: status.fix } : {}), ...(status.waiting ? { waiting: true } : {}) } : null,
+          watching: watching(),
+          accepted,
+        })
+      }
+      if (url.pathname !== '/__local/knowledge/documents') return json({ error: 'not found' }, 404)
+      if (req.method === 'POST') {
+        if (!folder) return json({ error: `${base} has no folder in the project (knowledge/<name>/knowledge.json), so a document can't be saved to it here` }, 404)
+        // Refused before the body is read: the form's boundary and fields add little beyond the file.
+        if (Number(req.headers.get('content-length') ?? 0) > MAX_KNOWLEDGE_UPLOAD_BYTES + 64 * 1024) {
+          return json({ error: `the document is larger than ${MAX_KNOWLEDGE_UPLOAD_BYTES / 1024 / 1024} MB, the most a knowledge base takes` }, 413)
+        }
+        const form = await req.formData().catch(() => null)
+        const file = form?.get('file')
+        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).
+        if (replace && id && documentInFolder(project.root, folder, name)) {
+          const call = serviceCall()
+          if (call) {
+            try {
+              await removeRuntimeCopies(call, id, name)
+            } catch (err) {
+              return json({ error: `the runtime's copy of ${name} couldn't be taken off (${(err as Error).message}), so knowledge/${folder}/${name} is left as it was` }, 502)
+            }
+          }
+        }
+        const saved = saveKnowledgeDocument(project.root, folder, name, new Uint8Array(await file.arrayBuffer()), { replace })
+        return json({ ...saved, watching: watching() })
+      }
+      if (req.method === 'DELETE') {
+        const sourceId = url.searchParams.get('sourceId') ?? ''
+        if (!id || !/^[\w-]{1,80}$/.test(sourceId)) return json({ error: 'name the document, as id=<knowledge id>&sourceId=<document id>' }, 400)
+        const call = serviceCall()
+        if (!call) return json({ error: 'the runtime is not seeded yet' }, 409)
+        const source = (await runtimeDocuments(call, id)).find((d) => d.id === sourceId)
+        if (!source) return json({ error: 'the runtime has no such document in this knowledge base' }, 404)
+        await call('DELETE', `/v1/workspace-knowledge/${encodeURIComponent(id)}/sources/${encodeURIComponent(sourceId)}`)
+        // Its file too, so the next apply does not upload it again; a base with no folder had only the runtime's copy.
+        // A runtime document of a kind or name the folder can't hold (a spreadsheet uploaded on the runtime) has no file to remove.
+        const removed = (() => {
+          if (!folder) return { path: null, removed: false }
+          try {
+            return removeKnowledgeDocument(project.root, folder, source.path)
+          } catch (err) {
+            if (err instanceof KnowledgeDocumentError && err.status !== 409) return { path: null, removed: false }
+            throw err
+          }
+        })()
+        return json({ path: removed.path, removedFile: removed.removed })
+      }
+      return json({ error: 'not found' }, 404)
     } catch (err) {
+      if (err instanceof KnowledgeDocumentError) return json({ error: err.message, ...err.extra }, err.status)
       return json({ error: (err as Error).message }, 502)
     }
   }
@@ -316,6 +478,7 @@ export function startStudioServer(opts: StudioServerOptions) {
         const started = testRuns.start({ agent: typeof body.agent === 'string' ? body.agent : undefined, live: body.live === true })
         return 'run' in started ? json(started.run, 202) : json({ error: started.error }, started.status)
       }
+      if (url.pathname === '/__local/knowledge' || url.pathname === '/__local/knowledge/documents') return knowledgeRoute(req, url)
       if (url.pathname.startsWith('/__local/')) return localRoute(url)
       // `/api/…` is the service; `/api` alone is Studio's API page.
       if (url.pathname.startsWith('/api/')) return proxy(req, url)