@frontera-sdk/cli 1.52.38 → 1.52.40

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

@@ -0,0 +1,120 @@
+import { runtimeLink, studioLink, type RuntimeLink } from '../mcp/mcp-runtime'
+import { conversationTraces, traceLink } from '../mcp/mcp-traces'
+import type { LocalProject } from './local-project'
+import type { CaseResult } from './local-test-runner'
+
+/**
+ * What a failing Agent case leaves to look at: its conversation, the trace of
+ * its last turn and the start of the reply it was judged on, so whoever reads
+ * `local check` or `local test` (a coding agent with `--json`) can tell an
+ * Agent regression from a check that asks for the wrong thing without
+ * 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).
+ */
+export interface CaseEvidence {
+  conversationId?: string
+  traceId?: string
+  /** Studio's page for the trace. */
+  traceLink?: string
+  /** Studio's page for the conversation, while the database still holds it. */
+  conversationLink?: string
+  /** The reply the case was judged on, its start (`REPLY_EXCERPT` characters). */
+  replyExcerpt?: string
+}
+
+export const REPLY_EXCERPT = 300
+
+export function replyExcerpt(reply: string): string | undefined {
+  const text = reply.replace(/\s+/g, ' ').trim()
+  if (!text) return undefined
+  return text.length > REPLY_EXCERPT ? `${text.slice(0, REPLY_EXCERPT)}…` : text
+}
+
+/** The newest trace of the conversation that called a model (the turn the reply came from), else its newest. */
+async function lastTurnTrace(link: RuntimeLink, conversationId: string, since?: string): Promise<string | null> {
+  const traces = (await conversationTraces(link, conversationId, since)).sort((a, b) => Date.parse(b.timestamp) - Date.parse(a.timestamp))
+  return (traces.find((t) => t.observations.some((o) => o.type === 'GENERATION')) ?? traces[0])?.id ?? null
+}
+
+/**
+ * The evidence of each failing case (never one that passed or couldn't run),
+ * by its index in `results`. A trace that has not arrived is looked for again
+ * for a few seconds; one that never does leaves its id out, never the case.
+ */
+export async function failingCaseEvidence(project: LocalProject, results: readonly CaseResult[], opts: { waitMs?: number } = {}): Promise<Map<number, CaseEvidence>> {
+  const out = new Map<number, CaseEvidence>()
+  const failing = results.map((r, i) => [r, i] as const).filter(([r]) => !r.passed && !r.notRun)
+  if (!failing.length) return out
+  const link = runtimeLink(project)
+  const deadline = Date.now() + (opts.waitMs ?? 4_000)
+  for (const [r, i] of failing) {
+    const evidence: CaseEvidence = {
+      ...(r.conversationId ? { conversationId: r.conversationId } : {}),
+      ...(replyExcerpt(r.reply) ? { replyExcerpt: replyExcerpt(r.reply) } : {}),
+    }
+    if (typeof link !== 'string' && r.conversationId) {
+      if (r.agentId) evidence.conversationLink = studioLink(link, `/agents/${encodeURIComponent(r.agentId)}/c/${encodeURIComponent(r.conversationId)}`)
+      const since = r.startedAt ? new Date(Date.parse(r.startedAt) - 1_000).toISOString() : undefined
+      for (;;) {
+        const id = await lastTurnTrace(link, r.conversationId, since).catch(() => null)
+        if (id) {
+          evidence.traceId = id
+          evidence.traceLink = traceLink(link, id)
+          break
+        }
+        if (Date.now() >= deadline) break
+        await new Promise((res) => setTimeout(res, 500))
+      }
+    }
+    if (Object.keys(evidence).length) out.set(i, evidence)
+  }
+  return out
+}
+
+/**
+ * The trace of each case's last turn, by its index in `results`: every case
+ * that has a conversation (passed, failed, or one that could not finish), so
+ * `local test --json` and the MCP `test_run` name the trace beside the
+ * conversation, and nobody matches traces by their time. A trace that has not
+ * arrived is looked for again for a few seconds, across the cases together
+ * (a second only, when none of the run's has arrived); one that never does
+ * leaves its case without a `traceId`. `known`: the
+ * failing cases' evidence already found, not looked for again. A case of several
+ * turns names its last turn's trace; `trace_list` with the conversation id
+ * lists the others.
+ */
+export async function caseTraces(project: LocalProject, results: readonly CaseResult[], opts: { waitMs?: number; known?: ReadonlyMap<number, CaseEvidence> } = {}): Promise<Map<number, { traceId: string; traceLink: string }>> {
+  const out = new Map<number, { traceId: string; traceLink: string }>()
+  const link = runtimeLink(project)
+  if (typeof link === 'string') return out
+  for (const [i, e] of opts.known ?? []) if (e.traceId && e.traceLink) out.set(i, { traceId: e.traceId, traceLink: e.traceLink })
+  let missing = results.map((r, i) => [r, i] as const).filter(([r, i]) => !!r.conversationId && !out.has(i))
+  const started = Date.now()
+  const deadline = started + (opts.waitMs ?? 4_000)
+  while (missing.length) {
+    for (const [r, i] of missing) {
+      const since = r.startedAt ? new Date(Date.parse(r.startedAt) - 1_000).toISOString() : undefined
+      const id = await lastTurnTrace(link, r.conversationId!, since).catch(() => null)
+      if (id) out.set(i, { traceId: id, traceLink: traceLink(link, id) })
+    }
+    missing = missing.filter(([, i]) => !out.has(i))
+    // A store that has none of this run's traces after a second is not about to: no wait for the rest.
+    if (!missing.length || Date.now() >= deadline || (!out.size && Date.now() >= started + 1_000)) break
+    await new Promise((res) => setTimeout(res, 500))
+  }
+  return out
+}
+
+/** One line under a failing case: "trace 6f5e… (link); conversation c-1; replied: "…"". */
+export function evidenceLine(e: CaseEvidence, opts: { rolledBack?: boolean } = {}): string {
+  return [
+    e.traceId ? `trace ${e.traceId}${e.traceLink ? ` (${e.traceLink})` : ''}` : e.conversationId ? 'trace not arrived yet (trace_list with the conversation id finds it)' : '',
+    e.conversationId ? `conversation ${e.conversationId}${opts.rolledBack ? ' (rolled back with the test data; the trace stays)' : ''}` : '',
+    e.replyExcerpt ? `replied: "${e.replyExcerpt}"` : 'no reply',
+  ]
+    .filter(Boolean)
+    .join('; ')
+}

package/src/local/local-case-not-run.ts

@@ -0,0 +1,153 @@
+/**
+ * An Agent case that couldn't run, told apart from one that failed.
+ *
+ * A case fails when the Agent's reply or tools miss what the case expects:
+ * that is what a change broke. A case that never got a reply because the
+ * model provider refused the request (out of credit, a rate limit, a refused
+ * key, an outage), the turn timed out, or the local runtime did not answer
+ * says nothing about the Agent. Such a case still keeps the gate from
+ * passing, but it is never counted as newly failing, never recorded as the
+ * case's last outcome, and it is said with its cause and the fix.
+ *
+ * The runtime describes a provider failure as `<status> · <category> ·
+ * <message>` (`describeProviderFailure` in the service): `402 ·
+ * invalid_request · This request would exceed your available credits…`.
+ */
+
+export type NotRunKind = 'credits' | 'rate-limit' | 'key' | 'provider-error' | 'timeout' | 'runtime-unreachable' | 'runtime-error'
+
+export interface CaseNotRun {
+  /** Whose side it is on: the model provider's, the turn's clock, or the local runtime's. */
+  cause: 'provider' | 'timeout' | 'runtime'
+  kind: NotRunKind
+  /** After "couldn't run: ": "the model provider refused (402 credits)". */
+  what: string
+  /** What fixes it, for the person. */
+  fix: string
+  /** Never sent: an earlier case met the same refusal, and the run stopped sending cases. */
+  skipped?: boolean
+  /** The provider that refused, when its words name it (`openrouter`, `anthropic`). */
+  provider?: string
+}
+
+/** Refusals every later case would meet as well: the account's credit or key, or a runtime that does not answer. */
+const STOPS_THE_RUN = new Set<NotRunKind>(['credits', 'key', 'runtime-unreachable'])
+
+export function stopsTheRun(n: CaseNotRun): boolean {
+  return STOPS_THE_RUN.has(n.kind)
+}
+
+const PROVIDERS = 'frontera local providers'
+
+/** The fix for each kind; `again` is what the person does once it is fixed ("runs the cases again"). */
+function fixFor(kind: NotRunKind, again = 'runs the cases again'): string {
+  switch (kind) {
+    case 'credits':
+      return `the model provider account is out of credit: the person adds credit there, or picks a model through another provider they hold a key for (\`${PROVIDERS}\` shows which provider each model uses), then ${again}`
+    case 'rate-limit':
+      return again === 'runs the cases again' ? 'the model provider is limiting requests: run the cases again later, or one at a time with `--concurrency 1`' : `the model provider is limiting requests: wait a minute, then ${again}`
+    case 'key':
+      return `the model provider refused the key: the person checks it and sets it again (\`frontera local key-set <provider>\`; \`${PROVIDERS}\` shows which provider each model uses), then ${again}`
+    case 'provider-error':
+      return `the model provider failed to answer: ${again.replace(/^runs /, 'run ')}; if it persists, check the provider’s status`
+    case 'timeout':
+      return 'the turn did not finish in time: run the case again; if it times out again, open its conversation in Studio (`frontera local ui`) to see where it stopped'
+    case 'runtime-unreachable':
+      return '`frontera local status` says whether the local runtime is running; `frontera local start` starts it'
+    case 'runtime-error':
+      return 'the local runtime failed the request: `frontera local logs service` says why; run the cases again once it answers'
+  }
+}
+
+/** The fix for a kind of refusal, with what the person does once it is fixed ("sends the message again"). */
+export function notRunFix(kind: NotRunKind, again?: string): string {
+  return fixFor(kind, again)
+}
+
+const notRun = (cause: CaseNotRun['cause'], kind: NotRunKind, what: string): CaseNotRun => ({ cause, kind, what, fix: fixFor(kind) })
+
+/** Which provider a refusal's words come from, when they say: OpenRouter's "can only afford", Anthropic's "credit balance is too low". */
+function refusingProvider(text: string): string | null {
+  if (/openrouter|can only afford|requires more credits/i.test(text)) return 'openrouter'
+  if (/anthropic|credit balance is too low/i.test(text)) return 'anthropic'
+  return null
+}
+
+/** A model offered directly by a provider whose key the runtime holds (`directModelFor` in local-seed). */
+export interface DirectModelHint {
+  slug: string
+  name: string
+  providerLabel: string
+}
+
+/**
+ * A credit refusal's fix with the model the person can switch to, when the
+ * runtime offers one directly from another provider they hold a key for:
+ * its slug, and how to make it the default (`frontera local model-default`),
+ * which is theirs to choose. Any other refusal is returned as it is.
+ */
+export function withDirectModel(n: CaseNotRun, direct: DirectModelHint | null, again = 'run the cases again'): CaseNotRun {
+  if (n.kind !== 'credits' || !direct) return n
+  return {
+    ...n,
+    fix: `the model provider account is out of credit: the person adds credit there, or uses a model through another provider they hold a key for. ${/^[AEIOU]/i.test(direct.providerLabel) ? 'An' : 'A'} ${direct.providerLabel} key is stored, so the runtime offers ${direct.name} directly from ${direct.providerLabel} as \`${direct.slug}\` (\`${PROVIDERS}\` lists it): \`frontera local model-default ${direct.slug}\` makes it the model new Agents and test grading use, and the one an Agent runs on when the runtime lacks the model its agent.json names (\`frontera local dev --once --reapply\` applies that to Agents already applied); an Agent whose agent.json names a model the runtime has keeps it until its file names \`${direct.slug}\`. Then ${again}`,
+  }
+}
+
+/** A provider failure as the runtime words it: its status and category, when it says them. */
+const DESCRIBED = /(?:^|[\s:"'(])(\d{3}) · (?:(provider_unavailable|rate_limited|authentication|invalid_request|out_of_credit|aborted) · )?/
+const CATEGORY_ONLY = /(?:^|[\s:"'(])(provider_unavailable|rate_limited|authentication|out_of_credit) · /
+const CREDIT = /credit|can only afford|insufficient (?:funds|balance|quota)|billing|payment required|quota/i
+const RATE = /rate.?limit|too many requests|in-flight|in flight/i
+
+/**
+ * Why a case's error means it couldn't run, or null when it is a failure of
+ * the case itself (a refused setup, a conversation waiting on a decision, a
+ * missing Agent). Only an error is classified, never a verdict on a reply.
+ */
+export function caseCouldNotRun(message: string): CaseNotRun | null {
+  const text = message.replace(/\s+/g, ' ').trim()
+  if (!text) return null
+  const described = DESCRIBED.exec(text)
+  const status = described ? Number(described[1]) : undefined
+  const category = described?.[2] ?? CATEGORY_ONLY.exec(text)?.[1]
+  const fromProvider = !!described || !!category
+  // A 402 or 429 the provider worded without the runtime's form ("402 Payment Required: … credits").
+  const bare = !fromProvider ? /\b(402|429)\b/.exec(text) : null
+  const code = status ?? (bare ? Number(bare[1]) : undefined)
+
+  // `out_of_credit`: the runtime's own category for a credit refusal, whatever status the provider sent.
+  if (code === 402 || category === 'out_of_credit' || ((fromProvider || bare) && CREDIT.test(text) && code !== 429 && category !== 'rate_limited')) {
+    const provider = refusingProvider(text)
+    return { ...notRun('provider', 'credits', `the model provider refused (${code ?? 402} credits)`), ...(provider ? { provider } : {}) }
+  }
+  if (code === 429 || category === 'rate_limited' || (bare && RATE.test(text))) return notRun('provider', 'rate-limit', `the model provider refused (${code ?? 429} rate limit)`)
+  if (fromProvider && (code === 401 || code === 403 || category === 'authentication')) return notRun('provider', 'key', `the model provider refused the key${code ? ` (${code})` : ''}`)
+  if (fromProvider && ((code !== undefined && (code === 408 || code >= 500)) || category === 'provider_unavailable')) return notRun('provider', 'provider-error', `the model provider failed${code ? ` (${code})` : ''}`)
+
+  // The turn's own clock (the runner gives a turn 180 s, a call 60 s).
+  if (/operation timed out|TimeoutError|aborted due to timeout|timed out after/i.test(text)) return notRun('timeout', 'timeout', 'the turn did not finish in time')
+  // The local runtime did not answer at all, or failed the request.
+  if (/unable to connect|ECONNREFUSED|ConnectionRefused|fetch failed|socket connection was closed unexpectedly/i.test(text)) return notRun('runtime', 'runtime-unreachable', 'the local runtime did not answer')
+  const failed = /\banswered (5\d\d)\b/.exec(text)
+  if (failed) return notRun('runtime', 'runtime-error', `the local runtime failed (${failed[1]})`)
+  return null
+}
+
+/** The cases that couldn't run, by cause: one line each, with its fix and the cases. */
+export function notRunGroups<T extends { notRun?: CaseNotRun; agent: string; name: string }>(results: readonly T[]): Array<{ what: string; fix: string; cause: CaseNotRun['cause']; cases: string[]; skipped: number }> {
+  const groups = new Map<string, { what: string; fix: string; cause: CaseNotRun['cause']; cases: string[]; skipped: number }>()
+  for (const r of results) {
+    if (!r.notRun) continue
+    const g = groups.get(r.notRun.what) ?? { what: r.notRun.what, fix: r.notRun.fix, cause: r.notRun.cause, cases: [], skipped: 0 }
+    g.cases.push(`${r.agent} · ${r.name}`)
+    if (r.notRun.skipped) g.skipped += 1
+    groups.set(r.notRun.what, g)
+  }
+  return [...groups.values()]
+}
+
+/** "13 couldn't run: the model provider refused (402 credits)", causes joined; empty when every case ran. */
+export function notRunWords(groups: ReturnType<typeof notRunGroups>): string {
+  return groups.map((g) => `${g.cases.length} couldn’t run: ${g.what}`).join('; ')
+}

package/src/local/local-chat-apps.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 import type { RemoteItem } from './local-sync-plan'
+import type { LocalCredentials } from './local-state'
 import { itemRef, referencesIn, toIds, toNames, type Directory } from './local-sync-refs'
 
 /**
@@ -32,12 +33,12 @@ export interface ChatAppRow {
 }
 
 /** The configuration's sections a project file keeps, in this order. */
-const SECTIONS = ['presentation', 'roster', 'features', 'conversation', 'memory'] as const
+const SECTIONS = ['presentation', 'roster', 'features', 'conversation', 'variables', 'memory'] as const
 
 export const chatAppPath = (slug: string) => `chat-apps/${slug}.json`
 
 /** Why a Chat App stays a draft locally, as the build and the Pull dialog say it. */
-export const CHAT_APP_DRAFT = 'Saved as the owner’s draft here and opened as its preview, its Agents running their drafts: a Chat App publishes only published Agents, and the local runtime’s Agents are drafts'
+export const CHAT_APP_DRAFT = 'Saved as the owner’s draft here: Studio opens it at /apps/<slug> as its draft preview, its Agents running their drafts. It publishes once its Agents are published (a Chat App publishes only published Agents)'
 
 /**
  * The project's file for an App's live configuration: its Agents by name,
@@ -83,11 +84,45 @@ export function readChatApps(rows: ChatAppRow[], directory: Directory, wanted: (
 
 type Call = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: unknown }>
 
+/** Calls as the runtime's workspace key: the principal `frontera chat-app` commands act as in the project. */
+export function keyCalls(serviceUrl: string, creds: LocalCredentials, fetcher: typeof fetch = fetch): Call {
+  return async (method, path, body) => {
+    const res = await fetcher(new URL(path, serviceUrl), {
+      method,
+      headers: {
+        authorization: `Bearer ${creds.workspaceKey ?? ''}`,
+        'x-org-id': creds.organizationId,
+        'x-workspace-id': creds.workspaceId,
+        ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    })
+    const text = await res.text()
+    let parsed: unknown = text
+    try {
+      parsed = text ? JSON.parse(text) : null
+    } catch {
+      // Keep the text.
+    }
+    return { status: res.status, body: parsed }
+  }
+}
+
 const dataOf = (body: unknown) => ((body as { data?: unknown } | null)?.data ?? body) as Record<string, unknown> | null
 
-const errorOf = (a: { status: number; body: unknown }) => {
-  const b = a.body as { message?: unknown } | null
-  return `${a.status} ${String(typeof b?.message === 'string' ? b.message : JSON.stringify(b)).replace(/\s+/g, ' ').slice(0, 200)}`
+/**
+ * A refusal with what the service said was wrong: the configuration's
+ * validation (`roster.agents.0.label: Required`) is in its `details`, which a
+ * bare "400 Invalid Chat App configuration" hides.
+ */
+export const errorOf = (a: { status: number; body: unknown }) => {
+  const b = a.body as { message?: unknown; details?: unknown; data?: { details?: unknown } } | null
+  const message = String(typeof b?.message === 'string' ? b.message : JSON.stringify(b)).replace(/\s+/g, ' ').slice(0, 200)
+  const raw = b?.details ?? b?.data?.details
+  const details = (Array.isArray(raw) ? raw : raw && typeof raw === 'object' ? [raw] : [])
+    .map((d) => (typeof d === 'string' ? d : d && typeof d === 'object' ? [(d as { path?: unknown }).path, (d as { message?: unknown }).message].filter((x) => typeof x === 'string' && x).join(': ') || JSON.stringify(d) : String(d)))
+    .filter(Boolean)
+  return details.length ? `${a.status} ${message}: ${details.slice(0, 8).join('; ')}${details.length > 8 ? ` (and ${details.length - 8} more)` : ''}` : `${a.status} ${message}`
 }
 
 export interface ChatAppApplied {
@@ -107,7 +142,7 @@ export interface ChatAppApplied {
  * hold is left off the roster, and said; one it holds but the runtime does
  * not have yet holds the App back until it does.
  */
-export async function applyChatApp(root: string, slug: string, call: Call, directory: () => Promise<Directory>, provides: (ref: string) => boolean): Promise<ChatAppApplied> {
+export async function applyChatApp(root: string, slug: string, call: Call, directory: () => Promise<Directory>, provides: (ref: string) => boolean, keyCall?: Call): Promise<ChatAppApplied> {
   const path = join(root, chatAppPath(slug))
   if (!existsSync(path)) return { ok: false, output: `error [CHAT_APP]: ${chatAppPath(slug)} is missing` }
   let doc: Record<string, unknown>
@@ -131,8 +166,10 @@ export async function applyChatApp(root: string, slug: string, call: Call, direc
   if (waiting.length) {
     return { ok: false, missing: waiting, output: [`error [UNRESOLVED_REFERENCE]: ${chatAppPath(slug)} names what this runtime does not have`, ...waiting.map((w) => `  ${w}: in the project, not applied yet`)].join('\n') }
   }
-  // The live version when it is published (null), as the platform's editor drafts it.
-  roster.agents = kept.map((e) => ({ ...e, agentVersionNumber: null }))
+  // A draft names no Agent version (null: the one live when it is published), as the platform's
+  // editor drafts it; on this runtime its preview runs each Agent's draft. The label and the
+  // description are the Agent's own unless the file gives the App's.
+  roster.agents = kept.map((e) => ({ ...e, agentVersionNumber: null, label: typeof e.label === 'string' && e.label.trim() ? e.label : null, description: typeof e.description === 'string' && e.description.trim() ? e.description : null }))
   const ids = new Set(kept.map((e) => e.agentConfigId))
   if (typeof roster.defaultAgentConfigId === 'string' && !ids.has(roster.defaultAgentConfigId)) roster.defaultAgentConfigId = kept[0]?.agentConfigId ?? null
   const { name: _name, description: _description, ...configuration } = { ...doc, roster } as Record<string, unknown>
@@ -151,20 +188,60 @@ export async function applyChatApp(root: string, slug: string, call: Call, direc
   }
   const draft = await call('PUT', `/v1/chat-apps/${encodeURIComponent(appId)}/draft`, { configuration: resolved })
   if (draft.status >= 400) return { ok: false, output: `error [CHAT_APP]: ${errorOf(draft)}` }
+  // What the runtime found wrong with its `variables` when it saved the draft: an error fails the apply, as it would block a publish.
+  const variableFindings = findingsOf(dataOf(draft.body)?.findings).filter((f) => f.code?.startsWith('variables.'))
+  const variableErrors = variableFindings.filter((f) => f.level === 'error')
+  // Drafts are per principal: the owner's is what Studio previews; the workspace key's is what
+  // `frontera chat-app get` reads in this project. Both hold the file.
+  if (keyCall) {
+    const keyDraft = await keyCall('PUT', `/v1/chat-apps/${encodeURIComponent(appId)}/draft`, { configuration: resolved })
+    if (keyDraft.status >= 400) lines.push(`  warning: \`frontera chat-app get ${slug}\` shows the workspace key's own draft, which could not be saved (${errorOf(keyDraft)}); Studio shows the applied one`)
+  }
   const published = await call('POST', `/v1/chat-apps/${encodeURIComponent(appId)}/publish`, { configuration: resolved })
-  if (published.status >= 400) {
-    const findings = ((dataOf(published.body)?.details ?? (published.body as { details?: unknown } | null)?.details) ?? []) as Array<{ code?: string; message?: string }>
-    const list = Array.isArray(findings) ? findings : []
-    if (list.length && list.every((f) => f.code === 'agent.unpublished' || f.code === 'agent.unavailable' || f.code === 'roster.empty')) {
+  if (published.status < 400) {
+    // Published: its roster's Agents were published here, and people open the live version.
+    const version = (dataOf(published.body) as { version?: { version?: unknown } | null; live?: { version?: unknown } | null } | null)
+    const v = version?.version?.version ?? version?.live?.version
+    lines.push(`  published Chat App ${name}${typeof v === 'string' || typeof v === 'number' ? ` v${v}` : ''} here: people open its live version, with its Agents’ published versions; Studio opens it at /apps/${slug} as its draft preview, its Agents running their drafts`)
+  } else {
+    // Its variables' findings were said from the draft; a runtime that gave none there says them here.
+    const list = findingsOf(dataOf(published.body)?.details ?? (published.body as { details?: unknown } | null)?.details).filter((f) => !(variableFindings.length && f.code?.startsWith('variables.')))
+    for (const f of list.filter((x) => x.code?.startsWith('variables.') && x.level !== 'error')) lines.push(`  warning [${f.code}]: ${f.message ?? ''}`)
+    const blocking = list.filter((x) => !x.code?.startsWith('variables.') || x.level === 'error')
+    for (const f of blocking.filter((x) => x.code?.startsWith('variables.'))) variableErrors.push(f)
+    const rest = blocking.filter((x) => !x.code?.startsWith('variables.'))
+    if (rest.length && rest.every((f) => f.code === 'agent.unpublished' || f.code === 'agent.unavailable' || f.code === 'roster.empty')) {
       lines.push(
-        list.some((f) => f.code === 'roster.empty')
+        rest.some((f) => f.code === 'roster.empty')
           ? '  warning: It has no Agent on its roster here, so it stays a draft'
-          : `  warning: ${CHAT_APP_DRAFT}`,
+          : `  warning: ${CHAT_APP_DRAFT.replace('<slug>', slug)}`,
       )
-    } else {
-      lines.push(`  warning: It stays a draft here: ${list.map((f) => f.message).filter(Boolean).join('; ') || errorOf(published)}`)
+    } else if (rest.length || !variableErrors.length) {
+      lines.push(`  warning: It stays a draft here: ${rest.map((f) => f.message).filter(Boolean).join('; ') || errorOf(published)}`)
+    }
+  }
+  for (const f of variableFindings.filter((x) => x.level !== 'error')) lines.push(`  warning [${f.code}]: ${f.message ?? ''}`)
+  if (variableErrors.length) {
+    return {
+      ok: false,
+      output: [
+        `error [CHAT_APP_VARIABLES]: ${chatAppPath(slug)}: its variables can't be given as written (the draft is saved, and can't be published until they can)`,
+        ...variableErrors.map((f) => `  ${f.code}: ${f.message ?? ''}`),
+        ...lines,
+      ].join('\n'),
     }
   }
   lines.unshift(`  saved Chat App ${name}`)
   return { ok: true, output: lines.join('\n') }
 }
+
+/** Validation findings as the runtime gives them (`level`, `code`, `message`), from a response's `findings` or an error's `details`. */
+interface ChatAppFinding {
+  level?: 'error' | 'warning' | string
+  code?: string
+  message?: string
+}
+
+function findingsOf(raw: unknown): ChatAppFinding[] {
+  return Array.isArray(raw) ? raw.filter((f): f is ChatAppFinding => !!f && typeof f === 'object') : []
+}

package/src/local/local-check-inherited.ts

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join, normalize } from 'node:path'
+
+import { hash, readLock } from './local-sync-plan'
+
+/**
+ * What a pulled project holds as the workspace gave it: each item whose files
+ * are all byte for byte what the last pull wrote (`frontera.lock`), and each
+ * such file. A failure only there is inherited from the workspace: the
+ * person's change did not make it, and fixing it means changing the
+ * workspace's own item. Empty for a project that was never pulled.
+ */
+export interface Unchanged {
+  /** Item references (`function/staff-availability`, `dataset/media_x`) unchanged since the pull. */
+  refs: Set<string>
+  /** Project paths unchanged since the pull. */
+  files: Set<string>
+}
+
+export function unchangedSincePull(root: string): Unchanged {
+  const lock = readLock(root)
+  const refs = new Set<string>()
+  const files = new Set<string>()
+  if (!lock) return { refs, files }
+  for (const [ref, entry] of Object.entries(lock.items)) {
+    let all = Object.keys(entry.files ?? {}).length > 0
+    for (const [path, written] of Object.entries(entry.files ?? {})) {
+      const full = join(root, path)
+      const same = existsSync(full) && hash(readFileSync(full, 'utf8')) === written
+      if (same) files.add(normalize(path))
+      else all = false
+    }
+    if (all) refs.add(ref)
+  }
+  return { refs, files }
+}
+
+/**
+ * Whether a governed Action's semantic-type conflict is the workspace's: the
+ * Action's file, and each file the conflict rests on (the object type, its
+ * semantic type, the shared field it comes through), are all still as the
+ * pull wrote them. Then the Action deploys as the workspace runs it, with the
+ * conflict said as an inherited warning; one the person made (an edited
+ * Action, a narrowed type) is refused, as the platform refuses it.
+ */
+export function inheritedFromPull(unchanged: Unchanged): (action: string, refs: readonly string[]) => boolean {
+  return (action, refs) => unchanged.refs.has(`blueprint/actions/${action}`) && refs.every((ref) => unchanged.refs.has(ref))
+}
+
+/**
+ * The warnings inherited from the workspace on the governed Actions' rows:
+ * each Action deployed as the workspace runs it, with a value it offers that
+ * the semantic type it writes refuses. Listed by `local check`; never a
+ * failure, even with `--strict`: the Action runs, as it does in the workspace.
+ */
+export function inheritedActionWarnings(rows: ReadonlyArray<{ ref: string; warnings?: string[] }>): string[] {
+  return rows.flatMap((r) => (r.ref.startsWith('action/') ? r.warnings ?? [] : []))
+}
+
+/** The project files a typecheck's output names an error in (`functions/x/src/index.ts(411,5): error TS2322`). */
+export function typecheckErrorFiles(output: string): string[] {
+  const out = new Set<string>()
+  for (const m of output.matchAll(/^\s*([^\s(:][^():\n]*\.(?:ts|tsx|mts|cts|js|jsx))(?:\(\d+,\d+\)|:\d+:\d+)\s*[:-]?\s*error\b/gm)) out.add(normalize(m[1]!.replace(/^\.\//, '')))
+  return [...out]
+}
+
+/**
+ * Whether every failure is inherited: there is at least one, and each is in
+ * an item or file unchanged since the pull. One failure the change could have
+ * made (an edited or new file) and the step is the change's.
+ */
+export function allInherited(failures: readonly string[], inherited: ReadonlySet<string>): boolean {
+  return failures.length > 0 && failures.every((f) => inherited.has(f))
+}
+
+const BLUEPRINT_ROWS: Record<string, string> = { objectType: 'object-types', action: 'actions', linkType: 'link-types', metric: 'metrics', semanticType: 'semantic-types', sharedField: 'shared-fields', objectSet: 'object-sets' }
+
+/** A status row's reference as the lock names the item: `objectType/Receipt` → `blueprint/object-types/Receipt`. */
+export function lockRefOf(rowRef: string): string {
+  const at = rowRef.indexOf('/')
+  const folder = at > 0 ? BLUEPRINT_ROWS[rowRef.slice(0, at)] : undefined
+  return folder ? `blueprint/${folder}/${rowRef.slice(at + 1)}` : rowRef
+}

package/src/local/local-cities.ts

@@ -0,0 +1,89 @@
+/**
+ * Cities sample data names for a custom `--region` point (`<lat>,<lon>[,<km>]`):
+ * the city a point is near, so a record's `city` agrees with its coordinates
+ * (e2e G4: a point on Denver gave every Site the made-up "West Ernesto").
+ *
+ * The large metropolitan areas of the countries sample data knows, and of a
+ * few more, with how far each reaches from its centre. A point near none of
+ * them keeps one made-up city for the whole region, as before.
+ */
+
+export interface City {
+  name: string
+  lat: number
+  lon: number
+  /** How far the city reaches from its centre, in kilometres. */
+  reachKm: number
+}
+
+const c = (name: string, lat: number, lon: number, reachKm = 25): City => ({ name, lat, lon, reachKm })
+
+export const CITIES: readonly City[] = [
+  // United States
+  c('New York', 40.71, -74.01, 35), c('Los Angeles', 34.05, -118.24, 40), c('Chicago', 41.88, -87.63, 35), c('Houston', 29.76, -95.37, 35),
+  c('Phoenix', 33.45, -112.07, 30), c('Philadelphia', 39.95, -75.17), c('San Antonio', 29.42, -98.49), c('San Diego', 32.72, -117.16),
+  c('Dallas', 32.78, -96.8, 35), c('Austin', 30.27, -97.74), c('San Jose', 37.34, -121.89, 20), c('San Francisco', 37.77, -122.42, 20),
+  c('Seattle', 47.61, -122.33), c('Denver', 39.74, -104.99, 30), c('Boston', 42.36, -71.06), c('Washington', 38.91, -77.04),
+  c('Atlanta', 33.75, -84.39, 30), c('Miami', 25.76, -80.19), c('Minneapolis', 44.98, -93.27), c('Detroit', 42.33, -83.05),
+  c('Portland', 45.52, -122.68), c('Las Vegas', 36.17, -115.14), c('Salt Lake City', 40.76, -111.89), c('Nashville', 36.16, -86.78),
+  c('Charlotte', 35.23, -80.84), c('Kansas City', 39.1, -94.58), c('St. Louis', 38.63, -90.2), c('Orlando', 28.54, -81.38),
+  c('Tampa', 27.95, -82.46), c('Pittsburgh', 40.44, -79.99), c('Cleveland', 41.5, -81.69), c('Columbus', 39.96, -83.0),
+  c('Indianapolis', 39.77, -86.16), c('Baltimore', 39.29, -76.61, 20), c('Sacramento', 38.58, -121.49), c('New Orleans', 29.95, -90.07),
+  c('Honolulu', 21.31, -157.86), c('Anchorage', 61.22, -149.9), c('Albuquerque', 35.08, -106.65), c('Oklahoma City', 35.47, -97.52),
+  c('Raleigh', 35.78, -78.64), c('Milwaukee', 43.04, -87.91),
+  // Canada, Mexico and South America
+  c('Toronto', 43.65, -79.38, 30), c('Montreal', 45.5, -73.57), c('Vancouver', 49.28, -123.12), c('Calgary', 51.05, -114.07),
+  c('Mexico City', 19.43, -99.13, 35), c('São Paulo', -23.55, -46.63, 35), c('Rio de Janeiro', -22.91, -43.17, 30), c('Brasília', -15.79, -47.88),
+  c('Belo Horizonte', -19.92, -43.94), c('Salvador', -12.97, -38.5), c('Porto Alegre', -30.03, -51.23), c('Recife', -8.05, -34.88),
+  c('Fortaleza', -3.73, -38.53), c('Curitiba', -25.43, -49.27), c('Buenos Aires', -34.6, -58.38, 30), c('Santiago', -33.45, -70.67),
+  c('Bogotá', 4.71, -74.07), c('Lima', -12.05, -77.04),
+  // Indonesia, Malaysia, Singapore, the Philippines and the rest of Asia
+  c('Jakarta', -6.2, 106.82, 30), c('Surabaya', -7.25, 112.75), c('Bandung', -6.92, 107.61), c('Medan', 3.59, 98.67),
+  c('Semarang', -6.97, 110.42), c('Makassar', -5.15, 119.43), c('Yogyakarta', -7.8, 110.36, 20), c('Denpasar', -8.65, 115.22, 20),
+  c('Palembang', -2.98, 104.75), c('Balikpapan', -1.24, 116.85), c('Kuala Lumpur', 3.14, 101.69), c('George Town', 5.41, 100.33),
+  c('Johor Bahru', 1.49, 103.74, 15), c('Kota Kinabalu', 5.98, 116.07), c('Kuching', 1.55, 110.36), c('Singapore', 1.35, 103.82, 15),
+  c('Manila', 14.6, 120.98), c('Cebu City', 10.32, 123.89), c('Davao City', 7.19, 125.46), c('Bangkok', 13.76, 100.5, 30),
+  c('Ho Chi Minh City', 10.82, 106.63), c('Hanoi', 21.03, 105.85), c('Hong Kong', 22.32, 114.17, 20), c('Seoul', 37.57, 126.98, 30),
+  c('Shanghai', 31.23, 121.47, 35), c('Beijing', 39.9, 116.41, 35), c('Tokyo', 35.68, 139.69, 30), c('Osaka', 34.69, 135.5),
+  c('Nagoya', 35.18, 136.91), c('Sapporo', 43.06, 141.35), c('Fukuoka', 33.59, 130.4), c('Kyoto', 35.01, 135.77, 15),
+  c('Sendai', 38.27, 140.87), c('Hiroshima', 34.39, 132.46), c('Mumbai', 19.08, 72.88, 30), c('Delhi', 28.61, 77.21, 35),
+  c('Bengaluru', 12.97, 77.59, 30), c('Hyderabad', 17.39, 78.49, 30), c('Chennai', 13.08, 80.27), c('Kolkata', 22.57, 88.36),
+  c('Pune', 18.52, 73.86), c('Ahmedabad', 23.02, 72.57), c('Jaipur', 26.91, 75.79),
+  // Oceania
+  c('Sydney', -33.87, 151.21, 35), c('Melbourne', -37.81, 144.96, 35), c('Brisbane', -27.47, 153.03, 30), c('Perth', -31.95, 115.86, 30),
+  c('Adelaide', -34.93, 138.6), c('Canberra', -35.28, 149.13, 15), c('Hobart', -42.88, 147.33, 15), c('Darwin', -12.46, 130.84, 15),
+  c('Gold Coast', -28.02, 153.4, 20), c('Auckland', -36.85, 174.76),
+  // Europe
+  c('London', 51.51, -0.12, 30), c('Manchester', 53.48, -2.24), c('Birmingham', 52.49, -1.89), c('Leeds', 53.8, -1.55, 20),
+  c('Glasgow', 55.86, -4.25, 20), c('Edinburgh', 55.95, -3.19, 15), c('Liverpool', 53.41, -2.98, 20), c('Bristol', 51.45, -2.59, 15),
+  c('Cardiff', 51.48, -3.18, 15), c('Belfast', 54.6, -5.93, 15), c('Newcastle upon Tyne', 54.98, -1.61, 15), c('Dublin', 53.35, -6.26),
+  c('Berlin', 52.52, 13.4), c('Hamburg', 53.55, 9.99), c('Munich', 48.14, 11.58), c('Cologne', 50.94, 6.96, 20),
+  c('Frankfurt', 50.11, 8.68, 20), c('Stuttgart', 48.78, 9.18, 20), c('Düsseldorf', 51.23, 6.77, 15), c('Leipzig', 51.34, 12.37, 15),
+  c('Paris', 48.86, 2.35), c('Marseille', 43.3, 5.37), c('Lyon', 45.76, 4.84, 20), c('Toulouse', 43.6, 1.44, 20),
+  c('Nice', 43.7, 7.27, 15), c('Bordeaux', 44.84, -0.58, 20), c('Lille', 50.63, 3.06, 15), c('Nantes', 47.22, -1.55, 15),
+  c('Strasbourg', 48.57, 7.75, 15), c('Madrid', 40.42, -3.7), c('Barcelona', 41.39, 2.17), c('Valencia', 39.47, -0.38, 20),
+  c('Seville', 37.39, -5.98, 20), c('Bilbao', 43.26, -2.93, 15), c('Málaga', 36.72, -4.42, 15), c('Lisbon', 38.72, -9.14, 20),
+  c('Amsterdam', 52.37, 4.9, 20), c('Rotterdam', 51.92, 4.48, 15), c('The Hague', 52.08, 4.3, 10), c('Utrecht', 52.09, 5.12, 10),
+  c('Eindhoven', 51.44, 5.47, 10), c('Brussels', 50.85, 4.35, 20), c('Zurich', 47.38, 8.54, 15), c('Vienna', 48.21, 16.37, 20),
+  c('Rome', 41.9, 12.5), c('Milan', 45.46, 9.19), c('Copenhagen', 55.68, 12.57, 20), c('Stockholm', 59.33, 18.07),
+  c('Oslo', 59.91, 10.75, 20), c('Warsaw', 52.23, 21.01), c('Istanbul', 41.01, 28.98, 35),
+  // The Middle East and Africa
+  c('Dubai', 25.2, 55.27, 30), c('Abu Dhabi', 24.45, 54.38), c('Doha', 25.29, 51.53, 20), c('Riyadh', 24.71, 46.68, 30),
+  c('Cairo', 30.04, 31.24, 30), c('Lagos', 6.52, 3.38, 30), c('Nairobi', -1.29, 36.82), c('Johannesburg', -26.2, 28.05, 30),
+  c('Cape Town', -33.92, 18.42),
+]
+
+/**
+ * The city a custom region's point is in or near: the nearest city whose reach,
+ * widened by the region's own radius (at most 60 km), holds the point. Null
+ * when the point is near none of them.
+ */
+export function cityNear(point: { lat: number; lon: number }, radiusKm: number, distanceKm: (a: { lat: number; lon: number }, b: { lat: number; lon: number }) => number): City | null {
+  let best: { city: City; d: number } | null = null
+  for (const city of CITIES) {
+    const d = distanceKm(city, point)
+    if (d > city.reachKm + Math.min(radiusKm, 60)) continue
+    if (!best || d < best.d) best = { city, d }
+  }
+  return best?.city ?? null
+}