@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/commands/local/docs-mcp.ts

@@ -1,16 +1,13 @@
-import { docsCopyPath, serveDocsMcp } from '../../local/local-docs'
 import { localProject } from '../../local/local-project'
-import { cliSchema, readKeptSchema } from '../../local/local-schemas'
+import { serveMcp } from '../../mcp/mcp-protocol'
+import { MCP_INFO, mcpTools } from '../../mcp/mcp-server'
 import type { Command } from '../types'
 
 /**
- * Frontera's documentation as an MCP server on stdio, for the coding agents
- * working in this project. `local init` registers it in `.mcp.json` (Claude
- * Code) and `.cursor/mcp.json`; Codex takes the same command. It reads the
- * documentation `local start` copied for the release the runtime runs, and
- * the formats of the project's files that start kept, so it needs no key and
- * keeps working while the runtime is stopped. Nothing but protocol goes to
- * stdout.
+ * The earlier name of `frontera mcp`, kept for one release so projects
+ * registered with `frontera-docs` keep their documentation tools. It serves
+ * the same server; Forge's Set up agents and `local init` now register
+ * `frontera mcp` instead.
  */
 export const localDocsMcp: Command = {
   meta: {
@@ -18,19 +15,14 @@ export const localDocsMcp: Command = {
     verb: 'docs-mcp',
     args: [],
     flags: {},
-    summary: "Serve Frontera's documentation to coding agents over MCP (stdio), for the local runtime's release",
-    examples: ['frontera local docs-mcp'],
+    summary: 'Deprecated: the same server as `frontera mcp`',
+    examples: ['frontera mcp'],
     offline: true,
     internal: true,
   },
   async run(ctx) {
-    const project = localProject(ctx.cwd)
-    // Not started yet: it still speaks MCP, and each tool call says what to do.
-    await serveDocsMcp({
-      docsPath: docsCopyPath(project),
-      schemaFor: (kind) => cliSchema(kind) ?? readKeptSchema(project, kind),
-    })
-    // The stream is the protocol: exit here, before the CLI renders a result onto it.
+    process.stderr.write('frontera local docs-mcp is deprecated: register `frontera mcp` instead (Forge: Set up agents).\n')
+    await serveMcp({ info: MCP_INFO, tools: mcpTools(localProject(ctx.cwd)) })
     process.exit(0)
   },
 }

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

@@ -3,12 +3,23 @@ import { existsSync, readFileSync, rmSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 
 import { CliError, UsageError } from '../../errors'
+import { EXIT } from '../../exit'
 import { writeFileAtomic } from '../../fs-atomic'
 import { solutionStatus } from '../../local/local-applied'
+import type { LiveAction } from '../../local/local-actions'
+import type { LiveApp } from '../../local/local-app-runtime'
+import { runtimeBuildInputs } from '../../local/local-build-inputs'
+import { listPersonas, type LocalPersona } from '../../local/local-personas'
+import type { SecretPresence } from '../../local/local-secrets'
+import { findObjectSet, normalizeObjectSets, projectObjectSetNames } from '../../blueprint/object-sets'
+import { actionsStatusText, appsStatusText, buildStatusText, emptyKnowledgeLines, itemKindsText, notPulledLines, objectSetsStatusText, projectBuildRows, projectBuildSummary, projectFilesLines } from '../../local/local-build-summary'
+import { inheritedActionWarnings } from '../../local/local-check-inherited'
+import { checkoutVersion, docsStatus, versionAtStart } from '../../local/local-docs'
 import { dockerAvailable } from '../../local/local-docker'
+import { downPhase, downToRestart, liveComponents, type DownComponent } from '../../local/local-component-health'
 import { readConfig, writeConfig, type LocalConfig } from '../../local/local-env'
 import { configuredProviders } from '../../local/local-keys'
-import { claimPorts, isPortFree, portHolder, releasePorts } from '../../local/local-ports'
+import { claimPortBlock, claimPorts, isPortFree, portHolder, reclaimedNote, releasePorts } from '../../local/local-ports'
 import { localProject, type LocalProject } from '../../local/local-project'
 import {
   destroyRuntimeData,
@@ -22,21 +33,35 @@ import {
 } from '../../local/local-control'
 import { clearState, ensureStateDir, isAlive, logPath, readState, type ComponentName, type LocalState } from '../../local/local-state'
 import { newSessionToken } from '../../local/local-studio-server'
+import { migrateMcpConfigs } from '../../local/local-scaffold'
 import { DEFAULT_REGISTRY, runSupervisor } from '../../local/local-supervisor'
-import { findCaseFiles, runCases } from '../../local/local-test-runner'
+import { compareWithLastRun, readLastRun, recordRun } from '../../local/local-test-baseline'
+import { agentFilesProblem, caseConcurrency, caseCount, runCases, selectCaseFiles, waitedWords, type CaseFile, type CaseResult } from '../../local/local-test-runner'
+import { devServerLine, listDevServers, stopDevServers } from '../../mcp/mcp-apps'
+import { caseTraces, evidenceLine, failingCaseEvidence } from '../../local/local-case-evidence'
+import { notRunGroups, notRunWords } from '../../local/local-case-not-run'
+import { findWorkflowTestFiles, recordWorkflowTestRun, runWorkflowTests, workflowFileState, type WorkflowTestFile, type WorkflowTestResult } from '../../local/local-workflow-tests'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
 import { localCheck } from './check'
+import { projectNotices } from '../../local/local-project-notices'
+import { readBaseline } from '../../local/local-db-snapshot'
+import { stuckKnowledge } from '../../local/local-knowledge-ingestion'
+import { orphanLine, projectOrphans } from '../../local/local-orphans'
 import { localData } from './data'
+import { localSdkRefresh } from './sdk-refresh'
 import { localDev } from './dev'
 import { localDocsMcp } from './docs-mcp'
 import { localInit } from './init'
 import { localKeyList, localKeyRemove, localKeySet } from './key'
 import { localModelAdd, localModelDefault, localModelRemove, localModelsAvailable, localProviderAdd, localProviderRemove, localProviders } from './providers'
+import { localRemove } from './remove'
 import { localSchema } from './schema'
 import { localSync } from './sync'
+import { keylessEmbeddingsStatus, KEYLESS_RETRIEVAL_NOTE } from '../../local/local-org-settings'
+import { withFix } from '../../local/fix-words'
 
 /**
- * `frontera local …`: Frontera's runtimes on this machine, for internal FDEs.
+ * `frontera local …`: Frontera's runtimes on this machine, for FDEs and the coding agents working with them.
  *
  * Modelled on `supabase start`: one command brings up only the runtimes a
  * solution needs (no product UI, no kernel), seeds an owner, organization,
@@ -49,7 +74,7 @@ const OPTIONAL: ComponentName[] = ['jobs', 'runner', 'storage']
 
 const sessionFile = (project: LocalProject) => join(project.stateDir, 'studio-session')
 
-function readSession(project: LocalProject): string | null {
+export function readSession(project: LocalProject): string | null {
   const path = sessionFile(project)
   return existsSync(path) ? readFileSync(path, 'utf8').trim() : null
 }
@@ -68,13 +93,15 @@ function studioUrl(state: LocalState, project: LocalProject): string {
   return `http://127.0.0.1:${state.ports.studio}/${token ? `?token=${token}` : ''}`
 }
 
-const DOT: Record<string, string> = { running: '●', starting: '◐', off: '○', stopped: '○', failed: '✕' }
+const DOT: Record<string, string> = { running: '●', starting: '◐', off: '○', stopped: '○', failed: '✕', down: '✕' }
 
-function renderStatus(state: LocalState, project: LocalProject, profile?: { profile: string; bound: boolean }): string {
+function renderStatus(state: LocalState, project: LocalProject, profile?: { profile: string; bound: boolean }, live: ReadonlyMap<string, LiveAction> | null = null, setIds: Record<string, string> | null = null, personas: LocalPersona[] | null = null, secrets: SecretPresence | null = null, liveApps: ReadonlyMap<string, LiveApp> | null = null, down: DownComponent[] = []): string {
   const lines: string[] = []
-  const phase = state.supervisorPid && !isAlive(state.supervisorPid) && state.phase !== 'stopped' ? 'stopped (supervisor exited)' : state.phase
+  // What is down now (`liveComponents`), not what the state file said at start: a container can exit under the supervisor.
+  const phase = state.supervisorPid && !isAlive(state.supervisorPid) && state.phase !== 'stopped' ? 'stopped (supervisor exited)' : down.length ? downPhase(down) : state.phase
   lines.push(`Frontera local runtime · ${project.root.split('/').pop()} · ${phase}`)
   if (state.error) lines.push(`  ${state.error}`)
+  if (down.length) lines.push('  Reads and writes fail until it is back: `frontera local start` restarts what is down and keeps the data')
   lines.push('')
   if (state.phase === 'ready') {
     lines.push(`  Studio       ${studioUrl(state, project)}`)
@@ -88,8 +115,11 @@ function renderStatus(state: LocalState, project: LocalProject, profile?: { prof
   }
   for (const c of state.components) {
     const where = c.kind === 'container' ? 'container' : c.kind === 'process' ? 'process' : 'supervisor'
-    lines.push(`  ${DOT[c.status] ?? '·'} ${c.name.padEnd(9)} ${c.status.padEnd(9)} ${c.status === 'off' ? (c.detail ?? '') : where}${c.status === 'failed' && c.detail ? ` — ${c.detail}` : ''}`)
+    const status = down.some((d) => d.name === c.name) ? 'down' : c.status
+    lines.push(`  ${DOT[status] ?? '·'} ${c.name.padEnd(9)} ${status.padEnd(9)} ${c.status === 'off' ? (c.detail ?? '') : where}${c.status === 'failed' && c.detail ? ` — ${c.detail}` : ''}`)
   }
+  const cache = down.find((d) => d.name === 'cache')
+  if (cache) lines.push(`  ✕ ${'cache'.padEnd(9)} ${'down'.padEnd(9)} container — ${cache.why}; \`frontera local start\` brings it back`)
   if (state.credentials) {
     lines.push('')
     lines.push(`  Signed in as ${state.credentials.email}`)
@@ -99,21 +129,64 @@ function renderStatus(state: LocalState, project: LocalProject, profile?: { prof
         ? `  CLI profile  ${name} — this directory is bound to another profile; pass \`--profile ${name}\``
         : `  CLI profile  ${name} (this directory uses it)`,
     )
-    lines.push(`  Blueprint    pass \`--profile ${name}-org\` (Blueprint commands need an organization key)`)
+    lines.push(
+      profile?.bound === false
+        ? `  Org profile  ${name}-org — pass \`--profile ${name}-org\` to Blueprint and Action commands`
+        : `  Org profile  ${name}-org (Blueprint and Action commands here use it)`,
+    )
     const files = solutionStatus(project, state.credentials.organizationId)
-    if (files.length) {
-      const behind = files.filter((f) => f.state !== 'applied')
-      lines.push(
-        behind.length
-          ? `  Project      ${behind.length} of ${files.length} files not on the runtime (${behind.map((f) => f.name).join(', ')}) — run \`frontera local dev\``
-          : `  Project      all ${files.length} files applied`,
-      )
+    if (files.length) lines.push(...projectFilesLines(files))
+    // Counted over the same rows it lists: the problems by name, under the line.
+    const build = projectBuildSummary(project.root, project.id, live, secrets, liveApps)
+    if (build) {
+      lines.push(`  Build        ${buildStatusText(build)}`)
+      // Each setting that differs from the workspace: what it changes when testing here, and whether it can be aligned.
+      for (const d of build.settingDetails) lines.push(`  Setting      ${d.line}${d.effect ? `: ${d.effect}` : ''}${d.align ? ` (${d.align.charAt(0).toLowerCase()}${d.align.slice(1)})` : ''}`)
+      const rows = projectBuildRows(project.root, project.id, live, setIds, secrets, liveApps) ?? []
+      for (const row of rows.filter((r) => r.state === 'failed' || r.state === 'blocked').slice(0, 12)) {
+        lines.push(`    ✕ ${row.ref} ${row.state}${row.reason ? `: ${row.reason}` : ''}`)
+        if (row.fix) lines.push(`      fix: ${row.fix}`)
+      }
+      // Applied, but naming a secret this runtime has no value for: it fails when used.
+      for (const row of rows.filter((r) => r.state === 'needs-setup').slice(0, 12)) lines.push(`    ! ${row.ref} needs setup${row.reason ? `: ${row.reason}` : ''}`)
+      // Each kind the build counts, so the line above adds up: `--json` lists every row.
+      lines.push(`  Items        ${itemKindsText(rows)}`)
+      lines.push(`  Actions      ${actionsStatusText(rows)}`)
+      const sets = objectSetsStatusText(rows)
+      if (sets) lines.push(`  Object sets  ${sets}`)
+      if (personas?.length) lines.push(`  Personas     ${personas.map((p) => `${p.key} (${p.displayName})`).join(', ')}: act as one with \`--as <key>\` on action available, submit, approve and reject`)
+      const apps = appsStatusText(rows)
+      if (apps) lines.push(`  Apps         ${apps}`)
+      // A knowledge base an Agent finds nothing in, and what the workspace has that was never pulled: each with its command.
+      for (const k of emptyKnowledgeLines(rows)) lines.push(`  Knowledge    ${k}`)
+      for (const n of notPulledLines(project.root)) lines.push(`  Not pulled   ${n}`)
+      // What the pull couldn't bring and why, App code on the platform, older sample data or SDK: each with its command.
+      const notices = projectNotices(project.root)
+      for (const n of [...notices.pull, ...(notices.agentNotes ?? [])]) lines.push(`  Pull note    ${n}`)
+      for (const n of notices.apps) lines.push(`  App code     ${n}`)
+      if (notices.sampleData) lines.push(`  Sample data  ${notices.sampleData}`)
+      if (notices.sdk) lines.push(`  SDK          ${notices.sdk}`)
+      for (const n of notices.agents) lines.push(`  Agent tools  ${n}`)
+      // An Agent whose bound Functions or workflows failed to apply: it runs without them here.
+      for (const row of rows) for (const w of row.warnings ?? []) if (/^agent\/[\w-]+: missing tools:/.test(w)) lines.push(`  Agent tools  ${w}`)
+      // A governed Action deployed as the workspace runs it, with what its owner fixes there.
+      for (const w of inheritedActionWarnings(rows)) lines.push(`  Action       ${w}`)
+      for (const n of notices.workflows) lines.push(`  Workflow     ${n}`)
     }
   }
+  const docs = docsStatus(project, { mode: state.mode, platformVersion: state.platformVersion, platformSource: readConfig(project)?.platformSource })
+  lines.push(`  Docs         ${docs.present ? `${docs.version ?? 'unknown version'}${docs.builtAt ? `, built ${docs.builtAt.slice(0, 10)}` : ''}${docs.note ? ` — ${docs.note}` : ''}` : docs.note}`)
   const providers = configuredProviders()
   lines.push(`  Model keys   ${providers.length ? providers.join(', ') : 'none — run `frontera local key-set <provider>`'}`)
   if (state.credentials?.modelProviders?.includes('local-embeddings')) {
-    lines.push('  Embeddings   local: words hashed into vectors, no key (an OpenAI or OpenRouter key replaces it)')
+    // With an OpenRouter key stored, the local embeddings mean the provider refused it for embeddings at start.
+    lines.push(
+      providers.includes('openrouter')
+        ? '  Embeddings   local: words hashed into vectors, because OpenRouter refused this computer’s key for its embedding model at start (`frontera local logs service` shows its answer after `[embedding] preflight failed`); `frontera local key-set openrouter` with a key it takes replaces them'
+        : '  Embeddings   local: words hashed into vectors, no key (an OpenAI or OpenRouter key replaces it)',
+    )
+    // What that does to knowledge search, and what gives the platform's: said where an agent reads the runtime first.
+    lines.push(`  Knowledge    ${KEYLESS_RETRIEVAL_NOTE.charAt(0).toUpperCase()}${KEYLESS_RETRIEVAL_NOTE.slice(1)}`)
   }
   return lines.join('\n')
 }
@@ -141,11 +214,26 @@ function parseList(raw: string | undefined): ComponentName[] {
 
 async function start(ctx: CommandContext): Promise<{ data: unknown; text: string }> {
   const project = localProject(ctx.cwd)
+  // Coding-agent configs from before `frontera mcp` launched the documentation server alone.
+  for (const file of migrateMcpConfigs(project.root)) ctx.output.note(`  ${file}: now launches \`frontera mcp\` (was \`frontera local docs-mcp\`)`)
   const existing = readState(project)
-  if (existing?.supervisorPid && isAlive(existing.supervisorPid) && existing.phase !== 'stopped') {
+  // Up, or partly up: what is down (a container that exited under it, a process that crashed) is brought back.
+  const restart = existing ? await downToRestart(existing) : null
+  if (existing && !restart && existing.supervisorPid && isAlive(existing.supervisorPid) && existing.phase !== 'stopped') {
     const profile = existing.credentials ? await registerLocalProfile(project, existing) : undefined
     return { data: existing, text: `Already running.\n\n${renderStatus(existing, project, profile)}` }
   }
+  if (restart?.length) {
+    ctx.output.note(`  ${restart.map((d) => `${d.name} is down (${d.why})`).join('; ')}: restarting the runtime; its data is kept`)
+    await ctx.output.task('Stopping what is left of it', () => stopRuntime(project))
+  } else if (existing?.supervisorPid && !isAlive(existing.supervisorPid) && existing.phase !== 'stopped') {
+    // The supervisor went away and left its containers up: they are stopped (not removed), and started again below.
+    try {
+      await stopRuntime(project)
+    } catch {
+      // No container runtime: the check below says so.
+    }
+  }
 
   const docker = dockerAvailable()
   if (!docker.ok) {
@@ -156,24 +244,28 @@ async function start(ctx: CommandContext): Promise<{ data: unknown; text: string
   }
 
   const sourceFlag = flagString(ctx, 'source')
-  const useImage = flagBool(ctx, 'image')
-  const source = sourceFlag ? resolve(ctx.cwd, sourceFlag) : useImage ? null : (process.env.FRONTERA_PLATFORM_SOURCE ?? detectPlatformSource())
+  const previous = readConfig(project)
+  // A restart of what went down, with no flags, runs as it ran: the same release image or checkout.
+  const keep = !!restart?.length && !sourceFlag && !flagBool(ctx, 'image') && !!previous
+  const useImage = flagBool(ctx, 'image') || (keep && previous!.mode === 'image')
+  const source = sourceFlag ? resolve(ctx.cwd, sourceFlag) : useImage ? null : ((keep ? previous!.platformSource : undefined) ?? process.env.FRONTERA_PLATFORM_SOURCE ?? detectPlatformSource())
   if (sourceFlag && !isPlatformSource(source!)) {
     throw new UsageError(`${source} is not a Frontera platform checkout`, 'point --source at the repository root that holds packages/service')
   }
-  const exclude = parseList(flagString(ctx, 'exclude'))
-  const previous = readConfig(project)
+  const exclude = keep && !flagString(ctx, 'exclude') ? previous!.exclude : parseList(flagString(ctx, 'exclude'))
   const config: LocalConfig = {
     mode: source ? 'source' : 'image',
     platformSource: source ?? undefined,
-    platformVersion: flagString(ctx, 'version') ?? previous?.platformVersion ?? cliVersion(),
+    platformVersion: versionAtStart({ checkout: source ? checkoutVersion(source) : null, flag: flagString(ctx, 'version'), previous, cli: cliVersion() }),
     registry: normalizeRegistry(flagString(ctx, 'registry') ?? process.env.FRONTERA_LOCAL_REGISTRY ?? previous?.registry),
     exclude,
   }
   ensureStateDir(project)
   writeConfig(project, config)
 
-  const ports = claimPorts(project.id, project.root)
+  const { ports, reclaimed } = claimPortBlock(project.id, project.root)
+  const freed = reclaimedNote(reclaimed)
+  if (freed) ctx.output.note(freed)
   for (const name of [...COMPONENTS, 'cache', 'embeddings', 'traces'] as const) {
     if (exclude.includes(name as ComponentName)) continue
     if (!(await isPortFree(ports[name]))) {
@@ -223,7 +315,6 @@ const startMeta = {
   summary: 'Start Frontera\'s runtimes on this machine and seed an owner, workspace and keys',
   examples: ['frontera local start', 'frontera local start --exclude runner', 'frontera local start --image --version 1.52.19', 'frontera local start --image --registry registry.example.com/frontera'],
   offline: true,
-  internal: true,
 } as const
 
 export const localStart: Command = { meta: { noun: 'local', verb: 'start', ...startMeta }, run: start }
@@ -231,16 +322,20 @@ export const localStart: Command = { meta: { noun: 'local', verb: 'start', ...st
 async function stop(ctx: CommandContext) {
   const project = localProject(ctx.cwd)
   const state = readState(project)
-  if (!state) return { data: { stopped: false }, text: 'No local runtime here.' }
+  // The project's App dev servers point at this runtime: they stop with it (only this project's records are read).
+  const apps = stopDevServers(project)
+  const appsLine = apps.length ? ` Stopped ${apps.length} App dev server${apps.length === 1 ? '' : 's'}: ${apps.map((a) => `${a.slug} (port ${a.port})`).join(', ')}.` : ''
+  const appsField = apps.length ? { appDevServersStopped: apps.map((a) => ({ app: a.slug, port: a.port, pid: a.pid })) } : {}
+  if (!state) return { data: { stopped: false, ...appsField }, text: `No local runtime here.${appsLine}` }
   await ctx.output.task('Stopping the local runtime', () => stopRuntime(project))
   if (flagBool(ctx, 'no-backup')) {
     destroyRuntimeData(project)
     clearState(project)
     rmSync(join(project.stateDir, 'secrets.json'), { force: true })
     releasePorts(project.id)
-    return { data: { stopped: true, dataRemoved: true }, text: 'Stopped, and removed the database and local secrets.' }
+    return { data: { stopped: true, dataRemoved: true, ...appsField }, text: `Stopped, and removed the database and local secrets.${appsLine}` }
   }
-  return { data: { stopped: true }, text: 'Stopped. Data is kept; `frontera local start` brings it back.' }
+  return { data: { stopped: true, ...appsField }, text: `Stopped. Data is kept; \`frontera local start\` brings it back.${appsLine}` }
 }
 
 export const localStop: Command = {
@@ -249,14 +344,36 @@ export const localStop: Command = {
     verb: 'stop',
     args: [],
     flags: { 'no-backup': 'boolean' },
-    summary: 'Stop the local runtime (keeps its data unless --no-backup)',
+    summary: 'Stop the local runtime and the project\'s App dev servers (keeps its data unless --no-backup)',
     examples: ['frontera local stop', 'frontera local stop --no-backup'],
     offline: true,
-    internal: true,
   },
   run: stop,
 }
 
+/**
+ * Each project object set's id on the runtime, by its file's reference, read
+ * where `frontera blueprint object-sets` reads them; null when the runtime is
+ * stopped or does not answer (the last apply's record is shown instead).
+ */
+async function runtimeObjectSetIds(state: LocalState, project: LocalProject): Promise<Record<string, string> | null> {
+  const files = projectObjectSetNames(project.root)
+  if (!files.size || state.phase !== 'ready' || !isAlive(state.supervisorPid) || !state.credentials?.workspaceKey) return null
+  try {
+    const res = await fetch(`http://127.0.0.1:${state.ports.service}/v1/sync/object-sets`, { headers: { authorization: `Bearer ${state.credentials.workspaceKey}` } })
+    if (!res.ok) return null
+    const sets = normalizeObjectSets(await res.json(), files)
+    const out: Record<string, string> = {}
+    for (const ref of files.keys()) {
+      const found = findObjectSet(sets, ref, files)
+      if ('set' in found) out[ref] = found.set.id
+    }
+    return out
+  } catch {
+    return null
+  }
+}
+
 async function status(ctx: CommandContext) {
   const project = localProject(ctx.cwd)
   const state = readState(project)
@@ -279,10 +396,48 @@ async function status(ctx: CommandContext) {
     ]
     return { data: Object.fromEntries(lines.map((l) => l.split(/=(.*)/s).slice(0, 2))), text: lines.join('\n') }
   }
-  const { credentials, ...rest } = state
+  // Each component as it is now: a container that exited under the supervisor is down, whatever the state file says.
+  const { components, down } = await liveComponents(state)
+  const { credentials, ...rest } = { ...state, components }
+  // Each governed Action as the runtime deploys it, and its secrets now (names, and whether each has a value):
+  // read as Studio's build summary reads them, so the two count the same failures.
+  const { live, secrets, apps: liveApps } = await runtimeBuildInputs(state, project.root)
+  const setIds = await runtimeObjectSetIds(state, project)
+  // The local personas, by key and name: never a session.
+  const personas = state.phase === 'ready' && isAlive(state.supervisorPid) && state.credentials ? await listPersonas(`http://127.0.0.1:${state.ports.service}`, state.credentials) : null
+  const summary = projectBuildSummary(project.root, project.id, live, secrets, liveApps ?? null)
+  const devServers = listDevServers(project)
+  // A document left unread by a rollback reads as built here otherwise: said with its fix.
+  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) ?? []
   return {
-    data: { ...rest, credentials: credentials ? { email: credentials.email, organizationId: credentials.organizationId, workspaceId: credentials.workspaceId } : null },
-    text: renderStatus(state, project),
+    data: {
+      ...rest,
+      credentials: credentials ? { email: credentials.email, organizationId: credentials.organizationId, workspaceId: credentials.workspaceId } : null,
+      // Down now (`components` says `failed` for each), with why; `frontera local start` brings them back.
+      ...(down.length ? { down } : {}),
+      profiles: { workspace: localProfileName(project), organization: `${localProfileName(project)}-org`.slice(0, 64) },
+      // `counts` is over exactly `items`.
+      build: summary ? { line: summary.line, counts: summary.counts, items: projectBuildRows(project.root, project.id, live, setIds, secrets, liveApps ?? null) ?? [] } : null,
+      personas: personas ?? [],
+      // Knowledge search on the keyless local embeddings: approximate, with what gives the platform's.
+      ...(state.credentials?.modelProviders?.includes('local-embeddings') ? { embeddings: keylessEmbeddingsStatus() } : {}),
+      docs: docsStatus(project, { mode: state.mode, platformVersion: state.platformVersion, platformSource: readConfig(project)?.platformSource }),
+      notices: projectNotices(project.root),
+      // The App dev servers running against this runtime, with their ports: `frontera local stop` stops them.
+      appDevServers: devServers.map((s) => ({ app: s.slug, port: s.port, url: s.url, pid: s.pid, startedAt: s.startedAt, startedBy: s.owner?.kind ?? 'hand', ...(s.owner ? { ownerPid: s.owner.pid } : {}) })),
+      // Knowledge documents pending or processing with no ingestion behind them, each with its fix.
+      ...(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 } : {}),
+    },
+    text: [
+      renderStatus({ ...state, components }, project, undefined, live, setIds, personas, secrets, liveApps ?? null, down),
+      ...(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)}`)] : []),
+    ].join('\n'),
   }
 }
 
@@ -296,7 +451,6 @@ export const localStatus: Command = {
     summary: 'Show the local runtime: components, URLs and credentials (-o env for scripts)',
     examples: ['frontera local status', 'eval "$(frontera local status -o env)"'],
     offline: true,
-    internal: true,
   },
   run: status,
 }
@@ -330,7 +484,6 @@ export const localLogs: Command = {
     summary: 'Print a component\'s log (service by default)',
     examples: ['frontera local logs', 'frontera local logs jobs -f'],
     offline: true,
-    internal: true,
   },
   run: logs,
 }
@@ -379,45 +532,123 @@ export const localUi: Command = {
     summary: 'Open Frontera Studio for the running local runtime',
     examples: ['frontera local ui', 'frontera local ui --no-open'],
     offline: true,
-    internal: true,
   },
   run: ui,
 }
 
+/**
+ * The case files `frontera local test` runs. `agent` takes one Agent's cases,
+ * `workflow` one workflow's; neither runs both kinds. `regression`: only the
+ * Agents' regression datasets, as the workspace chose them. `file`: one case
+ * file, an Agent's (agents/<slug>/evals/*.yaml) or a workflow's
+ * (workflows/tests/*.yaml), chosen as MCP `test_run` chooses it.
+ */
+export function localTestFiles(root: string, scope: { agent?: string; workflow?: string; file?: string; regression?: boolean }): { files: CaseFile[]; workflowFiles: WorkflowTestFile[] } {
+  const file = scope.file?.replace(/^\.\//, '')
+  const files = scope.workflow ? [] : selectCaseFiles(root, { agent: scope.agent, file, regression: scope.regression })
+  const workflowFiles = scope.agent || scope.regression ? [] : findWorkflowTestFiles(root, scope.workflow).filter((f) => !file || f.file === file)
+  return { files, workflowFiles }
+}
+
 async function test(ctx: CommandContext) {
   const project = localProject(ctx.cwd)
   const state = readState(project)
   if (!state || state.phase !== 'ready' || !state.credentials?.session) {
     throw new CliError('the local runtime is not running', { code: 'LOCAL_NOT_RUNNING', hint: 'run `frontera local start` first' })
   }
-  // `--regression`: only the Agents' regression datasets, as the workspace chose them.
-  const files = findCaseFiles(project.root, flagString(ctx, 'agent')).filter((f) => !flagBool(ctx, 'regression') || f.regression)
-  const total = files.reduce((n, f) => n + f.cases.length, 0)
-  if (total === 0 && flagBool(ctx, 'regression')) {
-    return { data: { passed: 0, failed: 0, results: [] }, text: 'No regression datasets. A pull marks the dataset each Agent is tested on before publishing in the workspace (`regression: true`).' }
+  const agent = flagString(ctx, 'agent')
+  const workflow = flagString(ctx, 'workflow')
+  const regression = flagBool(ctx, 'regression')
+  const file = flagString(ctx, 'file')?.replace(/^\.\//, '')
+  const { files, workflowFiles } = localTestFiles(project.root, { agent, workflow, file, regression })
+  const total = caseCount(files)
+  const workflowTotal = workflowFiles.reduce((n, f) => n + Math.max(f.cases.length, f.problem ? 1 : 0), 0)
+  const empty = { passed: 0, failed: 0, results: [], workflows: [] }
+  if (total + workflowTotal === 0 && regression) {
+    return { data: empty, text: 'No regression datasets. A pull marks the dataset each Agent is tested on before publishing in the workspace (`regression: true`).' }
+  }
+  if (total + workflowTotal === 0 && file) {
+    throw new UsageError(`no test case file ${file}${agent ? ` for Agent ${agent}` : workflow ? ` for workflow ${workflow}` : ''}`, 'give its path from the project root, e.g. agents/<slug>/evals/<name>.yaml or workflows/tests/<slug>.yaml')
   }
-  if (total === 0) {
+  if (total + workflowTotal === 0) {
     return {
-      data: { passed: 0, failed: 0, results: [] },
-      text: 'No test cases. Save one from Studio (Agents → Save as test case) or add agents/<slug>/evals/*.yaml.',
+      data: empty,
+      text: workflow
+        ? `No test cases for workflow ${workflow}. Add workflows/tests/${workflow}.yaml (\`frontera local schema workflow-tests\` is its format).`
+        : 'No test cases. Save one from Studio (Agents → Save as test case), add agents/<slug>/evals/*.yaml, or add workflows/tests/<slug>.yaml.',
     }
   }
-  const results = await runCases({
-    serviceUrl: `http://127.0.0.1:${state.ports.service}`,
-    creds: state.credentials,
-    files,
-    live: flagBool(ctx, 'live'),
-    onResult: (r) => ctx.output.note(`  ${r.passed ? '✓' : '✕'} ${r.agent} · ${r.name}${r.passed ? '' : ` — ${r.reason}`} (${r.ms} ms)`),
-  })
-  const failed = results.filter((r) => !r.passed)
-  const summary = `${results.length - failed.length} passed, ${failed.length} failed`
-  if (failed.length) {
-    throw new CliError(`${summary}: ${failed.map((f) => `${f.agent} · ${f.name}`).join('; ')}`, {
-      code: 'LOCAL_TESTS_FAILED',
-      hint: 'open the Agent in Studio (`frontera local ui`) to see the conversation, then fix the Agent or the case',
-    })
+  const serviceUrl = `http://127.0.0.1:${state.ports.service}`
+  let concurrency: number | undefined
+  try {
+    concurrency = caseConcurrency(flagString(ctx, 'concurrency'))
+  } catch (err) {
+    throw new UsageError((err as Error).message, 'frontera local test --concurrency 1')
+  }
+  const results: CaseResult[] = total
+    ? await runCases({
+        serviceUrl,
+        creds: state.credentials,
+        files,
+        live: flagBool(ctx, 'live'),
+        // The draft is what the files say, or the cases say what to run first.
+        staleDraft: (slug) => agentFilesProblem(project, state.credentials!.organizationId, slug),
+        concurrency,
+        onResult: (r) => {
+          // A case never sent after the run stopped is said once, below, not once each.
+          if (r.notRun?.skipped) return
+          ctx.output.note(`  ${r.passed ? '✓' : r.notRun ? '–' : '✕'} ${r.agent} · ${r.name}${r.passed ? '' : r.notRun ? ` — couldn’t run: ${r.notRun.what}` : ` — ${r.reason}`}${r.passed && r.retried ? ' (run twice: the provider refused the first try for its limits)' : ''}${r.waited?.length ? ` (${waitedWords(r.waited)})` : ''} (${r.ms} ms)`)
+        },
+      })
+    : []
+  // What kept cases from running, once each, with its fix: never a verdict on the Agent.
+  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}`)
+    ctx.output.note(`  couldn’t run ${g.cases.length} case${g.cases.length === 1 ? '' : 's'}: ${withFix(g.what, g.fix)}`)
   }
-  return { data: { passed: results.length, failed: 0, results }, text: summary }
+  const workflows: WorkflowTestResult[] = workflowTotal
+    ? await runWorkflowTests({
+        serviceUrl,
+        creds: state.credentials,
+        files: workflowFiles,
+        // Exactly the version `local dev` pushed each file as, never a stale draft.
+        fileState: (slug) => workflowFileState(project, state.credentials!.organizationId, slug),
+        onResult: (r) => ctx.output.note(`  ${r.passed ? '✓' : '✕'} workflow ${r.workflow} · ${r.name}${r.passed ? '' : ` — ${r.reason}`} (${r.ms} ms)`),
+      })
+    : []
+  // Each failing Agent case's conversation, last turn's trace and reply: what to read to tell a regression from a bad case.
+  const evidence = await failingCaseEvidence(project, results)
+  for (const [i, e] of evidence) ctx.output.note(`    ${results[i]!.agent} · ${results[i]!.name}: ${evidenceLine(e)}`)
+  // Every case's last-turn trace beside its conversation (`--json`), passing ones included; a failing one's came with its evidence.
+  const traces = await caseTraces(project, results, { known: evidence })
+  const comparison = compareWithLastRun(results, readLastRun(project))
+  if (results.length) recordRun(project, results)
+  // Each workflow case's last run, for Studio's Evaluations and Forge's home.
+  recordWorkflowTestRun(project, workflows)
+  const failed = [...results.filter((r) => !r.passed && !r.notRun).map((f) => `${f.agent} · ${f.name}`), ...workflows.filter((r) => !r.passed).map((f) => `workflow ${f.workflow} · ${f.name}`)]
+  const notRunCount = notRun.reduce((n, g) => n + g.cases.length, 0)
+  const passed = results.length + workflows.length - failed.length - notRunCount
+  const newly = comparison.newlyFailing.length ? `, ${comparison.newlyFailing.length} newly failing since the last run` : ''
+  const summary = `${passed} passed, ${failed.length} failed${newly}${notRun.length ? `, ${notRunWords(notRun)}` : ''}`
+  const data = { passed, failed: failed.length, ...(notRun.length ? { notRun: notRunCount, couldNotRun: notRun.map((g) => ({ what: `couldn’t run: ${g.what}`, fix: g.fix, cases: g.cases, ...(g.skipped ? { notSent: g.skipped } : {}) })) } : {}), fixed: comparison.fixed.length, results: results.map((r, i) => ({ ...r, ...traces.get(i), ...evidence.get(i) })), workflows }
+  if (failed.length || notRun.length) {
+    // Only cases that couldn't run: the run did not pass, and the cause is the provider's or the runtime's, not the Agent's.
+    const onlyNotRun = !failed.length
+    const code = onlyNotRun ? 'LOCAL_TESTS_NOT_RUN' : 'LOCAL_TESTS_FAILED'
+    const message = onlyNotRun ? summary : `${summary}: ${failed.join('; ')}`
+    const caseHint = workflows.some((r) => !r.passed)
+      ? 'open the run in Studio (`frontera local ui` → Workflows → Runs) or the Agent\'s conversation, then fix the workflow, the Agent or the case'
+      : 'open the Agent in Studio (`frontera local ui`) to see the conversation, then fix the Agent or the case'
+    const hint = [onlyNotRun ? null : caseHint, ...notRun.map((g) => g.fix)].filter(Boolean).join('; ')
+    // `--json`: the per-case results ARE the data, failed or not, so they go to stdout (exit 1 says a case failed), as `local check` does.
+    if (flagBool(ctx, 'json')) {
+      ctx.output.note(`error [${code}]: ${message}`)
+      return { data: { ...data, error: { code, message, hint } }, text: '', exitCode: EXIT.FAILURE }
+    }
+    throw new CliError(message, { code, hint, details: data })
+  }
+  return { data, text: summary }
 }
 
 export const localTest: Command = {
@@ -425,11 +656,15 @@ export const localTest: Command = {
     noun: 'local',
     verb: 'test',
     args: [],
-    flags: { agent: 'string', live: 'boolean', regression: 'boolean' },
-    summary: 'Run the project\'s saved Agent test cases against the local runtime',
-    examples: ['frontera local test', 'frontera local test --agent claims-triage', 'frontera local test --live', 'frontera local test --regression'],
+    flags: { agent: 'string', workflow: 'string', file: 'string', live: 'boolean', regression: 'boolean', concurrency: 'string' },
+    flagHelp: { file: 'run only this case file, by its path from the project root: agents/<slug>/evals/<name>.yaml or workflows/tests/<slug>.yaml' },
+    summary: 'Run the project\'s Agent test cases and workflow tests against the local runtime',
+    details: [
+      '`--file` runs one case file, by its path from the project root: an Agent\'s (agents/<slug>/evals/<name>.yaml) or a workflow\'s (workflows/tests/<slug>.yaml), the same file MCP `test_run` takes. A path that names no case file is refused.',
+      'A workflow test runs the workflow for real on the local runtime: a governed Action one of its steps submits (an action step, or a Function step\'s code) is applied and changes the runtime\'s records when the Action runs here; one whose effect would reach another system is switched off here. The writes stay; `frontera local check` rolls back its own tests\' writes, and `frontera local snapshot save` / `restore` do it by hand. The workspace is never touched.',
+    ],
+    examples: ['frontera local test', 'frontera local test --agent claims-triage', 'frontera local test --workflow claim-intake', 'frontera local test --file agents/claims-triage/evals/refunds.yaml', 'frontera local test --live', 'frontera local test --regression', 'frontera local test --concurrency 1'],
     offline: true,
-    internal: true,
   },
   run: test,
 }
@@ -463,6 +698,7 @@ export const localCommands: readonly Command[] = [
   localStatus,
   localLogs,
   localReset,
+  localRemove,
   localUi,
   localDev,
   localTest,
@@ -480,6 +716,7 @@ export const localCommands: readonly Command[] = [
   localDocsMcp,
   localSchema,
   localData,
+  localSdkRefresh,
   localSync,
   localDaemon,
 ]