@frontera-sdk/cli 1.53.5 → 1.53.7

package/src/main.ts

@@ -9,6 +9,7 @@ import { EXIT, sessionLaneFailure, sessionLaneRefusal, type ExitCode } from './e
 import { actAsLocalPersona, listPersonas, localPersonaHint, redact } from './local/local-personas'
 import { localRuntimeAt } from './local/local-runtime-target'
 import { acquireLock, lockRefusal, locksRuntime, projectStateDir, recordWrite, writeCommand } from './local/local-writers'
+import { tokenFromStdin } from './mcp/mcp-apps'
 import { resolveOrganization, setSelectedOrganization } from './organization'
 import { canPrompt, promptConfirm } from './prompt'
 import { remoteFromLocalProject, remoteWords } from './remote-guard'
@@ -228,6 +229,10 @@ async function main(): Promise<number> {
     // project are always read from one place. Two directories would mean
     // `--dir ../other-customer` could edit one customer's app with another
     // customer's key.
+    //
+    // The `frontera app dev` that `--detach` starts takes its caller's key on stdin, used as FRONTERA_TOKEN
+    // would be, so it is never in the environment the App's own server inherits.
+    const piped = await tokenFromStdin()
     let credential = command.meta.offline
       ? { apiUrl: typeof flags['api-url'] === 'string' ? flags['api-url'] : (process.env.FRONTERA_API_URL ?? ''), token: '' }
       : await resolveCredential(
@@ -237,7 +242,7 @@ async function main(): Promise<number> {
             // In a local project, an organization command takes the runtime's organization key.
             organization: commandScope(command.meta) === 'organization' && command.meta.noun !== 'auth' && command.meta.noun !== 'kit',
           },
-          { cwd },
+          { cwd, ...(piped ? { env: { ...process.env, FRONTERA_TOKEN: piped } } : {}) },
         )
     // A command that acts as a person takes the browser sign-in (`auth login --browser`) over the
     // profile's key, which it would refuse; nothing else does. A raw FRONTERA_TOKEN still wins.
@@ -377,6 +382,7 @@ async function main(): Promise<number> {
         cwd,
         apiUrl: credential.apiUrl,
         token: credential.token,
+        ...('profile' in credential && credential.profile ? { profile: credential.profile } : {}),
         positional,
         flags,
         repeated,

package/src/mcp/mcp-apps.ts

@@ -3,9 +3,9 @@ import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync,
 import { basename, dirname, join, relative } from 'node:path'
 
 import { isLoopbackPortFree } from '../dev-broker'
-import { findSolutionRoot, localProject, type LocalProject } from '../local/local-project'
+import { findSolutionRoot, localProject, localProjectAt, type LocalProject } from '../local/local-project'
 import { isAlive } from '../local/local-state'
-import { readProject } from '../project'
+import { appTarget, readProject } from '../project'
 import { ensureAppPackages } from '../project-bootstrap'
 import { detectAppFramework } from '../provenance'
 import { selfCommand } from './mcp-cli'
@@ -90,13 +90,28 @@ export interface DevServer {
   url: string
   startedAt: string
   log: string
+  /** What its sessions are minted against (`appTarget`: the API origin and workspace). Absent: an older record. */
+  target?: string
   /**
    * The process that started it: an MCP session (`app_dev`, `app_render`) or
    * Forge (its Start). The server stops when that process ends (`frontera app
    * dev` watches it), so a server an agent or Forge started never outlives it.
-   * Absent: started by hand.
+   * `detached`: `frontera app dev --detach`, which nothing owns, so it runs
+   * until it is stopped. Absent: started by hand.
    */
-  owner?: { kind: 'mcp' | 'forge'; pid: number }
+  owner?: { kind: 'mcp' | 'forge'; pid: number } | { kind: 'detached' }
+}
+
+/** What a dev server runs against: the credential `frontera app dev` gets, and the target it reaches (`appTarget`), null when unknown. */
+export interface DevCredential {
+  env: Record<string, string>
+  target: string | null
+  /**
+   * A key given on `frontera app dev`'s stdin instead of in `env`, so the
+   * App's own server, which inherits that environment, never holds it
+   * (`--detach` with the caller's profile key or browser sign-in).
+   */
+  token?: string
 }
 
 /** How a dev server this process started ended: its exit code (or signal) and the last lines it wrote. */
@@ -115,8 +130,14 @@ export interface EnsureDevServerOptions {
    * module (Forge) passes its own, or it would start a copy of itself.
    */
   command?: string[]
-  /** Who owns the server's lifetime (this process either way). Default: an MCP session. */
-  owner?: 'mcp' | 'forge'
+  /**
+   * Who owns the server's lifetime: an MCP session (the default) or Forge,
+   * this process either way; `detached` for `frontera app dev --detach`,
+   * whose server outlives it.
+   */
+  owner?: 'mcp' | 'forge' | 'detached'
+  /** The port to listen on. Default: a free one from 3100. */
+  port?: number
   /** Called once when the server this call started ends, however it ends. */
   onExit?: (exit: DevServerExit) => void
 }
@@ -124,6 +145,17 @@ export interface EnsureDevServerOptions {
 /** What tells `frontera app dev` which process started it, so it stops when that one ends. */
 export const DEV_OWNER_ENV = 'FRONTERA_APP_DEV_OWNER_PID'
 
+/** What tells `frontera app dev` that its credential comes on stdin (`DevCredential.token`). */
+const TOKEN_ON_STDIN_ENV = 'FRONTERA_TOKEN_ON_STDIN'
+
+/** The key `ensureDevServer` wrote to this process's stdin, read once; null when it was started any other way. */
+export async function tokenFromStdin(): Promise<string | null> {
+  if (process.env[TOKEN_ON_STDIN_ENV] !== '1') return null
+  // Gone before anything is spawned: a `frontera` the App's dev script runs must not wait for a key on stdin.
+  delete process.env[TOKEN_ON_STDIN_ENV]
+  return (await Bun.stdin.text()).trim() || null
+}
+
 /** The dev servers this process started, by project and App, so they stop with the MCP session or Forge (`stopStartedDevServers`). */
 const startedHere = new Map<string, { project: LocalProject; slug: string; pid: number }>()
 
@@ -160,6 +192,15 @@ export function enclosingSolution(appRoot: string): LocalProject | null {
   return localProject(root)
 }
 
+/**
+ * Where an App folder's dev server is recorded: in its solution, where the
+ * solution's agents, Forge and `local stop` look, or in the App folder itself
+ * when it stands alone.
+ */
+export function devServerHome(appRoot: string): LocalProject {
+  return enclosingSolution(appRoot) ?? localProjectAt(appRoot)
+}
+
 /**
  * Record a dev server another command started (`frontera app dev` run by hand
  * or by another session), so `app_dev`, `app_render` and Forge reuse it rather
@@ -202,16 +243,34 @@ export function localAppEnv(link: RuntimeLink): Record<string, string> {
   return { FRONTERA_TOKEN: key, FRONTERA_API_URL: link.serviceUrl, FRONTERA_ORG_ID: link.creds.organizationId }
 }
 
+/** The local runtime as what a dev server runs against. */
+export function localDevCredential(link: RuntimeLink): DevCredential {
+  return { env: localAppEnv(link), target: appTarget(link.serviceUrl, link.creds.workspaceId) }
+}
+
+/** "http://127.0.0.1:4000, workspace ws_1": a target (`appTarget`) in a sentence. */
+function targetWords(target: string): string {
+  const [origin, workspace] = target.split('#')
+  return `${origin}, workspace ${workspace}`
+}
+
 const READY_MS = 60_000
 
 /**
- * The App's dev server against the local runtime: the one already running,
- * or a new `frontera app dev` started in the background, its output in
- * `.frontera/local/logs/app-<slug>.log`.
+ * The App's dev server against `credential` (the local runtime, or the
+ * workspace `frontera app dev --detach` runs against): the one already
+ * running, or a new `frontera app dev` started in its own session, its
+ * output in `.frontera/local/logs/app-<slug>.log`.
  */
-export async function ensureDevServer(project: LocalProject, app: AppProjectRef, link: RuntimeLink, options: EnsureDevServerOptions = {}): Promise<{ server: DevServer; reused: boolean; installed?: string; trackedFiles?: string[] }> {
+export async function ensureDevServer(project: LocalProject, app: AppProjectRef, credential: DevCredential, options: EnsureDevServerOptions = {}): Promise<{ server: DevServer; reused: boolean; installed?: string; trackedFiles?: string[] }> {
   const running = readDevServer(project, app.slug)
-  if (running && (await answers(running.url))) return { server: running, reused: true }
+  if (running && (await answers(running.url))) {
+    // One server per App folder (Next.js refuses a second), so one against another target is refused, never passed off as this one.
+    if (running.target && credential.target && running.target !== credential.target) {
+      throw new Error(`${app.slug}'s dev server on port ${running.port} runs against ${targetWords(running.target)}, not ${targetWords(credential.target)}. Stop it with \`frontera app dev --stop\` in ${app.root}, then try again.`)
+    }
+    return { server: running, reused: true }
+  }
   if (app.framework === 'unknown') throw new Error(`${app.slug} has neither Next.js nor Vite in package.json, so it has no dev server to start.`)
   // A pulled App comes without node_modules: its packages are installed first (bun install), or `next` isn't there to start.
   // From its bun.lock as it is when it has one: a pulled App's lockfile is never rewritten here. One whose
@@ -223,7 +282,7 @@ export async function ensureDevServer(project: LocalProject, app: AppProjectRef,
   // From its own SDK copy (package.json and bun.lock disagree because of it): said with what kept both files as pulled.
   const where = relative(project.root, app.root) || app.slug
   const installed = install ? (install.fromCopy || install.fromLock ? `${where} had no node_modules: ${install.summary}` : `${where} had no node_modules: ran bun install first${frozen ? ' from its bun.lock as it is (--frozen-lockfile; the lockfile is unchanged)' : ''} (${install.summary})`) : undefined
-  const port = await freePort()
+  const port = options.port || (await freePort())
   mkdirSync(join(project.stateDir, 'logs'), { recursive: true })
   mkdirSync(devDir(project), { recursive: true })
   const log = join(project.stateDir, 'logs', `app-${app.slug}.log`)
@@ -231,13 +290,19 @@ export async function ensureDevServer(project: LocalProject, app: AppProjectRef,
   // Where this run's output starts in the log, which keeps earlier runs: its tail is this run's alone.
   const from = statSync(log).size
   const [exe, ...pre] = options.command ?? selfCommand()
+  const owned = options.owner !== 'detached'
+  const env: NodeJS.ProcessEnv = { ...process.env, ...credential.env, NO_COLOR: '1', ...(credential.token ? { [TOKEN_ON_STDIN_ENV]: '1' } : {}) }
+  delete env[DEV_OWNER_ENV]
   const child = spawn(exe!, [...pre, 'app', 'dev', '--no-open', '--port', String(port)], {
     cwd: app.root,
+    // Its own session: a signal to the caller's process group (a shell's job, an agent's background command) never reaches it.
     detached: true,
-    stdio: ['ignore', fd, fd],
-    // The server stops when this process ends, however it ends (`frontera app dev` watches it).
-    env: { ...process.env, ...localAppEnv(link), NO_COLOR: '1', [DEV_OWNER_ENV]: String(process.pid) },
+    stdio: [credential.token ? 'pipe' : 'ignore', fd, fd],
+    // An owned server stops when this process ends, however it ends (`frontera app dev` watches it); a detached one runs until stopped.
+    env: owned ? { ...env, [DEV_OWNER_ENV]: String(process.pid) } : env,
   })
+  // A child that dies before reading it closes the pipe: what it said goes to the log, not an unhandled EPIPE here.
+  if (credential.token) child.stdin!.on('error', () => {}).end(credential.token)
   closeSync(fd)
   let exited: DevServerExit | null = null
   child.on('exit', (code, signal) => {
@@ -249,8 +314,17 @@ export async function ensureDevServer(project: LocalProject, app: AppProjectRef,
   })
   child.unref()
   const origin = `http://127.0.0.1:${port}`
-  const server: DevServer = { slug: app.slug, pid: child.pid!, port, url: app.framework === 'vite' ? `${origin}/dev-host.html` : origin, startedAt: new Date().toISOString(), log: relative(project.root, log), owner: { kind: options.owner ?? 'mcp', pid: process.pid } }
-  startedHere.set(`${project.root}\0${app.slug}`, { project, slug: app.slug, pid: server.pid })
+  const server: DevServer = {
+    slug: app.slug,
+    pid: child.pid!,
+    port,
+    url: app.framework === 'vite' ? `${origin}/dev-host.html` : origin,
+    startedAt: new Date().toISOString(),
+    log: relative(project.root, log),
+    ...(credential.target ? { target: credential.target } : {}),
+    owner: owned ? { kind: options.owner ?? 'mcp', pid: process.pid } : { kind: 'detached' },
+  }
+  if (owned) startedHere.set(`${project.root}\0${app.slug}`, { project, slug: app.slug, pid: server.pid })
   writeFileSync(devFile(project, app.slug), `${JSON.stringify(server, null, 2)}\n`)
   const deadline = Date.now() + READY_MS
   while (Date.now() < deadline) {
@@ -428,8 +502,10 @@ export function watchOwner(owner: number, onGone: () => void, everyMs = 5_000):
 export function devServerLine(s: DevServer): string {
   const by = !s.owner
     ? 'started by hand (`frontera app dev`)'
-    : s.owner.kind === 'forge'
-      ? `started from Forge (pid ${s.owner.pid}); it stops when Forge stops it or quits`
-      : `started by an MCP session (pid ${s.owner.pid}); it stops when that session ends`
+    : s.owner.kind === 'detached'
+      ? 'started with `frontera app dev --detach`; it runs until `frontera app dev --stop` or `frontera local stop` stops it'
+      : s.owner.kind === 'forge'
+        ? `started from Forge (pid ${s.owner.pid}); it stops when Forge stops it or quits`
+        : `started by an MCP session (pid ${s.owner.pid}); it stops when that session ends`
   return `${s.slug} on port ${s.port} (${s.url}), ${by}`
 }

package/src/mcp/tools/agent-tools.ts

@@ -2,12 +2,13 @@ import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { itemBuild } from '../../local/local-build-summary'
-import { restoreBaseline, saveBaseline } from '../../local/local-db-snapshot'
+import { readBaseline, restoreBaseline, saveBaseline, type BaselineRecord, type BaselineSaver, type SnapshotDeps } from '../../local/local-db-snapshot'
 import type { LocalProject } from '../../local/local-project'
 import { providerRefusal } from '../../local/local-provider-refusal'
 import { waitForDatabaseReady } from '../../local/local-runtime-health'
 import { plainVariables, redactedVariablesOfTimeline, variablesOfTimeline } from '../../local/local-test-cases'
 import { chatTarget, type ToolCall } from '../../local/local-test-runner'
+import { lockRefusal, readLock } from '../../local/local-writers'
 import { dropTurn, readTurn, reattachTurn, startTurn, TURN_IDLE_MS, type HeldTurn, type PendingDecision, type TurnRead } from '../mcp-chat'
 import { conversationTranscript, searchConversations } from '../mcp-conversations'
 import { errorResult, intArg, jsonResult, stringArg, type McpTool, type ToolResult } from '../mcp-protocol'
@@ -339,7 +340,22 @@ export function simulatedWritesLine(count: number): string {
   return `${count} write${count === 1 ? '' : 's'} simulated, not applied: nothing changed, whatever the reply says (realActions: true in a new conversation runs them for real)`
 }
 
-export function agentTools(project: LocalProject, memory: McpMemory): McpTool[] {
+const SAVED_BY: Record<BaselineSaver, string> = {
+  check: 'a `frontera local check`, which saves them again before its tests',
+  snapshot: '`frontera local snapshot save`',
+  data: '`frontera local data load`',
+  conversation: 'another conversation started with rollback: true',
+}
+
+/** Why agent_rollback put nothing back: the records saved for the conversation are no longer the ones a restore puts back. */
+function replacedWords(savedAt: string, stored: BaselineRecord): string {
+  return `The records saved when this conversation started (${savedAt}) were replaced at ${stored.savedAt} by ${stored.savedBy ? SAVED_BY[stored.savedBy] : 'a later save (a `frontera local check`, `frontera local snapshot save`, or another conversation started with rollback: true)'}. `
+    + 'Nothing was put back: putting back that later save would keep what this conversation wrote. '
+    + 'What its real actions wrote is still there: look at it with blueprint_query and change it back, or start the conversation again with rollback: true and call agent_rollback before the next check.'
+}
+
+/** `snapshot`: how the records are saved and put back for a conversation with rollback, a stand-in's in tests. */
+export function agentTools(project: LocalProject, memory: McpMemory, snapshot: SnapshotDeps = {}): McpTool[] {
   /**
    * The turn as the agent reads it: the reply so far, what the Agent waits
    * on (kept, with its stream, for the answer), or why the turn stopped
@@ -553,7 +569,7 @@ export function agentTools(project: LocalProject, memory: McpMemory): McpTool[]
           },
           rollback: {
             type: 'boolean',
-            description: "With realActions, when starting: save the local runtime's records first, so agent_rollback puts back what this conversation's actions changed once you have read them (default false). It replaces the runtime's saved baseline, as `frontera local snapshot save` does.",
+            description: "With realActions, when starting: save the local runtime's records first, so agent_rollback puts back what this conversation's actions changed once you have read them (default false). It replaces the runtime's saved baseline, as `frontera local snapshot save` does, so it is refused while a `frontera local check`, reset or restart holds the runtime.",
           },
         },
         required: ['agent', 'message'],
@@ -577,9 +593,13 @@ export function agentTools(project: LocalProject, memory: McpMemory): McpTool[]
         if (rollback && (conversationId || !realActions)) return errorResult('rollback is chosen when a conversation starts with realActions: true; it saves the records first, and agent_rollback puts them back.')
         let savedAt: string | null = null
         if (rollback) {
-          const saved = await saveBaseline(project, link.creds.organizationId, { serviceAnswers: () => waitForDatabaseReady(link.serviceUrl) }, true)
+          // The lock a running check, reset or restart holds (`local-writers.ts`), which `main.ts` takes for the CLI only.
+          const held = lockRefusal(project.stateDir, 'local snapshot save') ? readLock(project.stateDir) : null
+          if (held) return errorResult(`The conversation was not started: \`frontera ${held.command}\` holds the local runtime since ${held.since.slice(11, 19)}, and rollback would save the records first, replacing the baseline under that run (a check rolls back to its own). Start it again once that run has finished; \`frontera local status\` says whether it still holds the runtime.`)
+          const saved = await saveBaseline(project, link.creds.organizationId, { serviceAnswers: () => waitForDatabaseReady(link.serviceUrl), ...snapshot }, 'conversation')
           if (!saved.ok) return errorResult(`The records could not be saved first, so the conversation was not started: ${saved.note}`)
-          savedAt = new Date().toISOString()
+          // The saved records' own time: agent_rollback tells them from a later save by it.
+          savedAt = readBaseline(project, link.creds.organizationId)?.savedAt ?? new Date().toISOString()
         }
 
         let target: { agentId: string; agentName: string }
@@ -655,7 +675,7 @@ export function agentTools(project: LocalProject, memory: McpMemory): McpTool[]
     {
       name: 'agent_rollback',
       description:
-        "Put the local runtime's records back as they were when a conversation started with rollback: true (Forge improvement plan L2): what its real actions wrote, and anything else written since, is undone. The conversation itself, its traces and run history stay to read. Do it once you have checked what the actions did (blueprint_query).",
+        "Put the local runtime's records back as they were when a conversation started with rollback: true (Forge improvement plan L2): what its real actions wrote, and anything else written since, is undone. The conversation itself, its traces and run history stay to read. Do it once you have checked what the actions did (blueprint_query), and before the next `frontera local check`: a check saves the records again, and then this refuses rather than keep the conversation's writes.",
       inputSchema: {
         type: 'object',
         properties: { conversationId: { type: 'string', description: 'The conversation agent_chat started with rollback: true.' } },
@@ -669,7 +689,9 @@ export function agentTools(project: LocalProject, memory: McpMemory): McpTool[]
         const known = memory.conversations.get(conversationId)
         if (!known?.rollback) return errorResult('That conversation was not started with rollback: true in this session, so there is nothing saved for it. `frontera local snapshot restore` puts back the runtime\'s saved baseline, whenever it was taken.')
         if (known.rollback.rolledBack) return errorResult(`Already put back, at ${known.rollback.rolledBack}.`)
-        const restored = await restoreBaseline(project, link.creds.organizationId, { serviceAnswers: () => waitForDatabaseReady(link.serviceUrl) }, { secrets: 'keep', history: 'keep' })
+        const stored = readBaseline(project, link.creds.organizationId)
+        if (stored && stored.savedAt !== known.rollback.savedAt) return errorResult(replacedWords(known.rollback.savedAt, stored))
+        const restored = await restoreBaseline(project, link.creds.organizationId, { serviceAnswers: () => waitForDatabaseReady(link.serviceUrl), ...snapshot }, { secrets: 'keep', history: 'keep' })
         if (!restored.ok) return errorResult(`The records could not be put back: ${restored.note}`)
         known.rollback.rolledBack = new Date().toISOString()
         return jsonResult({ conversationId, putBack: `the records as they were at ${known.rollback.savedAt}`, note: restored.note, kept: 'the conversation, its traces and run history' })

package/src/mcp/tools/app-tools.ts

@@ -7,7 +7,7 @@ import type { LocalProject } from '../../local/local-project'
 import { forgeSession, observeInForge, readForgeLink } from '../forge-link'
 import { AXE_RUN, axeSource, summarizeA11y } from '../a11y-scan'
 import { observeHeadless } from '../headless'
-import { ensureDevServer, findAppProjects, listDevServers, localAppEnv, resolveAppProject, stopDevServerAndSay } from '../mcp-apps'
+import { ensureDevServer, findAppProjects, listDevServers, localAppEnv, localDevCredential, resolveAppProject, stopDevServerAndSay } from '../mcp-apps'
 import { runSelf } from '../mcp-cli'
 import { errorResult, intArg, stringArg, type McpTool, type ToolResult } from '../mcp-protocol'
 import { redactSecret, requireRuntime, runtimeLink, signedStudioUrl } from '../mcp-runtime'
@@ -82,7 +82,7 @@ export function appTools(project: LocalProject): McpTool[] {
           return { content: [{ type: 'text', text: stopped ? [`Stopped ${app.slug}'s dev server.`, ...trackedFiles.map((l) => `${app.path}: ${l}.`)].join('\n') : `${app.slug} had no dev server running.` }] }
         }
         const link = requireRuntime(project)
-        const { server, reused, installed, trackedFiles } = await ensureDevServer(project, app, link)
+        const { server, reused, installed, trackedFiles } = await ensureDevServer(project, app, localDevCredential(link))
         // An installed SDK older than (or without what is in) the one the skills describe: said with the upgrade.
         const sdkLines = sdkDriftLines(app.path, appSdkDrift(app.root))
         const sdk = sdkLines.filter((l) => !/^note:/.test(l))
@@ -130,7 +130,7 @@ export function appTools(project: LocalProject): McpTool[] {
           target = renderTargetOf(explicit, app.slug, listDevServers(project).find((s) => s.slug === app.slug)?.url ?? null)
         } else {
           if (typeof link === 'string') return errorResult(link)
-          const dev = await ensureDevServer(project, app, link)
+          const dev = await ensureDevServer(project, app, localDevCredential(link))
           installed = dev.installed
           trackedFiles = dev.trackedFiles
           url = joinPath(dev.server.url, path)

package/src/mcp/tools/project-tools.ts

@@ -11,6 +11,7 @@ import { localOrganizationId } from '../../local/local-blueprint-outline'
 import { docsStatus } from '../../local/local-docs'
 import { readConfig } from '../../local/local-env'
 import { liveAppDeployments, workspaceGet } from '../../local/local-app-runtime'
+import { appTarget } from '../../project'
 import { projectBuildRows, projectBuildSummary } from '../../local/local-build-summary'
 import { localSecretPresence } from '../../local/local-secrets'
 import { readBaseline } from '../../local/local-db-snapshot'
@@ -80,7 +81,7 @@ export function projectTools(project: LocalProject): McpTool[] {
         // The runtime's secrets now: a "Needs a value" follows them, not the last apply.
         const secrets = typeof link === 'string' ? null : await localSecretPresence(link.serviceUrl, link.creds)
         // Each Custom App's deployment as the runtime holds it: a folder's record is not proof it is still there.
-        const liveApps = typeof link === 'string' ? null : await liveAppDeployments(project.root, workspaceGet(link.serviceUrl, link.creds)).catch(() => null)
+        const liveApps = typeof link === 'string' ? null : await liveAppDeployments(project.root, workspaceGet(link.serviceUrl, link.creds), appTarget(link.serviceUrl, link.creds.workspaceId)).catch(() => null)
         // The rows the build line counts, object types and items never applied included, so the two agree.
         const rows = projectBuildRows(project.root, project.id, null, null, secrets, liveApps) ?? []
         const builds: Record<string, ItemBuild> = Object.fromEntries(rows.map(({ ref, ...b }) => [ref, b]))

package/src/project.ts

@@ -3,10 +3,16 @@ import { join, dirname } from 'node:path'
 import { execSync } from 'node:child_process'
 
 import { collectSourceFiles, isExcluded } from './packaging'
+import { isLoopback } from './remote-guard'
 
 export interface ProjectConfig {
-  /** The app's real identifier; null until the first ensure. */
-  appId: string | null
+  /**
+   * An App id from before the folder kept one per target (`appBinding`):
+   * state.json's single `appId`, else package.json `frontera.appId`. Named
+   * only where the folder has no binding; the platform ignores an id that is
+   * not one of the workspace's Apps.
+   */
+  fallbackAppId: string | null
   /** Bootstrap name for the first deploy only — the platform owns it after. */
   slug: string
   displayName: string
@@ -83,10 +89,10 @@ export function readProject(dir: string): ProjectConfig {
   if (!slug) throw new Error('package.json needs a "name"')
 
   return {
-    // The real identifier is local environment state. A source tree remains
-    // portable across Frontera organizations; first authenticated use binds a
-    // clone to the App in that environment and subsequent calls use the id.
-    appId: state.appId ?? pkg.frontera?.appId ?? null,
+    // The real identifier is local environment state, one per target. A source
+    // tree remains portable across Frontera organizations; first authenticated
+    // use binds a clone to the App in that environment.
+    fallbackAppId: state.appId ?? pkg.frontera?.appId ?? null,
     slug,
     displayName: config.displayName ?? pkg.frontera?.displayName ?? slug,
     description: config.description ?? pkg.frontera?.description,
@@ -130,12 +136,39 @@ function stringList(value: unknown, field: string): string[] {
 }
 
 /**
- * Record the environment-specific app binding locally. Source remains portable
- * across organizations and package.json remains ordinary package metadata.
+ * Where an App folder deploys: the API's origin and the workspace the
+ * credential acts in there. Not the credential itself: keys rotate, and two
+ * keys can reach one workspace.
+ */
+export function appTarget(apiUrl: string, workspaceId: string): string {
+  return `${new URL(apiUrl).origin}#${workspaceId}`
+}
+
+/**
+ * The App this folder is bound to in `target`, and whether it is bound to
+ * Apps in another workspace. A folder deploys to a workspace and to the local
+ * runtime (`app dev`, `local dev`); one id for all of them meant a deploy
+ * named another target's App, which the platform ignores, so a renamed
+ * folder created a second App. A local runtime's binding is not another
+ * workspace: building there first is the usual way to a first deploy.
  */
-export function writeAppId(dir: string, appId: string): void {
-  if (readState(dir).appId === appId) return
-  writeState(dir, { appId })
+export function appBinding(dir: string, target: string | null): { id: string | null; elsewhere: boolean } {
+  const apps = readState(dir).apps ?? {}
+  return { id: (target && apps[target]) || null, elsewhere: Object.keys(apps).some((t) => t !== target && !isLoopback(t)) }
+}
+
+/**
+ * Record the folder's App in `target`. Source remains portable across
+ * organizations and package.json remains ordinary package metadata. The
+ * single id of an older CLI moves into the binding once the platform answers
+ * with it here, which proves it is this target's.
+ */
+export function bindApp(dir: string, target: string | null, appId: string): void {
+  if (!target) return
+  const state = readState(dir)
+  const adopted = state.appId === appId
+  if (state.apps?.[target] === appId && !adopted) return
+  writeState(dir, { apps: { ...state.apps, [target]: appId }, ...(adopted ? { appId: undefined } : {}) })
 }
 
 export function readPackageVersion(dir: string): string {
@@ -147,6 +180,9 @@ export function readPackageVersion(dir: string): string {
 interface ProjectState {
   /** The last deployment made from this folder (`app deploy`): what it was deployed as. */
   parentVersion?: string | null
+  /** The folder's App in each target it deploys to, by `appTarget`. */
+  apps?: Record<string, string>
+  /** An older CLI's one id for every target: read until a deploy proves whose it is (`bindApp`). */
   appId?: string
   /**
    * The version the working tree was pulled from (`app pull`, or a local

package/src/remote-guard.ts

@@ -26,7 +26,10 @@ export function isReadOnlyCommand(meta: { noun: string; verb?: string }): boolea
   return FRONTERA_READ_ONLY_COMMANDS.includes(path) || (!!meta.verb && READ_VERBS.has(meta.verb))
 }
 
-const LOOPBACK = /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:\d+)?(\/|$)/i
+const LOOPBACK = /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:\d+)?([/#]|$)/i
+
+/** An origin on this computer, or an App target there (`appTarget`, `<origin>#<workspace>`): a local runtime's. */
+export const isLoopback = (url: string): boolean => LOOPBACK.test(url)
 
 /**
  * Where a command is going when the guard should ask, or null when it runs

package/src/templates/next-app-files.ts

@@ -1001,7 +1001,10 @@ bun run check
 
 That is \`typecheck\`, then \`bun test\`, then \`build\` — the build is the only
 thing that proves the static export still works. For anything touching data,
-also run it against real data with \`frontera app dev\`.
+also run it against real data with \`frontera app dev --detach\`: it returns once
+the App answers and keeps running after your shell ends, and
+\`frontera app dev --stop\` stops it. Plain \`frontera app dev\` runs in the
+foreground, for a person's terminal.
 `,
 
     // `@AGENTS.md`, not `./AGENTS.md`. The latter is a relative path Claude

package/src/templates/next-skills.ts

@@ -143,8 +143,12 @@ const dispatcher: Skill = {
     'against real data:',
     '',
     '```bash',
-    'frontera app dev',
+    'frontera app dev --detach',
     '```',
+    '',
+    'It returns once the App answers and the server keeps running after your shell ends;',
+    '`frontera app dev --stop` stops it. Plain `frontera app dev` runs in the foreground, for a',
+    "person's terminal.",
   ],
 }
 
@@ -369,7 +373,7 @@ const session: Skill = {
     '## Verification',
     '',
     '```bash',
-    'frontera app dev',
+    'frontera app dev --detach',
     '```',
     '',
     'The App should mount with real rows. A page that renders but 401s on every read means the',
@@ -489,7 +493,7 @@ const blueprintData: Skill = {
     '```',
     '',
     '```bash',
-    'frontera app dev',
+    'frontera app dev --detach',
     '```',
     '',
     'Compare the number under the table with the row count for the same filter in the platform. If',
@@ -627,7 +631,7 @@ const actions: Skill = {
     '```',
     '',
     '```bash',
-    'frontera app dev',
+    'frontera app dev --detach',
     '```',
     '',
     'Submit one for real and watch it to a terminal state. A flow only tested to the submit call has',
@@ -938,7 +942,7 @@ const queryStates: Skill = {
     '## Verification',
     '',
     '```bash',
-    'frontera app dev',
+    'frontera app dev --detach',
     '```',
     '',
     'Exercise all four states: a filter that matches nothing, a stopped network, a first load, and a',