@frontera-sdk/cli 1.53.5 → 1.53.7

package/src/commands/local/check.ts

@@ -12,7 +12,7 @@ import { appPulledAsIs, keepBuildWrittenFiles } from '../../local/local-app-pull
 import { setAsideCopyPaths } from '../../local/local-app-sdk-paths'
 import { repullRefFor } from '../../local/local-app-code'
 import { customAppFolders } from '../../local/local-apps'
-import { readBaseline, restoreBaseline, saveBaseline } from '../../local/local-db-snapshot'
+import { endCheckBaseline, readBaseline, restoreBaseline, restoreCutOffCheck, saveBaseline } from '../../local/local-db-snapshot'
 import { localIngestApi, settleKnowledge, type KnowledgeSettle } from '../../local/local-knowledge-ingestion'
 import { localProject, type LocalProject } from '../../local/local-project'
 import { projectSecretLines } from '../../local/local-project-secrets'
@@ -53,12 +53,12 @@ import { flagBool, flagString, type Command, type CommandContext } from '../type
  *
  * The tests write for real (a workflow test always does, as does an Agent
  * case with `realActions` or a `decision`), so after the apply the database
- * is kept as a baseline (`local-db-snapshot.ts`, taken again only when what
- * is applied changed), and after the tests it is restored: each check starts
- * from the data the project's files make. The run history (conversations,
- * runs, evaluations) is kept across it (`local-history-carry.ts`), so one
- * check's results can be compared with the last. `--keep-state` keeps what the
- * tests wrote, to look at it.
+ * is kept as a baseline (`local-db-snapshot.ts`, a new copy every check), and
+ * after the tests it is restored: the tests' writes are rolled back, and what
+ * was written before the check (a person's sign-up, an App's records) stays.
+ * The run history (conversations, runs, evaluations) is kept across it
+ * (`local-history-carry.ts`), so one check's results can be compared with the
+ * last. `--keep-state` keeps what the tests wrote, to look at it.
  *
  * Knowledge documents are read by a background job whose work lands in the
  * database: before the baseline and the tests, the check waits (bounded)
@@ -104,10 +104,8 @@ export function blockedBy(step: CheckStepName, failed: ReadonlySet<CheckStepName
 /** What `--skip` may leave out: the runtime and the apply are the gate itself. */
 const SKIPPABLE: readonly CheckStepName[] = ['typecheck', 'unit', 'apps', 'agents', 'workflows']
 
-/** What became of the tests' writes: rolled back to the applied baseline, kept, or not rolled back and why. */
+/** What became of the tests' writes: rolled back to the baseline taken before them, kept, or not rolled back and why. */
 export interface CheckTestData {
-  /** taken: a new baseline after this apply; reused: the stored one is of this build. */
-  baseline?: 'taken' | 'reused'
   rolledBack: boolean
   /** --keep-state */
   kept?: boolean
@@ -406,6 +404,13 @@ async function check(ctx: CommandContext) {
       continue
     }
     if (step === 'apply') {
+      // A check cut off before its rollback left its tests' writes: its baseline goes back before this apply (within the hour).
+      const before = readState(project)
+      if (before?.credentials && running(project)) {
+        const cut = await restoreCutOffCheck(project, before.credentials.organizationId, { serviceAnswers: () => waitForDatabaseReady(`http://127.0.0.1:${before.ports.service}`) })
+        if (cut?.left) ctx.output.note(`── test data: ${cut.note}`)
+        else if (cut) ctx.output.note(`── test data: the last \`frontera local check\` stopped before it rolled back its tests’ writes, ${cut.ok ? 'so that is done first' : 'and they couldn’t be rolled back now'}: ${cut.note}`)
+      }
       say(step, 'frontera local dev --once')
       // Which Agents serve customers: an operating.json leaves an Agent out of the built-in Chat (X4).
       if (customerFacing.length) ctx.output.note(`   note: ${customerFacingWords(customerFacing)}`)
@@ -448,9 +453,9 @@ async function check(ctx: CommandContext) {
       if (state?.credentials && running(project) && testsWillRun()) {
         if (keepState) testData = { rolledBack: false, kept: true, note: 'kept what the tests write (--keep-state)' }
         else {
-          const saved = await saveBaseline(project, state.credentials.organizationId, { serviceAnswers: () => waitForDatabaseReady(`http://127.0.0.1:${state.ports.service}`) })
+          const saved = await saveBaseline(project, state.credentials.organizationId, { serviceAnswers: () => waitForDatabaseReady(`http://127.0.0.1:${state.ports.service}`) }, 'check')
           baselineReady = saved.ok
-          if (saved.ok) testData = { baseline: saved.took ? 'taken' : 'reused', rolledBack: false, note: saved.note }
+          if (saved.ok) testData = { rolledBack: false, note: saved.note }
           else testData = { rolledBack: false, note: `not rolled back: ${saved.note}` }
           ctx.output.note(`   test data: ${saved.ok ? saved.note : `couldn’t keep a baseline, so what the tests write stays: ${saved.note}`}`)
         }
@@ -666,7 +671,10 @@ async function check(ctx: CommandContext) {
         secretNotes.push(...lost)
       }
     }
-  } else if (testData?.kept && testsRan) ctx.output.note('── test data: the tests’ writes were kept (--keep-state); the next `frontera local check` rolls them back')
+  } else if (testData?.kept && testsRan) ctx.output.note('── test data: the tests’ writes were kept (--keep-state); they stay: the next `frontera local check` rolls back only its own tests’ writes')
+  // A baseline taken for tests that then did not run holds nothing of theirs to put back.
+  const ended = readState(project)
+  if (baselineReady && !testsRan && ended?.credentials) endCheckBaseline(project, ended.credentials.organizationId)
   const testDataField = { ...(testData && testsRan ? { testData } : {}), ...(customerFacing.length ? { customerFacing } : {}) }
 
   if (flagBool(ctx, 'stop')) {

package/src/commands/local/data.ts

@@ -114,7 +114,7 @@ async function loadCommand(ctx: Parameters<Command['run']>[0]) {
   const organizationId = state.credentials.organizationId
   const snapshot = !flagBool(ctx, 'no-snapshot')
   if (snapshot) {
-    const saved = await ctx.output.task('Saving the records first', () => saveBaseline(project, organizationId, { serviceAnswers: () => waitForDatabaseReady(serviceUrl) }, true))
+    const saved = await ctx.output.task('Saving the records first', () => saveBaseline(project, organizationId, { serviceAnswers: () => waitForDatabaseReady(serviceUrl) }, 'data'))
     if (!saved.ok) throw new CliError(`the records could not be saved first, so nothing was loaded: ${saved.note}`, { code: 'LOCAL_SNAPSHOT_FAILED', hint: '`--no-snapshot` loads without saving them' })
   }
   const persona = await actAsLocalPersona({ meta: { noun: 'action', verb: 'submit' }, cwd: ctx.cwd, apiUrl: serviceUrl, wanted: 'submitter' })

package/src/commands/local/dev.ts

@@ -29,7 +29,7 @@ import {
   type SyncProfiles,
   type SyncTarget,
 } from '../../local/local-dev-sync'
-import { applyBindings, applyKnowledge, applyPlugin, blueprintWithout, editableSets, embeddingsDiffer, localDirectory, mediaCatalogDatasetReason, pointMediaTypesAt, promoteWorkflow, resolveBlueprint, resolveTarget, type ObjectBuild, type ResolvedBlueprint } from '../../local/local-dev-references'
+import { applyBindings, applyKnowledge, applyPlugin, blueprintWithout, embeddingsDiffer, localDirectory, mediaCatalogDatasetReason, pointMediaTypesAt, promoteWorkflow, resolveBlueprint, resolveTarget, type ObjectBuild, type ResolvedBlueprint } from '../../local/local-dev-references'
 import { applyObjectSets, namesObjectSet, objectSetCalls } from '../../local/local-object-sets'
 import { applyTheme, themeCalls } from '../../local/local-themes'
 import { ensureMediaSets, mediaUpload } from '../../local/local-media-sets'
@@ -421,8 +421,6 @@ async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptio
     if (named) result = { ...result, output: `${result.output}\n${named}`.trim() }
   }
   let authoredAgain: string[] = []
-  // Object types whose editable fields were declared for their Actions below.
-  const editableDone = new Set<string>()
   if (actionCalls && blueprint) {
     const names = blueprint.actions.map((a) => a.apiName)
     // A decision pins the Action's contract, its object type's fields included, and a first
@@ -431,14 +429,6 @@ async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptio
       const again = await runCli(project, command, opts.auth)
       if (!again.ok) return again
     }
-    // What each Action may write (`backing.editable`): `blueprint apply` leaves backings to `bind`.
-    const appliedDir = blueprint.dir ? join(project.root, blueprint.dir) : join(project.root, 'blueprint')
-    const subjects = new Set(blueprint.actions.flatMap((a) => (a.fit.subject ? [a.fit.subject] : [])))
-    for (const [type, props] of editableSets(appliedDir, subjects)) {
-      editableDone.add(type)
-      const set = await runCli(project, ['blueprint', 'editable', type, '--set', props.join(','), '--profile', profiles.organization], opts.auth)
-      if (!set.ok && !/no change|already|unchanged/i.test(set.output)) notes = [notes, `  warning: ${type}'s editable fields (${props.join(', ')}) could not be declared: ${oneLine(applyErrorText(set.output))}`].filter(Boolean).join('\n')
-    }
     // An Action whose contract moved after its decision here blocks the publish, and a decision
     // cannot follow a new contract. On this runtime it is authored again under a new id: out of
     // the draft (`--prune` over a copy without it), then back from the files.
@@ -462,16 +452,6 @@ async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptio
     const refused = await prepareActions(actionCalls, names, new Set(authoredAgain))
     if (refused.size) return { ok: false, output: `error [BLUEPRINT_ACTIONS]: governed Action ${[...refused].map(([name, why]) => `${name}: ${why}`).join('; ')}` }
   }
-  // Every other type's `backing.editable` too, before the publish: an editable type's rows carry
-  // their record version, which an Action on it (one to come, or an App's) submits.
-  if (blueprint && opts.publish) {
-    const appliedDir = blueprint.dir ? join(project.root, blueprint.dir) : join(project.root, 'blueprint')
-    for (const [type, props] of editableSets(appliedDir, null)) {
-      if (editableDone.has(type)) continue
-      const set = await runCli(project, ['blueprint', 'editable', type, '--set', props.join(','), '--profile', profiles.organization], opts.auth)
-      if (!set.ok && !/no change|already|unchanged/i.test(set.output)) result = { ...result, output: `${result.output}\n  warning: ${type}'s editable fields (${props.join(', ')}) could not be declared: ${oneLine(applyErrorText(set.output))}` }
-    }
-  }
   const objectTypes = target.kind === 'blueprint' ? blueprintObjectTypes(blueprintRoot) : []
   // The workspace's grants beyond read (`blueprint/workspace-grants.yaml`); a file that is wrong fails the Blueprint, said by line.
   const workspaceGrants = target.kind === 'blueprint' ? readWorkspaceGrants(project.root) : null

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

@@ -489,7 +489,7 @@ async function status(ctx: CommandContext) {
       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 } : {}) })),
+      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 && 'pid' in 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).

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/steps.ts

@@ -1,6 +1,6 @@
 import { UsageError } from '../../errors'
 import { FRONTERA_READ_ONLY_COMMANDS } from '../../forge/permission-rules'
-import { addPersonStep, clearSettledSteps, CREDENTIAL_WORDS, CREDENTIALS, deliveryGroups, readPersonSteps, runStepChecks, settlePersonStep, type PersonStep } from '../../local/local-person-steps'
+import { addPersonStep, clearSettledSteps, CREDENTIAL_WORDS, CREDENTIALS, currentTarget, deliveryGroups, readPersonSteps, runStepChecks, settlePersonStep, staleProblem, type PersonStep, type StepTarget } from '../../local/local-person-steps'
 import { runSelf } from '../../mcp/mcp-cli'
 import { localProject } from '../../local/local-project'
 import { flagBool, flagString, type Command } from '../types'
@@ -15,11 +15,15 @@ import { flagBool, flagString, type Command } from '../types'
 
 const ACTIONS = ['list', 'add', 'done', 'dismiss', 'reopen', 'check', 'clear'] as const
 
-function stepLines(steps: PersonStep[]): string[] {
-  return steps.flatMap((s, n) => [
-    `  ${n + 1}. ${s.command ?? `${s.changes} (in the product)`}${s.check ? ' · checks itself' : ''}`,
-    `     ${s.why} Changes: ${s.changes} Needs ${CREDENTIAL_WORDS[s.credential] ?? s.credential}. (${s.id})`,
-  ])
+function stepLines(steps: PersonStep[], current: StepTarget | null): string[] {
+  return steps.flatMap((s, n) => {
+    const stale = staleProblem(s, current)
+    return [
+      `  ${n + 1}. ${s.command ?? `${s.changes} (in the product)`}${s.check ? ' · checks itself' : ''}`,
+      `     ${s.why} Changes: ${s.changes} Needs ${CREDENTIAL_WORDS[s.credential] ?? s.credential}. (${s.id})`,
+      ...(stale ? [`     ! Don't run it: ${stale}.`] : []),
+    ]
+  })
 }
 
 export const localSteps: Command = {
@@ -97,7 +101,7 @@ export const localSteps: Command = {
     const groups = deliveryGroups(steps)
     const settled = steps.filter((s) => s.status !== 'pending')
     const lines = groups.length
-      ? groups.flatMap((g) => [g.delivery ? `${g.delivery}:` : 'Other steps:', ...stepLines(g.steps), ''])
+      ? groups.flatMap((g) => [g.delivery ? `${g.delivery}:` : 'Other steps:', ...stepLines(g.steps, currentTarget(project.root)), ''])
       : ['No steps wait on the person.', '']
     if (flagBool(ctx, 'all') && settled.length) lines.push('Settled:', ...settled.map((s) => `  ${s.status === 'done' ? '✓' : '–'} ${s.command ?? s.changes} (${s.id})`))
     return { data: { pending: groups, ...(flagBool(ctx, 'all') ? { settled } : {}) }, text: lines.join('\n').trimEnd() }

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

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 
+import { signInStep } from '../../device-login'
 import { CliError, UsageError } from '../../errors'
 import { documentPath, readFolders, readPulledDocuments, recordPulledDocuments, sha256Of, type PulledDocument } from '../../local/local-knowledge-documents'
 import { assetFilename } from '../skill/bundle-commands'
@@ -8,10 +9,11 @@ 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'
-import { getSyncKey, readLink, setModelMapping, type SyncLink } from '../../local/local-sync-link'
+import { getSyncKey, readLink, registerTargetProfile, setModelMapping, targetOf, type SyncLink } from '../../local/local-sync-link'
 import { itemTitle } from '../../local/local-sync-names'
 import { checkBody, markMissingModels, markRefused, needsAPerson, planOf, type ApplyStep, type WorkspaceModel } from '../../local/local-sync-precheck'
 import { afterApplyOf, recordAfterApply } from '../../local/local-person-steps'
@@ -27,6 +29,7 @@ import {
   checksOf,
   currentRequest,
   describeOutcome,
+  failedName,
   functionEntryOf,
   isOpen,
   itemLine,
@@ -463,13 +466,15 @@ 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)
   const name = link.workspaceName ?? link.workspace
   const lines = [
-    ok.length ? `Would propose ${plural(ok.length, 'item')} to ${name}${kept ? `, updating “${kept.title}”` : ''}:` : `Nothing to propose to ${name}.`,
+    ok.length
+      ? `Would propose ${plural(ok.length, 'item')} to ${name}${kept ? `, updating “${kept.title}”` : ''}:`
+      : not.length ? `Nothing to propose to ${name}: ${plural(not.length, 'change')} here cannot go yet, each for the reason below.` : `Nothing to propose to ${name}.`,
     // Each item's notes under it.
     ...ok.flatMap((i) => [`  [x] ${pushItemLine(i)}`, ...(usedBy.has(i.ref) ? [`      ! Still used by ${usedBy.get(i.ref)!.join(', ')}: applying would be refused`] : []), ...i.notes.map((n) => `      · ${n}`)]),
   ]
@@ -480,6 +485,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 +573,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 +610,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 +630,21 @@ 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) {
+    // Changes the checks refused are changes still: say why each can't go, not that nothing changed.
+    const held = chosen.filter((i) => !i.proposable && !i.sample)
+    if (held.length) {
+      throw new CliError(`nothing to propose: ${plural(held.length, 'change')} here cannot go yet\n${held.flatMap((i) => [`  ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`, ...(i.fix ? [`      Fix: ${i.fix}`] : [])]).join('\n')}`, {
+        code: 'SYNC_PUSH_BLOCKED',
+        hint: `fix ${held.length === 1 ? 'it' : 'them'} as said, then check with \`frontera local sync push --preview\``,
+        details: { blocked: held.map((i) => ({ ref: i.ref, code: i.blocked, message: i.reason, ...(i.fix ? { fix: i.fix } : {}) })) },
+      })
+    }
+    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 +696,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 +705,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'),
@@ -957,7 +984,7 @@ async function apply(ctx: CommandContext) {
     throw new CliError(describeOutcome(outcome, allTitles).join('\n'), {
       code: 'SYNC_APPLY_FAILED',
       hint: /migration instruction/i.test(outcome.failure?.message ?? '') ? 'say what to do with existing records: apply again with `--migration "<instructions>"`' : 'once what failed is fixed, apply again (`frontera local sync request apply`); a fix in the project’s files is pushed first (`frontera local sync push`)',
-      details: { outcome, failed: outcome.failure ? { ref: outcome.failure.ref, title: allTitles[outcome.failure.ref] ?? outcome.failure.ref, message: outcome.failure.message } : null },
+      details: { outcome, failed: outcome.failure ? { ref: outcome.failure.ref, title: failedName(outcome, allTitles), message: outcome.failure.message } : null },
     })
   }
   // The workspace now has the applied versions: fetch, and move each applied item's base to them.
@@ -980,7 +1007,13 @@ async function apply(ctx: CommandContext) {
   // The Agents applied: their cases' last local runs become the baseline the next request's evals compare with.
   recordApplied(project, answer.items.filter((i) => i.kind === 'agent' && !i.deleted).map((i) => i.name))
   // What the request left for a person: kept as the delivery's person-steps, which Forge shows as Pending in workspace (N6).
-  const pending = recordAfterApply(project.root, answer.request.title, afterApplyOf(answer.outcome))
+  const after = afterApplyOf(answer.outcome)
+  // The steps change the workspace the request went to, so they name it: the folder is bound to its local runtime.
+  const { target, targetError } = after.length
+    ? await registerTargetProfile(project, link).then((name) => ({ target: name, targetError: null }), (err: Error) => ({ target: null, targetError: err.message }))
+    : { target: null, targetError: null }
+  const pending = recordAfterApply(project.root, answer.request.title, after, target ? { profile: target, target: targetOf(link) } : null)
+  const signIn = target && pending.length ? await signInStep({ profile: target, apiUrl: link.platform, named: true }) : null
   return {
     data: { applied: true, outcome, request: { id: answer.request.id, title: answer.request.title, state: answer.request.state }, fetched, pendingInWorkspace: pending },
     text: [
@@ -989,7 +1022,11 @@ async function apply(ctx: CommandContext) {
       '',
       fetched.error ? `Could not fetch afterwards: ${fetched.error}. Run \`frontera local sync fetch\`.` : `Fetched: ${plural(fetched.adopted.length, 'item')} now match${fetched.adopted.length === 1 ? 'es' : ''} the workspace.`,
       ...(pending.length
-        ? ['', `Pending in workspace (${pending.length}), for a person:`, ...pending.map((p) => `  - ${p.changes}${p.command ? `: \`${p.command}\`` : ''}${p.check ? ' (checks itself)' : ''}`), 'Forge lists them on the project’s home; `frontera local steps` here.']
+        ? ['', `Pending in workspace (${pending.length}), for a person:`, ...pending.map((p) => `  - ${p.changes}${p.command ? `: \`${p.command}\`` : ''}${p.check ? ' (checks itself)' : ''}`),
+          target
+            ? `They run against ${new URL(link.platform).host} with \`--profile ${target}\` (this project's keys), not the local runtime${signIn ? `; a step a signed-in person takes needs \`${signIn}\` first` : ''}.`
+            : `They name no target: the CLI could not record a profile for ${new URL(link.platform).host}${targetError ? ` (${targetError})` : ''}. Add \`--profile <a profile for that platform>\` when you run them.`,
+          'Forge lists them on the project’s home; `frontera local steps` here.']
         : []),
     ].join('\n'),
   }

package/src/commands/local/sync.ts

@@ -11,7 +11,7 @@ import { lessonsToPropose, pullLessons, type LessonsPulled } from '../../local/l
 import { analyticsNeeded, connectionsNeeded, documentationNeeded, standInPath, writePlatformOnly, writeStandIns } from '../../local/local-stand-ins'
 import { localProject, type LocalProject } from '../../local/local-project'
 import { normalizeOrigin, syncClient, type SyncClient } from '../../local/local-sync-client'
-import { getSyncKey, projectFile, readLink, removeSyncKey, setSyncKey, writeLink, type SyncLink } from '../../local/local-sync-link'
+import { getSyncKey, projectFile, projectKeyFingerprints, readLink, registerTargetProfile, removeSyncKey, removeTargetProfile, setSyncKey, targetProfileName, writeLink, type SyncLink } from '../../local/local-sync-link'
 import { describeRepair, repairBases, type BaseRepair } from '../../local/local-sync-base'
 import { conflictsId, mergeItemFiles, type Choice, type Conflict, type Side } from '../../local/local-sync-merge'
 import {
@@ -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'
@@ -433,11 +434,13 @@ const connect = async (ctx: CommandContext) => {
   }
   const blueprintFlag = flagString(ctx, 'blueprint')
   if (blueprintFlag && blueprintFlag !== 'workspace' && blueprintFlag !== 'organization') throw new UsageError('--blueprint is workspace or organization', '`--blueprint organization` reads the whole model and needs an organization key')
+  // The stored organization key belongs to the previous link's platform and organization: kept only while both stay.
+  const keepsOrganizationKey = !keys.organization && previous?.platform === platform && previous.organization === me.orgId
   const link: SyncLink = {
     platform,
     workspace: me.workspaceId!,
     workspaceName: identity?.workspace.name ?? previous?.workspaceName,
-    organization: keys.organization ? me.orgId! : previous?.organization,
+    organization: keys.organization ? me.orgId! : keepsOrganizationKey ? previous!.organization : undefined,
     organizationName: identity?.organization.name ?? previous?.organizationName,
     blueprint: (blueprintFlag as SyncLink['blueprint'] | undefined) ?? (previous?.blueprint === 'organization' && keys.organization ? 'organization' : 'workspace'),
     // The models mapped for this workspace stay; another workspace has its own catalog.
@@ -445,14 +448,26 @@ const connect = async (ctx: CommandContext) => {
   }
   // A folder that is not a project yet gets the project file the link lives in.
   if (!existsSync(projectFile(project.root))) writeFileSync(projectFile(project.root), `# A Frontera project. \`frontera local dev\` applies agents/, workflows/, functions/ and blueprint/.\nname: ${basename(project.root)}\n`)
+  // The previous target's profile goes with the keys it was made from.
+  if (previous && targetProfileName(project, previous) !== targetProfileName(project, link)) await removeTargetProfile(project, previous)
+  // Read before the keys are replaced, so a profile holding the key a rotation replaces is still the project's.
+  const previousKeys = projectKeyFingerprints(project)
   setSyncKey(project, 'workspace', keys.workspace)
   if (keys.organization) setSyncKey(project, 'organization', keys.organization)
+  else if (!keepsOrganizationKey) removeSyncKey(project, 'organization')
   writeLink(project.root, link)
+  // The workspace as a CLI profile: a change request's steps for a person name it (`--profile`).
+  const { profile, profileError } = await registerTargetProfile(project, link, previousKeys).then(
+    (name) => ({ profile: name, profileError: null }),
+    (err: Error) => ({ profile: null, profileError: err.message }),
+  )
   return {
-    data: { link, keys: { workspace: true, organization: !!(keys.organization || getSyncKey(project, 'organization')) } },
+    data: { link, keys: { workspace: true, organization: !!(keys.organization || getSyncKey(project, 'organization')) }, profile },
     text: [
       `Linked to ${link.workspaceName ?? link.workspace}${link.organizationName ? ` (${link.organizationName})` : ''} on ${new URL(platform).host}.`,
       'Keys are in your keychain; the link is in frontera.yaml.',
+      ...(profile ? [`A change request's steps for a person reach this platform with \`--profile ${profile}\`, not the local runtime.`] : []),
+      ...(profileError ? [`No CLI profile was recorded for this platform (${profileError}); a change request's steps for a person name none until one is.`] : []),
       'See what you can pull: `frontera local sync pull --preview`.',
     ].join('\n'),
   }
@@ -529,9 +544,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 +559,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'),
   }
 }
@@ -944,6 +961,8 @@ const resolve = async (ctx: CommandContext) => {
 const disconnect = async (ctx: CommandContext) => {
   const project = localProject(ctx.cwd)
   const link = readLink(project.root)
+  // First, while the keys that show the profile is the project's are still stored.
+  if (link) await removeTargetProfile(project, link)
   removeSyncKey(project, 'workspace')
   removeSyncKey(project, 'organization')
   const forget = flagBool(ctx, 'forget-link')

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/commands/types.ts

@@ -106,6 +106,8 @@ export interface CommandContext {
   cwd: string
   apiUrl: string
   token: string
+  /** The profile the credential came from, when it came from one. */
+  profile?: string
   positional: string[]
   flags: Record<string, string | boolean>
   /** Every value of a string flag given more than once (`flags` holds the last). */