@frontera-sdk/cli 1.53.5 → 1.53.6

package/src/commands/local/snapshot.ts

@@ -31,7 +31,7 @@ export const localSnapshot: Command = {
     flags: { exact: 'boolean' },
     summary: 'Save the local database as a baseline, or restore it, throwing away what was written since (local check does this around its tests)',
     details: [
-      'save keeps the database as it is now as the baseline, replacing the one before. restore puts the database back as the baseline holds it; the service, job engine and runner keep running and reconnect, and the command returns once the service reaches the database again (it waits up to 30 seconds).',
+      'save keeps the database as it is now as the baseline, replacing the one before. `local check` replaces it the same way just before its tests, so a restore after a check goes back to the database as it was before that check’s tests. restore puts the database back as the baseline holds it; the service, job engine and runner keep running and reconnect, and the command returns once the service reaches the database again (it waits up to 30 seconds).',
       'Workspace secrets are configuration, not data: restore keeps them as they are now (set, changed or deleted since the baseline), and `local check` keeps them across its rollback too. `--exact` puts the baseline\'s secrets back as well.',
       'The run history is kept the same way: conversations (an Agent test case\'s included), Agent sessions and runs, workflow and Function runs and evaluation runs are as they were before the restore, so results can be compared across runs; the records those runs wrote are rolled back. A history row that names a record the restore took away is left out and counted. `--exact` puts the baseline\'s history back as well.',
       'Items applied after the baseline count as not applied once it is restored: the next `frontera local dev` applies them again (a running one does so at once).',
@@ -57,7 +57,7 @@ export const localSnapshot: Command = {
     if (action === 'save') {
       // A document mid-read would be kept unread, its reading lost on a restore: the save waits (bounded) for it.
       const settled = ingest ? await settleKnowledge(ingest, state.credentials.workspaceId, { restoredAt: readBaseline(project, organizationId)?.restoredAt }) : null
-      const saved = await ctx.output.task('Saving the database as the baseline', () => saveBaseline(project, organizationId, { serviceAnswers: () => waitForDatabaseReady(`http://127.0.0.1:${state.ports.service}`) }, true))
+      const saved = await ctx.output.task('Saving the database as the baseline', () => saveBaseline(project, organizationId, { serviceAnswers: () => waitForDatabaseReady(`http://127.0.0.1:${state.ports.service}`) }, 'snapshot'))
       if (!saved.ok) throw new CliError(saved.note, { code: 'LOCAL_SNAPSHOT_FAILED', hint: 'see `frontera local logs postgres`' })
       const knowledge = settled?.lines ?? []
       return {

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

@@ -8,6 +8,7 @@ import { packFunctionSource } from '../../pack'
 import { createTarGz } from '../../tar'
 import { functionEntry } from '../../local/local-dev-sync'
 import { adoptProposedLessons } from '../../local/local-lessons'
+import { mcpServersNotCarried } from '../../local/local-mcp-servers'
 import { localProject, type LocalProject } from '../../local/local-project'
 import { HISTORY_KINDS, projectAtRevision } from '../../local/local-sync-base'
 import { normalizeOrigin, unwrap } from '../../local/local-sync-client'
@@ -463,7 +464,7 @@ async function workspaceModels(api: Platform): Promise<WorkspaceModel[]> {
   }
 }
 
-function previewText(link: SyncLink, items: PushItem[], kept: { title: string } | null, orgNote: string | null, available: boolean, usedBy: Map<string, string[]> = new Map(), person: ReturnType<typeof needsAPerson> = []): string {
+function previewText(link: SyncLink, items: PushItem[], kept: { title: string } | null, orgNote: string | null, available: boolean, usedBy: Map<string, string[]> = new Map(), person: ReturnType<typeof needsAPerson> = [], notCarried: string | null = null): string {
   const ok = items.filter((i) => i.proposable && !i.sample)
   const samples = items.filter((i) => i.proposable && i.sample)
   const not = items.filter((i) => !i.proposable)
@@ -480,6 +481,7 @@ function previewText(link: SyncLink, items: PushItem[], kept: { title: string }
   if (before.length) lines.push('', 'Needs a person before Apply:', ...before.flatMap((p) => [`  - ${p.step}: ${p.message}`, `      Fix: ${p.fix}`]))
   if (after.length) lines.push('', 'Left for a person after Apply:', ...after.flatMap((p) => [`  - ${p.step}: ${p.message}`, `      Then: ${p.fix}`]))
   if (orgNote) lines.push('', orgNote)
+  if (notCarried) lines.push('', notCarried)
   if (!available) lines.push('', 'This platform does not take change requests yet.')
   if (ok.length && available) lines.push('', 'Propose with `frontera local sync push -t "<title>"`, or name items to propose only those.')
   return lines.join('\n')
@@ -567,11 +569,15 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
   const updating = kept && isOpen(kept.state) ? kept : null
   const orgStored = !!getSyncKey(project, 'organization')
   const titles = Object.fromEntries(all.map((i) => [i.ref, i.title]))
+  const mcp = mcpServersNotCarried(project.root)
+  const notCarried = mcp ? { mcpServers: mcp.files, save: mcp.command } : null
 
   let chosen: PushItem[]
   if (named.length) {
     const byRef = new Map(all.map((i) => [i.ref, i]))
     const unknown = named.filter((r) => !byRef.has(r))
+    const servers = unknown.filter((r) => r.startsWith('mcp-server'))
+    if (mcp && servers.length) throw new UsageError(`a change request does not carry ${servers.join(', ')}`, mcp.line)
     if (unknown.length) throw new UsageError(`nothing to propose in ${unknown.join(', ')}: ${unknown.length === 1 ? 'it matches' : 'they match'} the workspace, or the project has no such item`, 'list what can be proposed with `frontera local sync push --preview`')
     chosen = named.map((r) => byRef.get(r)!)
   } else chosen = all
@@ -600,9 +606,10 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
         // Apply's steps in order, and the ones the project's credentials can't take (N3).
         applyPlan: checked.plan,
         needsPerson: person,
+        notCarried,
         fetchedAt: snapshot.fetchedAt,
       },
-      text: previewText(link, chosen, updating, orgNote, available, usedBy, person),
+      text: previewText(link, chosen, updating, orgNote, available, usedBy, person, mcp?.line),
     }
   }
 
@@ -619,7 +626,12 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
   }
   const going = chosen.filter((i) => i.proposable && !leftSamples.includes(i))
   const releaseAsks = parseReleases(flagString(ctx, 'release'))
-  if (!going.length && !releaseAsks.length) throw new CliError('nothing to propose: nothing changed here since the last pull', { code: 'SYNC_NOTHING_TO_PUSH', hint: 'change an item in the project first; `frontera local sync status` shows where it stands' })
+  if (!going.length && !releaseAsks.length) {
+    throw new CliError(`nothing to propose: nothing ${mcp ? 'a change request carries ' : ''}changed here since the last pull`, {
+      code: 'SYNC_NOTHING_TO_PUSH',
+      hint: `${mcp ? `${mcp.line} For anything else, ` : ''}change an item in the project first; \`frontera local sync status\` shows where it stands`,
+    })
+  }
   const title = flagString(ctx, 'title')?.trim()
   const description = flagString(ctx, 'description')
   // The current request still taking pushes is updated; one applied or closed (here or on the platform) is not.
@@ -671,6 +683,7 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
       notProposed: notProposed.map((i) => ({ ref: i.ref, code: i.blocked, message: i.reason, ...(i.fix ? { fix: i.fix } : {}) })),
       samples: leftSamples.map((i) => i.ref),
       organizationKey: { needed: needsOrganizationKey(view.items), stored: orgStored },
+      notCarried,
     },
     text: [
       `${target ? `Updated “${view.request.title}” in` : `Proposed “${view.request.title}” to`} ${link.workspaceName ?? link.workspace}: ${plural(view.items.length, 'item')}.`,
@@ -679,6 +692,7 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
       ...(notProposed.length ? ['', 'Not proposed:', ...notProposed.flatMap((i) => [`  ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`, ...(i.fix ? [`    Fix: ${i.fix}`] : [])])] : []),
       ...(leftSamples.length ? ['', `Left out: ${plural(leftSamples.length, 'sample')} from setting up the project (${leftSamples.map((i) => i.title).join(', ')}); name ${leftSamples.length === 1 ? 'it' : 'them'} to propose`] : []),
       ...(orgNote ? ['', orgNote] : []),
+      ...(mcp ? ['', mcp.line] : []),
       '',
       'Apply it with `frontera local sync request apply`; see it with `frontera local sync request`.',
     ].join('\n'),

package/src/commands/local/sync.ts

@@ -38,6 +38,7 @@ import { readWorkspace, type SyncSource } from '../../local/local-sync-remote'
 import { rememberLocalCatalog } from '../../local/local-sync-models'
 import { runningTarget, runtimeCatalog } from '../../local/local-providers'
 import { buildStatusText, projectBuildSummary } from '../../local/local-build-summary'
+import { mcpServersNotCarried } from '../../local/local-mcp-servers'
 import { kindTitle } from '../../local/local-sync-names'
 import { describeUnresolved } from '../../local/local-sync-refs'
 import { blockers, type Blocker, type Need } from '../../local/local-portability'
@@ -529,9 +530,10 @@ const status = async (ctx: CommandContext) => {
   const kept = currentRequest(readRequests(project.root, link.workspace))
   // How the last `local dev` left the project, counted as Forge's home counts it.
   const build = projectBuildSummary(project.root, project.id)
+  const mcp = mcpServersNotCarried(project.root)
   const request = kept ? `${kept.state === 'merged' ? 'Applied' : kept.applied && !kept.applied.ok && kept.state !== 'closed' ? 'Apply failed' : kept.state === 'closed' ? 'Closed' : 'Proposed'} · ${plural(kept.refs.length, 'item')} · ${kept.title}` : null
   return {
-    data: { link, keys, lastPull, ...none, ...(tally ?? { counts: null }), ...(plan ? { items: { ...itemStates(plan), ...Object.fromEntries(lessons.map((slug) => [`lessons/${slug}`, 'outgoing' as const])) } } : {}), fetchedAt, platform: platformOf(snapshot), error, organizationKeyFor, build },
+    data: { link, keys, lastPull, ...none, ...(tally ?? { counts: null }), ...(plan ? { items: { ...itemStates(plan), ...Object.fromEntries(lessons.map((slug) => [`lessons/${slug}`, 'outgoing' as const])) } } : {}), fetchedAt, platform: platformOf(snapshot), error, organizationKeyFor, build, notCarried: mcp ? { mcpServers: mcp.files, save: mcp.command } : null },
     text: [
       `Linked to ${link.workspaceName ?? link.workspace}${link.organizationName ? ` (${link.organizationName})` : ''} on ${new URL(link.platform).host}`,
       `  Last pull   ${lastPull ? when(lastPull) : 'never'}`,
@@ -543,6 +545,7 @@ const status = async (ctx: CommandContext) => {
       ...(request ? [`  Request     ${request}`] : []),
       ...(build ? [`  Build       ${buildStatusText(build)}`] : []),
       ...(organizationKeyFor ? ['  Actions     this workspace’s workflows use governed Actions: run `frontera local sync connect` again with an organization key to bring them'] : []),
+      ...(mcp ? [`  MCP servers ${mcp.files.join(', ')}: not in a change request; save with \`${mcp.command}\``] : []),
     ].join('\n'),
   }
 }

package/src/commands/mcp-server/index-commands.ts

@@ -1,17 +1,28 @@
+import { dirname, resolve } from 'node:path'
+
+import { FronteraError } from '@frontera-sdk/core/errors'
+
 import { PlatformApi } from '../../api/platform-api'
-import { UsageError } from '../../errors'
+import { CliError, UsageError } from '../../errors'
+import { targetFor } from '../../local/local-dev-sync'
+import { linkedSaveTarget, projectMcpServers, readMcpServerFile, savedLines, type SavedServer } from '../../local/local-mcp-servers'
+import { findSolutionRoot } from '../../local/local-project'
+import { isLoopback } from '../../remote-guard'
 import { table } from '../../table'
-import type { Command } from '../types'
+import type { Command, CommandContext } from '../types'
 
 /**
- * A workspace's own MCP servers: what is on the workspace, and taking one out
- * of service.
+ * A workspace's own MCP servers: saving one from its file, what is on the
+ * workspace, and taking one out of service.
  *
- * A server is authored as `mcp-servers/<slug>.yaml` in a project and saved by
- * `frontera local dev`, which also archives one whose file was removed. These
- * commands cover the rest: seeing what a workspace serves and where and how a
- * client connects, why a tool is left out for you, and archiving a server the
- * project never had a file for.
+ * A server is authored as `mcp-servers/<slug>.yaml` in a project. `frontera
+ * local dev` saves it on the local runtime, and archives one whose file was
+ * removed; a change request does not carry it, so `save` sends the file with
+ * the request `local dev` makes, to the workspace the project is linked to
+ * (or, unlinked or with `--profile`, the profile's). The rest:
+ * seeing what a workspace serves and where and how a client connects, why a
+ * tool is left out for you, and archiving a server the project never had a
+ * file for.
  */
 
 /** How a client connects: signing in with a Frontera account, or a key where sign-in is not offered. */
@@ -53,7 +64,7 @@ const list: Command = {
       data: rows,
       text:
         rows.length === 0
-          ? 'No MCP servers in this workspace. Add mcp-servers/<slug>.yaml to the project and run `frontera local dev` (`frontera local schema mcp-server` prints the format).'
+          ? 'No MCP servers in this workspace. Add mcp-servers/<slug>.yaml to the project and save it with `frontera mcp-server save mcp-servers/<slug>.yaml` (`frontera local schema mcp-server` prints the format).'
           : table(
               ['slug', 'name', 'tools', 'url'],
               rows.map((s) => [s.slug ?? '?', s.name ?? '', String(s.tools?.length ?? 0), s.url ?? '']),
@@ -102,4 +113,81 @@ const archive: Command = {
   },
 }
 
-export const mcpServerCommands: Command[] = [list, get, archive]
+/** The named file, or every server file in the project; its slug is its file name, as `local dev` reads it. */
+function serverFiles(cwd: string, named: string | undefined): Array<{ root: string; slug: string; file: string }> {
+  if (!named) {
+    const root = findSolutionRoot(cwd)
+    const all = projectMcpServers(root).map((s) => ({ root, ...s }))
+    if (!all.length) throw new UsageError('this project has no MCP server files', 'add mcp-servers/<slug>.yaml (`frontera local schema mcp-server` prints the format), then save it')
+    return all
+  }
+  const absolute = resolve(cwd, named)
+  const root = dirname(dirname(absolute))
+  const target = targetFor(root, absolute)
+  if (target?.kind !== 'mcp-server') {
+    throw new UsageError(`${named} is not an MCP server file`, 'an MCP server is mcp-servers/<slug>.yaml (or .yml, .json), named by its slug: lowercase letters, digits and dashes, starting with a letter')
+  }
+  return [{ root, slug: target.name, file: target.file }]
+}
+
+/**
+ * The credential a save goes with: the link's, unless the command names one
+ * (`--profile`, `--api-url`, `--workspace`, or `FRONTERA_TOKEN` with its
+ * origin). `FRONTERA_PROFILE` is not such a choice: Forge sets it to the
+ * directory's profile, the local runtime's in a project that has one.
+ */
+async function saveTarget(ctx: CommandContext, root: string): Promise<{ api: PlatformApi; where: string }> {
+  const named = ['profile', 'api-url', 'workspace'].some((f) => typeof ctx.flags[f] === 'string') || !!process.env.FRONTERA_TOKEN?.trim()
+  const linked = named ? null : linkedSaveTarget(root)
+  if (linked) return { api: new PlatformApi(linked.platform, linked.key), where: linked.where }
+  const api = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+  const workspace = ctx.workspaceId ?? (await api.whoami().catch(() => null))?.workspaceId
+  const at = workspace ? `workspace ${workspace} on ${new URL(ctx.apiUrl).host}` : ctx.apiUrl
+  return { api, where: isLoopback(ctx.apiUrl) ? `${at}, a local runtime` : at }
+}
+
+const save: Command = {
+  meta: {
+    noun: 'mcp-server',
+    verb: 'save',
+    args: [{ name: 'file', required: false, description: 'mcp-servers/<slug>.yaml; every MCP server file in the project when left out' }],
+    flags: {},
+    summary: 'Save an MCP server from its file to the workspace: created, or updated in place. A change request does not carry MCP servers',
+    details: [
+      'In a project linked with `frontera local sync connect`, it saves to the linked workspace with the project\'s workspace key, the workspace `frontera local sync push` proposes to. `--profile <name>` saves to that profile\'s workspace instead, and so does an unlinked project\'s save. The output names the workspace it saved to.',
+    ],
+    examples: ['frontera mcp-server save mcp-servers/tracker.yaml', 'frontera mcp-server save', 'frontera mcp-server save mcp-servers/tracker.yaml --profile acme --json'],
+  },
+  async run(ctx) {
+    const files = serverFiles(ctx.cwd, ctx.positional[0])
+    // Every file read before anything is sent.
+    const docs = files.map((f) => {
+      const read = readMcpServerFile(f.root, f.file)
+      if (!read.ok) throw new UsageError(read.problem, 'fix the file (`frontera local schema mcp-server` prints the format), then save again')
+      return { ...f, doc: read.doc }
+    })
+    const { api, where } = await saveTarget(ctx, files[0]!.root)
+    const saved: Array<{ slug: string; file: string } & SavedServer> = []
+    for (const f of docs) {
+      try {
+        saved.push({ slug: f.slug, file: f.file, ...(await api.saveMcpServer(f.slug, f.doc)) })
+      } catch (err) {
+        // The service's reason for closing the route to organization keys, which its 403 names only by a code.
+        if (err instanceof FronteraError && (err.details as { detail?: unknown } | undefined)?.detail === 'org-key-route-closed') {
+          throw new CliError(`MCP server ${f.slug} was refused: an organization key names no person, and a workspace MCP server runs every tool as the person connected, so it is saved only with a person's sign-in or a workspace key`, {
+            code: 'FORBIDDEN',
+            hint: 'save it with a profile that signs in as a person or holds a workspace key (`--profile <name>`; `frontera auth list` shows them)',
+            cause: err,
+          })
+        }
+        throw err
+      }
+    }
+    return {
+      data: saved.map((s) => ({ ...s, where })),
+      text: [`Saved to ${where}:`, ...saved.flatMap((s) => savedLines(s.slug, s, 'updated'))].join('\n'),
+    }
+  },
+}
+
+export const mcpServerCommands: Command[] = [list, get, save, archive]

package/src/commands/registry.ts

@@ -212,7 +212,7 @@ const NOUN_SUMMARY: Readonly<Record<string, string>> = {
   pack: 'Reusable skill bundles — author once, install per workspace',
   secret: 'Workspace secrets — named here, never printed back',
   'chat-app': 'Chat Apps — stage, publish and open an Agent roster',
-  'mcp-server': 'Workspace MCP servers — list, inspect and archive',
+  'mcp-server': 'Workspace MCP servers — save, list, inspect and archive',
   function: 'Functions — TypeScript deployed here, run on a schedule',
   workflow: 'Workflows — declared steps, versioned, promoted, then run',
   blueprint: 'The shared model of the organization — what an app can read',

package/src/flag-help.ts

@@ -127,6 +127,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   framework: 'App scaffold to create: next (default) or react (legacy Vite)',
   port: 'loopback port to listen on — the App development server, or the Forge daemon (0: any free port)',
   'no-open': 'start local development without opening a browser window',
+  detach: 'start the App development server in its own session and return once it answers: it keeps running after this shell ends',
   'no-install': 'scaffold without running `bun install` — for an offline machine or a sandbox',
   'no-git': 'scaffold without creating a repository and an initial commit',
   'no-components': 'scaffold without fetching the baseline shadcn components',
@@ -283,7 +284,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   title: 'the change request’s title; a push that opens a new one needs it',
   why: 'a person-step: why it is needed now, in a sentence',
   changes: 'a person-step: what it changes, in the workspace’s words',
-  credential: 'a person-step: who or what it needs (workspace-key, organization-key, steward, admin, second-person, person)',
+  credential: 'a person-step: who or what it needs (workspace-key, organization-key, steward, admin, second-person, person, registry-owner)',
   delivery: 'a person-step: the delivery it belongs to; steps with the same one show as one card',
   all: 'list the settled ones too',
   browser: 'sign in by approving a code in the browser, as yourself',

package/src/forge/permission-rules.ts

@@ -113,6 +113,8 @@ export const FRONTERA_PERSON_COMMANDS: readonly string[] = [
   'app rollback',
   'agent publish',
   'chat-app publish',
+  // Live in the workspace at once, its tools run as whoever connects; a change request does not carry it.
+  'mcp-server save',
   'function promote',
   'workflow promote',
   'local sync request apply',

package/src/local/local-app-runtime.ts

@@ -1,6 +1,6 @@
 import { join } from 'node:path'
 
-import { readState } from '../project'
+import { appBinding, readState } from '../project'
 import { customAppFolders } from './local-apps'
 import type { LocalCredentials } from './local-state'
 
@@ -42,16 +42,18 @@ export function workspaceGet(serviceUrl: string, creds: Pick<LocalCredentials, '
  * holds it. Null when the runtime could not be asked; a folder the runtime
  * could not answer for is left out (the folder's record speaks for it).
  */
-export async function liveAppDeployments(root: string, get: Get | null): Promise<Map<string, LiveApp> | null> {
+export async function liveAppDeployments(root: string, get: Get | null, target: string): Promise<Map<string, LiveApp> | null> {
   if (!get) return null
   const out = new Map<string, LiveApp>()
   for (const dir of customAppFolders(root)) {
     const state = readState(join(root, dir))
     const deployment = typeof state.parentVersion === 'string' && state.parentVersion ? state.parentVersion : null
-    if (!deployment || !state.appId) continue
+    // The folder's App on this runtime (`appTarget`); an older CLI's single id otherwise.
+    const appId = appBinding(join(root, dir), target).id ?? state.appId
+    if (!deployment || !appId) continue
     const name = dir.split('/').pop()!
     try {
-      const res = await get(`/v1/platform-apps/${encodeURIComponent(state.appId)}/deployments`)
+      const res = await get(`/v1/platform-apps/${encodeURIComponent(appId)}/deployments`)
       if (res.status === 404) {
         out.set(name, { app: false, deployment: null })
         continue

package/src/local/local-build-inputs.ts

@@ -1,4 +1,5 @@
 import { liveActionStates, localActionCalls, type LiveAction } from './local-actions'
+import { appTarget } from '../project'
 import { liveAppDeployments, workspaceGet, type LiveApp } from './local-app-runtime'
 import { projectBuildRows, projectBuildSummary, type BuildRow, type ProjectBuildSummary } from './local-build-summary'
 import { localSecretPresence, type SecretPresence } from './local-secrets'
@@ -26,7 +27,7 @@ export async function runtimeBuildInputs(state: LocalState | null, root?: string
   const [live, secrets, apps] = await Promise.all([
     creds.orgKey ? Promise.resolve().then(() => liveActionStates(localActionCalls(serviceUrl, creds))).catch(() => null) : Promise.resolve(null),
     localSecretPresence(serviceUrl, creds).catch(() => null),
-    root ? liveAppDeployments(root, workspaceGet(serviceUrl, creds)).catch(() => null) : Promise.resolve(null),
+    root ? liveAppDeployments(root, workspaceGet(serviceUrl, creds), appTarget(serviceUrl, creds.workspaceId)).catch(() => null) : Promise.resolve(null),
   ])
   return { live, secrets, apps }
 }

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

@@ -1,9 +1,7 @@
-import { createHash } from 'node:crypto'
 import { readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { writeFileAtomic } from '../fs-atomic'
-import { loadHashes } from './local-applied'
 import { appDeployments, appsLostByRestore, appsLostWords, markAppsLostByRestore, type AppLostByRestore } from './local-app-restore'
 import { execInContainer, queryInContainer } from './local-docker'
 import { dumpHistory, historyWords, loadHistory, type HistoryCarried } from './local-history-carry'
@@ -20,12 +18,19 @@ import { containerName } from './local-supervisor'
  * `realActions` or a `decision`) is rolled back afterwards instead of growing
  * the data on every `local check`.
  *
- * The baseline is keyed by the applied build: a digest of what `local dev`
- * recorded as applied (`applied-hashes.json`). It is taken again only when
- * that changed. A copy of the hash and build records is kept with it, so a
- * restore puts the CLI's record of what is applied back with the database:
- * anything applied after the baseline counts as not applied, and the next
- * `local dev` applies it again.
+ * Every save takes a new copy: the baseline is the database just before what
+ * is to be rolled back (`local check` saves it after its apply, right before
+ * its tests), so a restore takes away only what was written since. A copy kept
+ * from an earlier save would also take away what was written between the two,
+ * such as a person's sign-up or an App's records. A copy of the hash and build
+ * records is kept with it, so a restore puts the CLI's record of what is
+ * applied back with the database: anything applied after the baseline counts
+ * as not applied, and the next `local dev` applies it again.
+ *
+ * A check's baseline is marked from its save until its restore, so a check
+ * cut off in between (Ctrl+C, an agent's time limit, a crash), which left
+ * its tests' writes, is put right by the next check before it applies
+ * (`restoreCutOffCheck`).
  *
  * Only the platform database is copied. The managed datasets' catalog
  * database, object storage and local traces are left as they are.
@@ -52,6 +57,8 @@ import { containerName } from './local-supervisor'
  */
 
 export const BASELINE_DB = `${POSTGRES_DB}_baseline`
+/** What took a baseline: `local check`, `local snapshot save`, `local data load`, or an Agent conversation with rollback (MCP `agent_chat`). */
+export type BaselineSaver = 'check' | 'snapshot' | 'data' | 'conversation'
 /** The database psql connects to while it copies, drops and creates the platform's. */
 const MAINTENANCE_DB = 'postgres'
 
@@ -60,8 +67,6 @@ export interface BaselineRecord {
   organizationId: string
   database: string
   baseline: string
-  /** The applied build the baseline is of (`buildHash`). */
-  buildHash: string
   savedAt: string
   saveMs: number
   /** `applied-hashes.json` and `build.json` as they were when the baseline was taken; null when absent. */
@@ -74,6 +79,10 @@ export interface BaselineRecord {
    * Absent on a baseline taken before it was kept.
    */
   apps?: Record<string, string | null>
+  /** Absent on a baseline an older CLI took. */
+  savedBy?: BaselineSaver
+  /** A `local check` took it and has not restored it yet: still running, or cut off before its rollback. */
+  checkInProgress?: boolean
   restoredAt?: string
   restoreMs?: number
 }
@@ -102,8 +111,6 @@ export interface SnapshotOutcome {
   /** What happened, in a line. */
   note: string
   ms: number
-  /** save: false when the stored baseline is already of this build. */
-  took?: boolean
   /** restore: items applied after the baseline, now counted as not applied (Custom Apps deployed after it included). */
   reapply?: number
   /** restore: the Custom Apps deployed after the baseline, which the restored database does not have. */
@@ -136,26 +143,11 @@ function readText(path: string): string | null {
   }
 }
 
-/**
- * What is applied to this runtime, as one digest: the hash record, in a stable
- * order, and each Custom App's deployment. An App deployed since the baseline
- * changes it, so `local check` takes the baseline again rather than rolling the
- * App back out of the runtime after its tests.
- */
-export function buildHash(project: LocalProject, organizationId: string): string {
-  const entries = [...loadHashes(project, organizationId)].sort(([a], [b]) => a.localeCompare(b))
-  const apps = Object.entries(appDeployments(project.root)).filter(([, d]) => d).sort(([a], [b]) => a.localeCompare(b))
-  const hash = createHash('sha256').update(organizationId).update('\0').update(JSON.stringify(entries))
-  // Only when there is one, so a project without Apps keeps the digest its baseline was taken under.
-  if (apps.length) hash.update('\0apps\0').update(JSON.stringify(apps))
-  return hash.digest('hex')
-}
-
 /** The stored baseline's record, for this organization (after a reset the runtime is another one). */
 export function readBaseline(project: LocalProject, organizationId: string): BaselineRecord | null {
   try {
     const saved = JSON.parse(readFileSync(recordPath(project), 'utf8')) as Partial<BaselineRecord>
-    return saved.version === 1 && saved.organizationId === organizationId && typeof saved.buildHash === 'string' ? (saved as BaselineRecord) : null
+    return saved.version === 1 && saved.organizationId === organizationId ? (saved as BaselineRecord) : null
   } catch {
     return null
   }
@@ -225,24 +217,15 @@ function withLock<T>(project: LocalProject, run: () => Promise<T>): Promise<T> {
   return run().finally(() => rmSync(lockPath(project), { force: true }))
 }
 
-/**
- * Take the baseline of the database as it is now, unless the stored one is of
- * this build already (`force` takes it regardless).
- */
-export async function saveBaseline(project: LocalProject, organizationId: string, deps: SnapshotDeps = {}, force = false): Promise<SnapshotOutcome> {
+/** Take the baseline of the database as it is now, replacing the one before. */
+export async function saveBaseline(project: LocalProject, organizationId: string, deps: SnapshotDeps = {}, by?: BaselineSaver): Promise<SnapshotOutcome> {
   const exec = deps.exec ?? execInContainer
   const now = deps.now ?? Date.now
   const psql = psqlFor(project, exec)
-  const hash = buildHash(project, organizationId)
-  const stored = readBaseline(project, organizationId)
   const started = now()
-  if (!force && stored?.buildHash === hash && psql(exists(BASELINE_DB))) {
-    return { ok: true, took: false, ms: 0, note: `the stored baseline is of this build (taken ${stored.savedAt})` }
-  }
   return withLock(project, async () => {
-    // The copy before last is dropped first: a template is only ever this one build.
     if (!psql(`DROP DATABASE IF EXISTS ${BASELINE_DB}`)) {
-      return { ok: false, took: false, ms: now() - started, note: `couldn’t drop the previous baseline (${BASELINE_DB}); see \`frontera local logs postgres\`` }
+      return { ok: false, ms: now() - started, note: `couldn’t drop the previous baseline (${BASELINE_DB}); see \`frontera local logs postgres\`` }
     }
     psql(refuse(POSTGRES_DB, false))
     let copied = false
@@ -252,7 +235,7 @@ export async function saveBaseline(project: LocalProject, organizationId: string
       psql(refuse(POSTGRES_DB, true))
     }
     const ms = now() - started
-    if (!copied) return { ok: false, took: false, ms, note: `couldn’t copy the database to ${BASELINE_DB}: something kept a connection open; see \`frontera local logs postgres\`` }
+    if (!copied) return { ok: false, ms, note: `couldn’t copy the database to ${BASELINE_DB}: something kept a connection open; see \`frontera local logs postgres\`` }
     // Nothing connects to the baseline: it is only ever a template.
     psql(refuse(BASELINE_DB, false))
     await settle(deps)
@@ -262,15 +245,16 @@ export async function saveBaseline(project: LocalProject, organizationId: string
       organizationId,
       database: POSTGRES_DB,
       baseline: BASELINE_DB,
-      buildHash: hash,
       savedAt: new Date(now()).toISOString(),
       saveMs: ms,
       applied: readText(hashesFile(project)),
       build: readText(buildFile(project)),
       apps: appDeployments(project.root),
+      ...(by ? { savedBy: by } : {}),
+      ...(by === 'check' ? { checkInProgress: true } : {}),
     })
     const late = answering ? '' : '; the service isn’t answering since (see `frontera local logs service`)'
-    return { ok: true, took: true, ms, note: `took a baseline of the applied database (${ms} ms)${late}` }
+    return { ok: true, ms, note: `took a baseline of the database as it is now (${ms} ms)${late}` }
   })
 }
 
@@ -352,17 +336,49 @@ export async function restoreBaseline(project: LocalProject, organizationId: str
     const answering = deps.serviceAnswers ? await deps.serviceAnswers() : true
     const ms = now() - started
     // Written last: a watching `local dev` reads it to take the record above.
-    writeBaseline(project, { ...stored, restoredAt, restoreMs: ms })
+    writeBaseline(project, { ...stored, checkInProgress: undefined, restoredAt, restoreMs: ms })
     const kept = secretsWords(secrets)
     const ran = historyWords(history)
     const lostApps = appsLostWords(appsLost)
     const tail = `${reapply ? `; ${reapply} item${reapply === 1 ? '' : 's'} applied after the baseline will apply again on the next \`frontera local dev\`` : ''}${lostApps ? `; ${lostApps}` : ''}${kept ? `; ${kept}` : ''}${ran ? `; ${ran}` : ''}`
     const withSecrets = { ...(secrets ? { secrets } : {}), ...(history ? { history } : {}) }
     const counted = { reapply: reapply + appsLost.length, ...(appsLost.length ? { appsLost } : {}) }
-    if (!answering) return { ok: false, ms, ...counted, ...withSecrets, note: `restored the database (${ms} ms), but the service isn’t answering since: see \`frontera local logs service\`${tail}` }
-    return { ok: true, ms, ...counted, ...withSecrets, note: `restored the database as applied (${ms} ms)${tail}` }
+    const back = `restored the database to the baseline of ${stored.savedAt} (${ms} ms), so anything written since then is gone`
+    if (!answering) return { ok: false, ms, ...counted, ...withSecrets, note: `${back}, but the service isn’t answering since: see \`frontera local logs service\`${tail}` }
+    return { ok: true, ms, ...counted, ...withSecrets, note: `${back}${tail}` }
   })
 }
 
+/** How long after its save a cut-off check's baseline is put back by the next check: later, what was written since is more likely the person's own than a test's. */
+const CUT_OFF_RESTORE_MS = 60 * 60_000
+
+/**
+ * The baseline a `local check` cut off before its rollback took, put back:
+ * its tests' writes, and anything written since, are gone. When it was taken
+ * more than an hour ago, the data is left as it is instead and the mark
+ * cleared (`left`: when it was taken), so the next check goes on with a new
+ * baseline. Null when the last check finished (or the baseline was saved
+ * again since). The runtime lock keeps a second check from running, so a
+ * marked baseline found by a check is never a running check's.
+ */
+export async function restoreCutOffCheck(project: LocalProject, organizationId: string, deps: SnapshotDeps = {}): Promise<(SnapshotOutcome & { left?: string }) | null> {
+  const stored = readBaseline(project, organizationId)
+  if (!stored?.checkInProgress) return null
+  if ((deps.now ?? Date.now)() - Date.parse(stored.savedAt) <= CUT_OFF_RESTORE_MS) return restoreBaseline(project, organizationId, deps)
+  writeBaseline(project, { ...stored, checkInProgress: undefined })
+  return {
+    ok: true,
+    ms: 0,
+    left: stored.savedAt,
+    note: `the last \`frontera local check\` was cut off at ${stored.savedAt}, more than an hour ago, before it rolled back its tests’ writes. They are still in the data: rolling back now would also take away everything written since. \`frontera local snapshot restore\` puts that baseline back by hand until the next save of one, which a check makes before its tests`,
+  }
+}
+
+/** A check whose tests did not run after its save: nothing of theirs for a later check to put back. */
+export function endCheckBaseline(project: LocalProject, organizationId: string): void {
+  const stored = readBaseline(project, organizationId)
+  if (stored?.checkInProgress) writeBaseline(project, { ...stored, checkInProgress: undefined })
+}
+
 /** The record file's path relative to the project, which `local dev` watches for a restore. */
 export const BASELINE_RECORD = join('.frontera', 'local', 'db-baseline.json')