@frontera-sdk/cli 1.53.5 → 1.53.7

package/src/local/local-mcp-servers.ts

@@ -2,7 +2,11 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { parse as parseYaml } from 'yaml'
 
+import { CliError } from '../errors'
 import { errorOf } from './local-chat-apps'
+import { allTargets } from './local-dev-sync'
+import { localProjectAt } from './local-project'
+import { getSyncKey, readLink, type SyncLink } from './local-sync-link'
 
 /**
  * A workspace's own MCP servers: `mcp-servers/<slug>.yaml` (or .yml, .json),
@@ -12,6 +16,11 @@ import { errorOf } from './local-chat-apps'
  * types the workspace is granted, its Functions, workflows and governed
  * Actions. A server whose file is deleted is archived on the runtime.
  *
+ * A change request carries no MCP servers: `frontera mcp-server save` sends
+ * the same file with the same request to the workspace the project is linked
+ * to (`local sync connect`), with its workspace key, as `local sync push`
+ * reaches it; to the profile's workspace in a project with no link.
+ *
  * Its format is the service's (`frontera local schema mcp-server`).
  */
 
@@ -24,45 +33,101 @@ export interface McpServerApplied {
   output: string
 }
 
-interface SavedServer {
+export interface SavedServer {
   server?: { slug?: string; name?: string; url?: string; signIn?: boolean; tools?: unknown[] }
   created?: boolean
   warnings?: Array<{ name?: string; reason?: string }>
 }
 
 /** The file as the service takes it: YAML or JSON, a mapping at the top. */
-export function readMcpServerFile(root: string, file: string): { ok: true; doc: Record<string, unknown> } | { ok: false; output: string } {
+export function readMcpServerFile(root: string, file: string): { ok: true; doc: Record<string, unknown> } | { ok: false; problem: string } {
   const path = join(root, file)
-  if (!existsSync(path)) return { ok: false, output: `error [MCP_SERVER]: ${file} is missing` }
+  if (!existsSync(path)) return { ok: false, problem: `${file} is missing` }
   let doc: unknown
   try {
     const text = readFileSync(path, 'utf8')
     doc = file.endsWith('.json') ? JSON.parse(text) : parseYaml(text)
   } catch (err) {
-    return { ok: false, output: `error [MCP_SERVER]: ${file} can't be read: ${(err as Error).message.split('\n')[0]}` }
+    return { ok: false, problem: `${file} can't be read: ${(err as Error).message.split('\n')[0]}` }
   }
   if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
-    return { ok: false, output: `error [MCP_SERVER]: ${file} must be a mapping with name, instructions and tools (\`frontera local schema mcp-server\`)` }
+    return { ok: false, problem: `${file} must be a mapping with name, instructions and tools (\`frontera local schema mcp-server\`)` }
   }
   return { ok: true, doc: doc as Record<string, unknown> }
 }
 
+/** Where a client connects to a saved server, and each tool offered to nobody for now. */
+export function savedLines(slug: string, saved: SavedServer | null, updated = 'applied'): string[] {
+  const tools = saved?.server?.tools?.length ?? 0
+  const url = saved?.server?.url
+  // A local runtime offers no sign-in: a client there sends the runtime's workspace key.
+  const how = saved?.server?.signIn === false ? " with the runtime's workspace key" : ''
+  const lines = [`  ${saved?.created ? 'created' : updated} MCP server ${slug} (${tools} tool${tools === 1 ? '' : 's'})${url ? ` — connect at ${url}${how}` : ''}`]
+  for (const warning of saved?.warnings ?? []) {
+    lines.push(`  warning: MCP server ${slug}: tool ${warning.name ?? '?'} is offered to nobody for now: ${warning.reason ?? 'unavailable'}`)
+  }
+  return lines
+}
+
 /** Save one server on the runtime; the line says where a client connects, or what the service refused. */
 export async function applyMcpServer(root: string, slug: string, file: string, call: Call): Promise<McpServerApplied> {
   const read = readMcpServerFile(root, file)
-  if (!read.ok) return read
+  if (!read.ok) return { ok: false, output: `error [MCP_SERVER]: ${read.problem}` }
   const res = await call('PUT', `/v1/mcp-servers/${encodeURIComponent(slug)}`, read.doc)
   if (res.status !== 200 && res.status !== 201) {
     return { ok: false, output: `error [MCP_SERVER]: MCP server ${slug} was refused: ${errorOf(res)}` }
   }
   const saved = ((res.body as { data?: unknown } | null)?.data ?? res.body) as SavedServer | null
-  const tools = saved?.server?.tools?.length ?? 0
-  const url = saved?.server?.url
-  // A local runtime offers no sign-in: a client there sends the runtime's workspace key.
-  const how = saved?.server?.signIn === false ? " with the runtime's workspace key" : ''
-  const lines = [`  ${saved?.created ? 'created' : 'applied'} MCP server ${slug} (${tools} tool${tools === 1 ? '' : 's'})${url ? ` — connect at ${url}${how}` : ''}`]
-  for (const warning of saved?.warnings ?? []) {
-    lines.push(`  warning: MCP server ${slug}: tool ${warning.name ?? '?'} is offered to nobody for now: ${warning.reason ?? 'unavailable'}`)
+  return { ok: true, output: savedLines(slug, saved).join('\n') }
+}
+
+/** The project's MCP server files, as `local dev` finds them. */
+export function projectMcpServers(root: string): Array<{ slug: string; file: string }> {
+  return allTargets(root).flatMap((t) => (t.kind === 'mcp-server' ? [{ slug: t.name, file: t.file }] : []))
+}
+
+/** "Orders (ws_1) on acme.frontera.example": the linked workspace in a sentence. */
+function linkedWorkspaceWords(link: SyncLink): string {
+  return `${link.workspaceName ?? link.workspace}${link.workspaceName ? ` (${link.workspace})` : ''} on ${new URL(link.platform).host}`
+}
+
+/**
+ * Where `frontera mcp-server save` sends a linked project's servers: the
+ * linked workspace, with the project's workspace key, which is what `local
+ * sync push` reaches and what its line names. The directory's profile in a
+ * project with a local runtime is the runtime's (`local start` binds it), and
+ * `local dev` already saves the files there. A workspace key acts for its
+ * creator, so the service lets it save a server as it lets `local dev`'s.
+ * Null when the project has no link. With a link and no key on this computer,
+ * refused rather than sent to the profile.
+ */
+export function linkedSaveTarget(root: string): { platform: string; key: string; where: string } | null {
+  const link = readLink(root)
+  if (!link) return null
+  const workspace = linkedWorkspaceWords(link)
+  const key = getSyncKey(localProjectAt(root), 'workspace')
+  if (!key) {
+    throw new CliError(`this project is linked to ${workspace}, and this computer holds no workspace key for it`, {
+      code: 'SYNC_NO_KEY',
+      hint: '`frontera local sync connect` stores one (keys are kept per computer); `--profile <name>` saves to that profile’s workspace instead',
+    })
   }
-  return { ok: true, output: lines.join('\n') }
+  return { platform: link.platform, key, where: `${workspace}, the workspace this project is linked to` }
+}
+
+/**
+ * What a push or `sync status` says of the project's MCP server files, which
+ * no change request carries, with the command that saves them. Null when the
+ * project has none.
+ */
+export function mcpServersNotCarried(root: string): { files: string[]; command: string; line: string } | null {
+  const files = projectMcpServers(root).map((s) => s.file)
+  if (!files.length) return null
+  const command = files.length === 1 ? `frontera mcp-server save ${files[0]}` : 'frontera mcp-server save'
+  const link = readLink(root)
+  const where = link
+    ? `${linkedWorkspaceWords(link)}, the workspace this project is linked to, with its workspace key (\`--profile <name>\` saves to a profile’s workspace instead)`
+    : 'the workspace your profile signs in to (`--profile <name>` picks another)'
+  const line = `A change request does not carry MCP servers (${files.join(', ')}): \`${command}\` saves ${files.length === 1 ? 'it' : 'every one'} to ${where}.`
+  return { files, command, line }
 }

package/src/local/local-person-steps.ts

@@ -2,6 +2,9 @@ import { existsSync, mkdirSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 
 import { writeFileAtomic } from '../fs-atomic'
+import { getProfile } from '../profiles'
+import { localProject } from './local-project'
+import { readLink, targetOf, targetProfileName } from './local-sync-link'
 
 /**
  * Person-steps (Forge improvement plan T4, N4): a step only the person may
@@ -25,7 +28,7 @@ import { writeFileAtomic } from '../fs-atomic'
 export const PERSON_STEPS_FILE = join('.frontera', 'sync', 'person-steps.json')
 
 /** Who or what the step needs. */
-export const CREDENTIALS = ['workspace-key', 'organization-key', 'steward', 'admin', 'second-person', 'person'] as const
+export const CREDENTIALS = ['workspace-key', 'organization-key', 'steward', 'admin', 'second-person', 'person', 'registry-owner'] as const
 export type Credential = (typeof CREDENTIALS)[number]
 
 /** Each credential in the person's words, as the card and the list say it. */
@@ -36,6 +39,7 @@ export const CREDENTIAL_WORDS: Record<Credential, string> = {
   admin: 'a workspace admin',
   'second-person': 'a second person (not whoever made the change)',
   person: 'you, signed in (`frontera auth login --browser`)',
+  'registry-owner': 'an owner of the organization that publishes the runtime images',
 }
 
 /**
@@ -67,12 +71,16 @@ export interface PersonStep {
   doneAt?: string
   /** Who saw it done: the person's mark, or its check. */
   doneBy?: 'person' | 'check'
-  /** Where it came from: the coding agent, or what a change request left after Apply. */
-  source?: 'agent' | 'change-request'
-  /** A change request's own key for it (`action-deploy:qualifyLead`), so applying again updates it. */
+  /** Where it came from: the coding agent, what a change request left after Apply, or the local runtime at a refusal only a person clears. */
+  source?: 'agent' | 'change-request' | 'runtime'
+  /** A change request's own key for it (`action-deploy:qualifyLead`), or the runtime's (`image-access:<repository>`), so recording it again updates it. */
   key?: string
   check?: StepCheck
   lastCheckedAt?: string
+  /** The workspace a change request's step acts on (`targetOf`): stale once the folder links elsewhere. */
+  target?: string
+  /** The profile its command and check name (`targetProfileName`): stale when it is gone or no longer the folder's. */
+  profile?: string
 }
 
 interface StepsFile {
@@ -118,12 +126,35 @@ function filePath(root: string): string {
 export function readPersonSteps(root: string): PersonStep[] {
   const path = filePath(root)
   if (!existsSync(path)) return []
+  let steps: PersonStep[]
   try {
     const parsed = JSON.parse(readFileSync(path, 'utf8')) as Partial<StepsFile>
-    return Array.isArray(parsed.steps) ? parsed.steps.filter((s): s is PersonStep => !!s && typeof s.id === 'string' && (typeof s.command === 'string' || s.command === null)) : []
+    steps = Array.isArray(parsed.steps) ? parsed.steps.filter((s): s is PersonStep => !!s && typeof s.id === 'string' && (typeof s.command === 'string' || s.command === null)) : []
   } catch {
     return []
   }
+  const current = steps.some((s) => s.profile) ? currentTarget(root) : null
+  return current ? steps.map((s) => aimedAt(s, current)) : steps
+}
+
+/**
+ * A change request's step recorded for the folder's target under another
+ * profile, aimed at the folder's profile for it. The profile name follows the
+ * folder's path, so it changes when the folder is moved or renamed, while the
+ * steps file moves with the folder.
+ */
+function aimedAt(step: PersonStep, current: StepTarget): PersonStep {
+  const was = step.profile
+  if (!was || step.target !== current.target || was === current.profile) return step
+  const swap = (command: string) => command.split(' ')
+    .map((word, i, words) => (word === was && words[i - 1] === '--profile' ? current.profile : word === `--profile=${was}` ? `--profile=${current.profile}` : word))
+    .join(' ')
+  return {
+    ...step,
+    profile: current.profile,
+    ...(step.command ? { command: swap(step.command) } : {}),
+    ...(step.check ? { check: { ...step.check, command: swap(step.check.command) } } : {}),
+  }
 }
 
 function writeSteps(root: string, steps: PersonStep[]): void {
@@ -133,19 +164,23 @@ function writeSteps(root: string, steps: PersonStep[]): void {
 }
 
 export interface NewPersonStep {
-  command: string
+  /** null for a step done outside the CLI, which only the CLI itself records. */
+  command: string | null
   why: string
   changes: string
   credential: string
   delivery?: string | null
   /** The read that proves it done, already checked (`checkProblem`). */
   check?: StepCheck
+  /** The CLI's own step, under a stable key: recording it again updates that step, and reopens it if it was settled. */
+  key?: string
+  source?: 'agent' | 'runtime'
 }
 
 /** Each problem with a step as given; empty when it can be recorded. */
 export function stepProblems(input: NewPersonStep): string[] {
   const problems: string[] = []
-  const command = commandProblem(input.command)
+  const command = input.command === null ? null : commandProblem(input.command)
   if (command) problems.push(command)
   if (!input.why?.trim()) problems.push('say why the step is needed (`why`)')
   if (!input.changes?.trim()) problems.push('say what the step changes (`changes`)')
@@ -160,17 +195,20 @@ export function stepProblems(input: NewPersonStep): string[] {
 /**
  * Record a step. The same command pending in the same delivery is the same
  * step, updated rather than listed twice, so an agent restating its plan
- * after a compaction doesn't double the card.
+ * after a compaction doesn't double the card. A keyed step is one step
+ * whatever its state: a refusal seen again is pending again.
  */
 export function addPersonStep(root: string, input: NewPersonStep, now = new Date()): { step: PersonStep; updated: boolean } {
   const problems = stepProblems(input)
   if (problems.length) throw new Error(problems.join('; '))
   const steps = readPersonSteps(root)
-  const command = input.command.trim().replace(/\s+/g, ' ')
+  const command = input.command === null ? null : input.command.trim().replace(/\s+/g, ' ')
   const delivery = input.delivery?.trim() || null
-  const same = steps.find((s) => s.status === 'pending' && s.command === command && s.delivery === delivery)
+  const same = input.key ? steps.find((s) => s.key === input.key) : steps.find((s) => s.status === 'pending' && s.command === command && s.delivery === delivery)
   if (same) {
-    Object.assign(same, { why: input.why.trim(), changes: input.changes.trim(), credential: input.credential as Credential, ...(input.check ? { check: input.check } : {}) })
+    Object.assign(same, { why: input.why.trim(), changes: input.changes.trim(), credential: input.credential as Credential, status: 'pending', ...(input.check ? { check: input.check } : {}) })
+    delete same.doneAt
+    delete same.doneBy
     writeSteps(root, steps)
     return { step: same, updated: true }
   }
@@ -184,7 +222,8 @@ export function addPersonStep(root: string, input: NewPersonStep, now = new Date
     delivery,
     status: 'pending',
     createdAt: now.toISOString(),
-    source: 'agent',
+    source: input.source ?? 'agent',
+    ...(input.key ? { key: input.key } : {}),
     ...(input.check ? { check: input.check } : {}),
   }
   writeSteps(root, [...steps, step])
@@ -208,6 +247,15 @@ export function settlePersonStep(root: string, id: string, status: 'done' | 'dis
   return step
 }
 
+/** Mark the pending step recorded under `key` done, seen by the CLI itself (the pull it waited for now works). */
+export function markKeyedStepDone(root: string, key: string, now = new Date()): void {
+  const steps = readPersonSteps(root)
+  const step = steps.find((s) => s.key === key && s.status === 'pending')
+  if (!step) return
+  Object.assign(step, { status: 'done', doneAt: now.toISOString(), doneBy: 'check' })
+  writeSteps(root, steps)
+}
+
 /** Take settled steps off the list; pending ones stay. */
 export function clearSettledSteps(root: string): number {
   const steps = readPersonSteps(root)
@@ -255,21 +303,73 @@ export function checkProblem(check: StepCheck, readOnly: readonly string[]): str
   return null
 }
 
+/** Where a folder's link points (`targetOf`), and the profile that reaches it (`targetProfileName`). */
+export interface StepTarget {
+  target: string
+  profile: string
+}
+
+/** The folder's current target, or null when it links to no workspace. */
+export function currentTarget(root: string): StepTarget | null {
+  const link = readLink(root)
+  return link ? { target: targetOf(link), profile: targetProfileName(localProject(root), link) } : null
+}
+
+/**
+ * Why a change request's step must not run, or null when it may: it was
+ * recorded for another target than the folder links to now, it names a profile
+ * that is not the folder's and no target to aim it again (a hand-written
+ * step), or its profile is gone. Each says how to go on: connect the folder,
+ * or dismiss the step. The request is applied already, so applying it again
+ * is refused; adding a profile by hand would aim the step at a profile
+ * nothing keeps in step with the link.
+ */
+export function staleProblem(step: PersonStep, current: StepTarget | null): string | null {
+  if (step.target && step.target !== current?.target) {
+    return `it was recorded for ${step.target}, and this folder now links to ${current?.target ?? 'no workspace'}: link this folder back to it with \`frontera local sync connect --relink\`, or dismiss this step`
+  }
+  if (!step.profile) return null
+  if (step.profile !== current?.profile) {
+    return `it names the profile ${step.profile}, which is not this folder's for its link, and it records no target to aim it at this folder's: dismiss this step`
+  }
+  if (!getProfile(step.profile)) {
+    return `its profile ${step.profile} is not on this computer: connect this folder again with \`frontera local sync connect\`, which records it, or dismiss this step`
+  }
+  return null
+}
+
+/** The command aimed at a profile: `--profile <profile>` added unless it names one already. */
+export function atProfile(command: string, profile: string | null): string {
+  return !profile || /(?:^|\s)--profile(?:\s|=|$)/.test(command) ? command : `${command} --profile ${profile}`
+}
+
 /**
  * Record what a request left for a person, as person-steps of its delivery
- * (the request's title). An item already listed (by its key) is updated, a
- * settled one stays settled, so applying a request again doesn't bring back
- * what was done.
+ * (the request's title). An item already listed (by its key) is updated. A
+ * settled one stays settled when the request is applied again to the same
+ * target, so that doesn't bring back what was done; applied to another
+ * target, it is pending again there. `at` is the request's target: its profile
+ * (`targetProfileName`), which each command and check names, since the folder
+ * is bound to its local runtime and the steps change the workspace the request
+ * was applied to, and the target itself, recorded on each step.
  */
-export function recordAfterApply(root: string, delivery: string, items: AfterApplyItem[], now = new Date()): PersonStep[] {
+export function recordAfterApply(root: string, delivery: string, items: AfterApplyItem[], at: { profile: string; target: string } | null = null, now = new Date()): PersonStep[] {
+  const profile = at?.profile ?? null
   const steps = readPersonSteps(root)
   const out: PersonStep[] = []
-  for (const item of items) {
+  for (const raw of items) {
+    const item = { ...raw, ...(raw.command ? { command: atProfile(raw.command, profile) } : {}), ...(raw.check ? { check: { ...raw.check, command: atProfile(raw.check.command, profile) } } : {}) }
     const credential = ((CREDENTIALS as readonly string[]).includes(item.credential) ? item.credential : 'person') as Credential
     const command = item.command && !commandProblem(item.command) ? item.command : null
     const existing = steps.find((s) => s.key === item.key && s.delivery === delivery)
     if (existing) {
-      Object.assign(existing, { command, why: item.why, changes: item.label, credential, ...(item.check ? { check: item.check } : {}) })
+      if (at && existing.target && existing.target !== at.target) {
+        existing.status = 'pending'
+        delete existing.doneAt
+        delete existing.doneBy
+        delete existing.lastCheckedAt
+      }
+      Object.assign(existing, { command, why: item.why, changes: item.label, credential, ...(item.check ? { check: item.check } : {}), ...(at ? { target: at.target, profile: at.profile } : {}) })
       out.push(existing)
       continue
     }
@@ -285,6 +385,7 @@ export function recordAfterApply(root: string, delivery: string, items: AfterApp
       source: 'change-request',
       key: item.key,
       ...(item.check ? { check: item.check } : {}),
+      ...(at ? { target: at.target, profile: at.profile } : {}),
     }
     steps.push(step)
     out.push(step)
@@ -314,12 +415,13 @@ export async function runStepChecks(
   now = new Date(),
 ): Promise<{ checked: number; done: PersonStep[]; problems: Array<{ id: string; problem: string }> }> {
   const steps = readPersonSteps(root)
+  const current = currentTarget(root)
   const done: PersonStep[] = []
   const problems: Array<{ id: string; problem: string }> = []
   let checked = 0
   for (const step of steps) {
     if (step.status !== 'pending' || !step.check) continue
-    const problem = checkProblem(step.check, readOnly)
+    const problem = staleProblem(step, current) ?? checkProblem(step.check, readOnly)
     if (problem) {
       problems.push({ id: step.id, problem })
       continue

package/src/local/local-project.ts

@@ -48,7 +48,11 @@ export function slugify(name: string): string {
 }
 
 export function localProject(cwd: string): LocalProject {
-  const root = findSolutionRoot(cwd)
+  return localProjectAt(findSolutionRoot(cwd))
+}
+
+/** The local project rooted at `root` itself, with no walk up. */
+export function localProjectAt(root: string): LocalProject {
   const hash = createHash('sha256').update(root).digest('hex').slice(0, 8)
   return {
     root,

package/src/local/local-supervisor.ts

@@ -9,7 +9,9 @@ import {
   execInContainer,
   followLogs,
   imagePresent,
+  PullError,
   pullImage,
+  registryHost,
   removeContainer,
   runContainer,
   startContainer,
@@ -33,6 +35,7 @@ import {
   type LocalSecrets,
 } from './local-env'
 import { runtimeKeyCustodianProblem } from './local-key-custodian'
+import { addPersonStep, markKeyedStepDone } from './local-person-steps'
 import { localEmbeddingsReachable, providerEnv } from './local-keys'
 import { applyProviderSetup, readProviderSetup, rememberSlugs, writeProviderSetup } from './local-providers'
 import type { PortBlock } from './local-ports'
@@ -325,9 +328,44 @@ export async function runSupervisor(project: LocalProject, ports: PortBlock, ses
 
 type SetFn = (name: ComponentName, patch: Partial<ComponentState>) => void
 
-async function ensureImage(image: string, project: LocalProject, component: ComponentName): Promise<void> {
-  if (imagePresent(image)) return
-  await pullImage(image, logPath(project, component))
+/**
+ * Every image the runtime runs comes through here. A pull refused for want of
+ * access is the person's step, recorded without the agent choosing to:
+ * one per image repository, so a retry finds the same step, and done once an
+ * image from that repository is on the machine.
+ */
+export async function ensureImage(image: string, project: LocalProject, component: ComponentName): Promise<void> {
+  const repository = image.replace(/:[^/:]*$/, '')
+  const key = `image-access:${repository}`
+  if (!imagePresent(image)) {
+    try {
+      await pullImage(image, logPath(project, component))
+    } catch (err) {
+      if (!(err instanceof PullError) || err.failure !== 'no-access') throw err
+      const host = registryHost(image)
+      const ghcr = host === 'ghcr.io'
+      try {
+        addPersonStep(project.root, {
+          key,
+          source: 'runtime',
+          command: null,
+          credential: 'registry-owner',
+          changes: ghcr ? `Read access for your GitHub account to the organization's package ${repository}` : `Pull access for your account on ${host} to ${repository}`,
+          why: [
+            `Docker is signed in to ${host}, and the registry still refused ${image}, so the local runtime can't start from it.`,
+            ghcr ? "Ask an organization owner to grant the GitHub account Docker signed in with read access to the organization's packages." : `Ask an owner of ${host} to grant the account Docker signed in with pull access.`,
+            `If the account already has access, its sign-in no longer works: sign Docker in to ${host} again.`,
+            'The next `frontera local start --image` that pulls the image marks this step done. Without access, run from a platform checkout without --image.',
+          ].join(' '),
+        })
+      } catch {
+        // Not recorded (200 steps already pending): the refusal still says what to do.
+        throw err
+      }
+      throw new PullError('no-access', `${err.message}. This is the person's step; \`frontera local steps\` lists it`)
+    }
+  }
+  markKeyedStepDone(project.root, key)
 }
 
 /**

package/src/local/local-sync-link.ts

@@ -1,11 +1,15 @@
 import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
 import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { parseDocument } from 'yaml'
 
+import { credentialStore } from '../credential-store'
+import { forgetDeviceSession } from '../device-login'
 import { writeFileAtomic } from '../fs-atomic'
 import { configDir } from '../paths'
+import { deleteProfile, fingerprint, getProfile, putProfile } from '../profiles'
 import { PROJECT_FILES, type LocalProject } from './local-project'
 
 /**
@@ -161,3 +165,75 @@ export function removeSyncKey(project: LocalProject, role: KeyRole): void {
   delete keys[account(project, role)]
   writeFileAtomic(keysFile(), `${JSON.stringify(keys, null, 2)}\n`, 0o600)
 }
+
+// ── The link's target as a CLI profile ──────────────────────────────────────
+
+/**
+ * The CLI profile that reaches the linked workspace's platform with the
+ * project's own keys, one per folder and target: its name comes from the
+ * project (its folder), the platform and the workspace. The organization is
+ * left out, since a workspace already fixes it, so adding the organization
+ * key keeps the name. The project folder is bound to its local runtime, so a step
+ * that must change the workspace (a change request's after-apply steps, the
+ * read that checks them) names this profile with `--profile`; the remote guard
+ * lets a command that names its target through.
+ */
+export function targetProfileName(project: LocalProject, link: SyncLink): string {
+  const target = [project.id, link.platform, link.workspace].join('\n')
+  return `sync-${createHash('sha256').update(target).digest('hex').slice(0, 16)}`
+}
+
+/** Where a recorded step acts, `<host>/<workspace>`: a step whose target is not the folder's link is stale. */
+export const targetOf = (link: SyncLink) => `${new URL(link.platform).host}/${link.workspace}`
+
+/** The fingerprints of the keys stored for the project now. */
+export function projectKeyFingerprints(project: LocalProject): string[] {
+  return (['organization', 'workspace'] as const).flatMap((role) => {
+    const key = getSyncKey(project, role)
+    return key ? [fingerprint(key)] : []
+  })
+}
+
+/**
+ * Record the target profile from the keys stored for the project: the
+ * organization key when there is one (every step a change request leaves is
+ * at organization grain), else the workspace key. Null when no key is stored.
+ * The profile is the project's when it holds one of the project's keys, now
+ * or before `connect` replaced them (`previous`), and then takes the current
+ * key; one holding another key is left alone. The key is stored as every
+ * profile's is, so a machine without a secure store refuses it unless its
+ * person chose the 0600 file.
+ */
+export async function registerTargetProfile(project: LocalProject, link: SyncLink, previous: readonly string[] = []): Promise<string | null> {
+  const organizationKey = getSyncKey(project, 'organization')
+  const key = organizationKey ?? getSyncKey(project, 'workspace')
+  if (!key) return null
+  const name = targetProfileName(project, link)
+  const existing = getProfile(name)
+  if (existing && ![...previous, ...projectKeyFingerprints(project)].includes(existing.fingerprint)) {
+    throw new Error(`the profile ${name} holds a key that isn't this project's, so it is left as it is; \`frontera auth remove ${name}\` frees the name`)
+  }
+  await credentialStore().set(name, key)
+  const now = new Date().toISOString()
+  putProfile(name, {
+    apiUrl: link.platform,
+    credentialKind: organizationKey ? 'organization' : 'workspace',
+    workspaceId: organizationKey ? null : link.workspace,
+    orgId: link.organization ?? null,
+    fingerprint: fingerprint(key),
+    createdAt: existing?.createdAt ?? now,
+    lastVerifiedAt: now,
+  })
+  return name
+}
+
+/** Remove this folder's target profile with its key and its browser sign-in, unless the profile holds a key that isn't the project's. */
+export async function removeTargetProfile(project: LocalProject, link: SyncLink): Promise<void> {
+  const name = targetProfileName(project, link)
+  const existing = getProfile(name)
+  if (existing && !projectKeyFingerprints(project).includes(existing.fingerprint)) return
+  if (existing) deleteProfile(name)
+  const store = credentialStore()
+  await store.delete(name)
+  await forgetDeviceSession(store, name, (url, init) => fetch(url, { ...init, signal: AbortSignal.timeout(5_000) }))
+}

package/src/local/local-sync-precheck.ts

@@ -64,7 +64,7 @@ export function fixFor(check: Check): string | null {
   const ref = check.ref
   if (check.code === 'stale_base' || check.code === 'exists' || check.code === 'gone') return `pull it first (\`frontera local sync pull ${ref}\`), then propose`
   if (check.code === 'unpublished_draft') return 'publish or discard its draft on the platform, then fetch and propose'
-  if (check.code === 'blueprint_backing') return 'leave it out: a dataset binding is set on the platform'
+  if (check.code === 'blueprint_backing') return 'make the type’s backing name a dataset the organization has, or add its datasets/<name>.json to this request, and map each field to one of its columns'
   if (check.code === 'blueprint_draft') return 'publish or discard the Blueprint’s draft on the platform, then propose'
   const model = /the model (\S+) is not in this workspace/.exec(check.message)
   if (model) return `choose the workspace model it goes as (\`frontera local sync map-model ${model[1]} <workspace model>\`)`

package/src/local/local-sync-push.ts

@@ -1055,6 +1055,13 @@ export function parseOutcome(raw: unknown): ApplyOutcome {
 const STEP_MARK: Record<StepStatus, string> = { done: '✓', failed: '✗', 'not-run': '·' }
 const BACK_WORD = { 'put-back': 'put back', failed: 'could not be put back', irreversible: 'cannot be withdrawn' } as const
 
+/** What failed: an item's title when the step is one item's, otherwise the step's own words ("Grant the workspace its new object types"). */
+export function failedName(outcome: ApplyOutcome, titles: Record<string, string> = {}): string {
+  const failed = outcome.failure
+  if (!failed) return 'a step'
+  return titles[failed.ref] ?? outcome.steps.find((s) => s.key === failed.key)?.label ?? failed.ref
+}
+
 /** Apply's steps, and after a failure what was put back, as `request apply` prints them. */
 export function describeOutcome(outcome: ApplyOutcome, titles: Record<string, string> = {}): string[] {
   const lines = outcome.steps.flatMap((s) => [
@@ -1063,9 +1070,8 @@ export function describeOutcome(outcome: ApplyOutcome, titles: Record<string, st
   ])
   if (outcome.ok) return [`Applied ${outcome.steps.length} step${outcome.steps.length === 1 ? '' : 's'}:`, ...lines]
   const failed = outcome.failure
-  const name = failed ? titles[failed.ref] ?? failed.ref : 'a step'
   return [
-    `Not applied: ${failed ? `${name} failed: ${failed.message}` : 'a step failed'}`,
+    `Not applied: ${failed ? `${failedName(outcome, titles)} failed: ${failed.message}` : 'a step failed'}`,
     ...lines,
     ...(outcome.compensation.length
       ? ['', 'What was put back:', ...outcome.compensation.map((c) => `  ${c.label}: ${BACK_WORD[c.status]}${c.error ? ` (${c.error})` : ''}`)]

package/src/local/local-sync-remote.ts

@@ -578,6 +578,22 @@ export async function agentOperatingConfig(
   return { config, notes }
 }
 
+/**
+ * The Knowledge app's bases an Agent searches are platform settings, not part
+ * of its files: a local runtime has no Knowledge app, and a base belongs to
+ * one installation. Said, so what the Agent answers locally is not taken for
+ * what it answers on the platform. Nothing to say where the platform has no
+ * Knowledge app, the Agent searches none, or the route is not there.
+ */
+export async function knowledgeBasesNote(source: SyncSource, agentId: string): Promise<string | null> {
+  const answer = await source.workspace.get(`/v1/config/agents/${encodeURIComponent(agentId)}/knowledge-bases`).catch(() => null)
+  const bases = answer ? one<{ bases?: Array<{ name?: unknown; searched?: unknown }> } | null>(answer)?.bases ?? [] : []
+  const names = bases.filter((base) => base.searched === true && typeof base.name === 'string').map((base) => `“${base.name as string}”`)
+  if (!names.length) return null
+  const which = names.length === 1 ? `the knowledge base ${names[0]}` : `${names.length} knowledge bases (${names.join(', ')})`
+  return `Searches ${which} from the Knowledge app on the platform. A local runtime has no Knowledge app, so here it answers without them: test this Agent’s Knowledge on the platform`
+}
+
 /** An Agent's record (`/v1/config/agents/:id`): its published version, and its behavior settings, scrubbed. */
 interface AgentDetail { currentVersion?: { versionNumber?: number } | null; operatingConfig?: unknown }
 
@@ -632,6 +648,8 @@ async function readAgents(source: SyncSource, lists: Lists, directory: Directory
       it.notes.push(`Its Context and data couldn’t be read on the platform: ${context.unread}. Until it can be read, local dev gives it read access to the object types the project holds, as an adaptation, so locally it may read more than on the platform`)
     }
     if (bound.functions.length || bound.workflows.length || bound.blueprint?.length || bound.blueprintUnread) docs.push({ path: `agents/${row.agentId}/bindings.json`, doc: bound, format: 'json' })
+    const knowledgeBases = await knowledgeBasesNote(source, row.id)
+    if (knowledgeBases) it.notes.push(knowledgeBases)
     await nameUnknownAgents(source, directory, docs)
     out.push(finish(it, directory, docs))
   }