@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/local/local-studio-server.ts

@@ -5,11 +5,15 @@ import { extname, join, normalize } from 'node:path'
 import type { LocalProject } from './local-project'
 import { AgentFileError, saveAgentEdit, type AgentFileEdit } from './local-agent-files'
 import { solutionStatus } from './local-applied'
+import { appCodeStates } from './local-apps'
 import { projectBlueprintOutline } from './local-blueprint-outline'
-import { itemBuild } from './local-build-summary'
-import { logPath, readApplied, readState, type ComponentName } from './local-state'
-import { appendTestCase, renderTestCase } from './local-test-cases'
+import { currentBuildRows, currentBuildSummary } from './local-build-inputs'
+import { appStatusRow, itemBuild } from './local-build-summary'
+import { KnowledgeDocumentError, KNOWLEDGE_UPLOAD_EXTENSIONS, MAX_KNOWLEDGE_UPLOAD_BYTES, checkUpload, documentInFolder, knowledgeFolderOf, projectDocuments, removeKnowledgeDocument, removeRuntimeCopies, runtimeDocuments, saveKnowledgeDocument, type ServiceCall } from './local-knowledge-uploads'
+import { isAlive, logPath, readApplied, readState, type ComponentName } from './local-state'
+import { appendTestCase, decisionOfApprovals, MIXED_DECISIONS_LINE, noteRedactedVariables, redactedVariablesLine, redactedVariablesOfTimeline, renderTestCase, variablesOfTimeline } from './local-test-cases'
 import { findCaseFiles } from './local-test-runner'
+import { workflowTestListing } from './local-workflow-tests'
 import { createTestRuns } from './local-test-runs'
 import { docsCopyPath } from './local-docs'
 import { standInMcp } from './local-stand-ins'
@@ -62,6 +66,16 @@ export function newSessionToken(): string {
   return randomBytes(24).toString('base64url')
 }
 
+/** An Agent's display name from `agents/<slug>/agent.json` (`config.name`), or null when it gives none. */
+export function agentFileName(root: string, slug: string): string | null {
+  try {
+    const name = (JSON.parse(readFileSync(join(root, 'agents', slug, 'agent.json'), 'utf8')) as { config?: { name?: unknown } }).config?.name
+    return typeof name === 'string' && name.trim() ? name.trim() : null
+  } catch {
+    return null
+  }
+}
+
 function sameToken(a: string, b: string): boolean {
   const ab = Buffer.from(a)
   const bb = Buffer.from(b)
@@ -95,7 +109,7 @@ export function startStudioServer(opts: StudioServerOptions) {
   const json = (data: unknown, status = 200) =>
     new Response(JSON.stringify(data), { status, headers: { 'content-type': 'application/json; charset=utf-8' } })
 
-  const localRoute = (url: URL): Response => {
+  const localRoute = (url: URL): Response | Promise<Response> => {
     if (url.pathname === '/__local/state') {
       const state = readState(project)
       if (!state) return json({ error: 'no local runtime state' }, 404)
@@ -125,6 +139,36 @@ export function startStudioServer(opts: StudioServerOptions) {
       if (!/^[a-z-]+\/[A-Za-z0-9][\w./-]{0,200}$/.test(ref)) return json({ error: 'name an item, as agent/<slug>' }, 400)
       return json({ build: itemBuild(project.root, ref, project.id) })
     }
+    // The build in a few numbers, counted as `local status` counts it (the runtime's Action deployments and
+    // secrets read the same way): Studio's footer says its failures, the number `local status` prints.
+    if (url.pathname === '/__local/build-summary') {
+      return currentBuildSummary(project.root, project.id, readState(project)).then((summary) =>
+        json({ summary: summary ? { problems: summary.problems, counts: summary.counts, headline: summary.headline } : null }),
+      )
+    }
+    // The build's rows of one kind (`?kind=function`), each with its state, reason and fix, as `local status` lists
+    // them: Studio's lists mark the ones that didn't apply or need setup, with the same words.
+    if (url.pathname === '/__local/builds') {
+      const kind = url.searchParams.get('kind') ?? ''
+      if (!/^[a-zA-Z-]{1,40}$/.test(kind)) return json({ error: 'name a kind, as function' }, 400)
+      return currentBuildRows(project.root, project.id, readState(project)).then((rows) =>
+        json({
+          rows: (rows ?? [])
+            .filter((r) => r.ref.startsWith(`${kind}/`))
+            .map((r) => ({ ref: r.ref, state: r.state, label: r.label, reason: r.reason, fix: r.fix ?? null, ...(r.warnings?.length ? { warnings: r.warnings } : {}) })),
+        }),
+      )
+    }
+    // Where each Custom App's code is (its folder, not pulled, or none yet), with its one status as `local status` says
+    // it (deployed to this runtime, built, not built, no code): Studio's Apps page says it, and how to work on it.
+    if (url.pathname === '/__local/apps') {
+      return json({
+        apps: appCodeStates(project.root).map((code) => {
+          const row = appStatusRow(project.root, code)
+          return { ...code, status: row.appStatus, label: row.label, fix: row.fix ?? null }
+        }),
+      })
+    }
     // The Blueprint's definitions as the files state them, so they show before anything is applied.
     if (url.pathname === '/__local/blueprint') {
       return json({ objectTypes: projectBlueprintOutline(project.root) })
@@ -132,11 +176,17 @@ export function startStudioServer(opts: StudioServerOptions) {
     // The solution's saved cases (`agents/<slug>/evals/*.yaml`), read fresh each time.
     if (url.pathname === '/__local/test-cases') {
       try {
-        return json({ files: findCaseFiles(project.root) })
+        // Each Agent by the name its agent.json gives it, as the home and Agents say it, not its folder.
+        return json({ files: findCaseFiles(project.root).map((f) => ({ ...f, agentName: agentFileName(project.root, f.agent) })) })
       } catch (err) {
         return json({ error: `a case file could not be read: ${(err as Error).message}` }, 422)
       }
     }
+    // The workflows' test files (`workflows/tests/*.yaml`): `frontera local test` runs them; Evaluations lists them.
+    if (url.pathname === '/__local/workflow-tests') {
+      // Each case by name, with its last run (`frontera local test` keeps it), so Evaluations lists them.
+      return json({ files: workflowTestListing(project.root, project.stateDir) })
+    }
     if (url.pathname === '/__local/test-runs') return json({ runs: testRuns.list() })
     const runMatch = /^\/__local\/test-runs\/([0-9a-f-]+)$/.exec(url.pathname)
     if (runMatch) {
@@ -171,10 +221,122 @@ export function startStudioServer(opts: StudioServerOptions) {
       const agent = (await get(`/v1/config/agents/${encodeURIComponent(body.agentId)}`)) as { agentId?: string }
       const messages = (await get(`/v1/sessions/${encodeURIComponent(body.conversationId)}/messages`)) as unknown
       const list = Array.isArray(messages) ? messages : ((messages as { messages?: unknown[] })?.messages ?? [])
-      const yaml = renderTestCase({ conversationId: body.conversationId, messages: list as never[], savedAt: new Date().toISOString() })
+      // The variables the conversation started with, when its Test setup recorded them: the case replays as the same customer.
+      const session = (await get(`/v1/config/agents/${encodeURIComponent(body.agentId)}/try/conversations/${encodeURIComponent(body.conversationId)}/session`).catch(() => null)) as { timeline?: Array<{ payload?: Record<string, unknown> | null }> } | null
+      const variables = variablesOfTimeline(session?.timeline ?? [])
+      // A sensitive variable is named in the setup, never its value: the case says to fill it in by hand.
+      const redacted = redactedVariablesOfTimeline(session?.timeline ?? [])
+      // The tool approvals it stopped on, as the person decided them: the case answers them the same way.
+      const cards = (await get(`/v1/chat/approvals?conversationId=${encodeURIComponent(body.conversationId)}`).catch(() => [])) as unknown
+      const { decision, mixed } = decisionOfApprovals(Array.isArray(cards) ? cards : [])
+      const yaml = noteRedactedVariables(renderTestCase({ conversationId: body.conversationId, messages: list as never[], savedAt: new Date().toISOString(), ...(variables ? { variables } : {}), ...(decision ? { decision } : {}) }), redacted)
       const path = appendTestCase(project.root, agent.agentId ?? body.agentId, yaml)
-      return json({ path })
+      const notes = [...(redacted.length ? [redactedVariablesLine(redacted, path)] : []), ...(mixed ? [MIXED_DECISIONS_LINE] : [])]
+      return json({ path, ...(decision ? { decision } : {}), ...(redacted.length ? { redactedVariables: redacted } : {}), ...(notes.length ? { note: notes.join(' ') } : {}) })
+    } catch (err) {
+      return json({ error: (err as Error).message }, 502)
+    }
+  }
+
+  /** The local service as the seeded owner, for the routes that act on the runtime themselves; null before it is seeded. */
+  const serviceCall = (): ServiceCall | null => {
+    const creds = readState(project)?.credentials
+    const bearer = creds?.session ?? creds?.workspaceKey
+    if (!creds || !bearer) return null
+    return async (method, path) => {
+      const res = await fetch(new URL(path, opts.serviceUrl), { method, headers: { authorization: `Bearer ${bearer}`, 'x-org-id': creds.organizationId, 'x-workspace-id': creds.workspaceId } })
+      const text = await res.text()
+      if (!res.ok) throw new Error(`the runtime answered ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}`)
+      return text ? (JSON.parse(text) as unknown) : null
+    }
+  }
+
+  /** Whether a `local dev` watcher is applying this project's saved files (Forge keeps one running). */
+  const watching = (): boolean => {
+    try {
+      return isAlive(Number(readFileSync(join(project.stateDir, 'dev.pid'), 'utf8').trim()))
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * A knowledge base's documents as the project's files (`local-knowledge-uploads.ts`):
+   *   GET    /__local/knowledge?base=<name>&id=<knowledge id>   its folder, its documents and whether the runtime has each, its apply state
+   *   POST   /__local/knowledge/documents?base=&id=[&replace=1] save one document (multipart `file`) into its folder
+   *   DELETE /__local/knowledge/documents?base=&id=&sourceId=   take a document off the runtime and out of the folder
+   */
+  const knowledgeRoute = async (req: Request, url: URL): Promise<Response> => {
+    const base = (url.searchParams.get('base') ?? '').trim()
+    const id = url.searchParams.get('id') ?? ''
+    if (!base || base.length > 200) return json({ error: 'name the knowledge base, as base=<name>' }, 400)
+    if (id && !/^[\w-]{1,80}$/.test(id)) return json({ error: 'id is not a knowledge base id' }, 400)
+    const folder = knowledgeFolderOf(project.root, base)
+    try {
+      if (url.pathname === '/__local/knowledge' && req.method === 'GET') {
+        const accepted = { extensions: KNOWLEDGE_UPLOAD_EXTENSIONS, maxBytes: MAX_KNOWLEDGE_UPLOAD_BYTES }
+        if (!folder) return json({ folder: null, documents: [], apply: null, watching: watching(), accepted })
+        const call = id ? serviceCall() : null
+        const onRuntime = call ? await runtimeDocuments(call, id).then((docs) => new Set(docs.map((d) => d.path)), () => null) : null
+        const status = solutionStatus(project, readState(project)?.credentials?.organizationId ?? null, (t) => t.kind === 'knowledge' && t.name === folder)[0]
+        return json({
+          folder: `knowledge/${folder}/`,
+          documents: projectDocuments(project.root, folder, onRuntime),
+          apply: status ? { state: status.state, ...(status.detail ? { detail: status.detail } : {}), ...(status.fix ? { fix: status.fix } : {}), ...(status.waiting ? { waiting: true } : {}) } : null,
+          watching: watching(),
+          accepted,
+        })
+      }
+      if (url.pathname !== '/__local/knowledge/documents') return json({ error: 'not found' }, 404)
+      if (req.method === 'POST') {
+        if (!folder) return json({ error: `${base} has no folder in the project (knowledge/<name>/knowledge.json), so a document can't be saved to it here` }, 404)
+        // Refused before the body is read: the form's boundary and fields add little beyond the file.
+        if (Number(req.headers.get('content-length') ?? 0) > MAX_KNOWLEDGE_UPLOAD_BYTES + 64 * 1024) {
+          return json({ error: `the document is larger than ${MAX_KNOWLEDGE_UPLOAD_BYTES / 1024 / 1024} MB, the most a knowledge base takes` }, 413)
+        }
+        const form = await req.formData().catch(() => null)
+        const file = form?.get('file')
+        if (!(file instanceof Blob)) return json({ error: 'send the document as the multipart field "file"' }, 400)
+        const name = checkUpload((file as File).name ?? '', file.size)
+        const replace = url.searchParams.get('replace') === '1'
+        // Replacing: the runtime's copy goes first, so the apply uploads the new content (it only adds what the runtime lacks).
+        if (replace && id && documentInFolder(project.root, folder, name)) {
+          const call = serviceCall()
+          if (call) {
+            try {
+              await removeRuntimeCopies(call, id, name)
+            } catch (err) {
+              return json({ error: `the runtime's copy of ${name} couldn't be taken off (${(err as Error).message}), so knowledge/${folder}/${name} is left as it was` }, 502)
+            }
+          }
+        }
+        const saved = saveKnowledgeDocument(project.root, folder, name, new Uint8Array(await file.arrayBuffer()), { replace })
+        return json({ ...saved, watching: watching() })
+      }
+      if (req.method === 'DELETE') {
+        const sourceId = url.searchParams.get('sourceId') ?? ''
+        if (!id || !/^[\w-]{1,80}$/.test(sourceId)) return json({ error: 'name the document, as id=<knowledge id>&sourceId=<document id>' }, 400)
+        const call = serviceCall()
+        if (!call) return json({ error: 'the runtime is not seeded yet' }, 409)
+        const source = (await runtimeDocuments(call, id)).find((d) => d.id === sourceId)
+        if (!source) return json({ error: 'the runtime has no such document in this knowledge base' }, 404)
+        await call('DELETE', `/v1/workspace-knowledge/${encodeURIComponent(id)}/sources/${encodeURIComponent(sourceId)}`)
+        // Its file too, so the next apply does not upload it again; a base with no folder had only the runtime's copy.
+        // A runtime document of a kind or name the folder can't hold (a spreadsheet uploaded on the runtime) has no file to remove.
+        const removed = (() => {
+          if (!folder) return { path: null, removed: false }
+          try {
+            return removeKnowledgeDocument(project.root, folder, source.path)
+          } catch (err) {
+            if (err instanceof KnowledgeDocumentError && err.status !== 409) return { path: null, removed: false }
+            throw err
+          }
+        })()
+        return json({ path: removed.path, removedFile: removed.removed })
+      }
+      return json({ error: 'not found' }, 404)
     } catch (err) {
+      if (err instanceof KnowledgeDocumentError) return json({ error: err.message, ...err.extra }, err.status)
       return json({ error: (err as Error).message }, 502)
     }
   }
@@ -316,6 +478,7 @@ export function startStudioServer(opts: StudioServerOptions) {
         const started = testRuns.start({ agent: typeof body.agent === 'string' ? body.agent : undefined, live: body.live === true })
         return 'run' in started ? json(started.run, 202) : json({ error: started.error }, started.status)
       }
+      if (url.pathname === '/__local/knowledge' || url.pathname === '/__local/knowledge/documents') return knowledgeRoute(req, url)
       if (url.pathname.startsWith('/__local/')) return localRoute(url)
       // `/api/…` is the service; `/api` alone is Studio's API page.
       if (url.pathname.startsWith('/api/')) return proxy(req, url)

package/src/local/local-supervisor.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path'
 import {
   containerState,
   copyFromContainer,
+  dbVolumeName,
   execInContainer,
   followLogs,
   imagePresent,
@@ -13,6 +14,7 @@ import {
   runContainer,
   startContainer,
   stopContainer,
+  storageVolumeName,
 } from './local-docker'
 import {
   CATALOG_DB,
@@ -30,14 +32,15 @@ import {
   type LocalConfig,
   type LocalSecrets,
 } from './local-env'
-import { keylessEmbeddings, providerEnv } from './local-keys'
+import { localEmbeddingsReachable, providerEnv } from './local-keys'
 import { applyProviderSetup, readProviderSetup, rememberSlugs, writeProviderSetup } from './local-providers'
 import type { PortBlock } from './local-ports'
 import { startProcess, stopProcess, waitForHttp } from './local-process'
 import type { LocalProject } from './local-project'
 import { startLocalEmbeddings } from './local-embeddings'
 import { LOCAL_TRACE_KEYS, startLocalTraces } from './local-traces'
-import { copyDocs, customerDocsBundle, IMAGE_DOCS_PATH } from './local-docs'
+import { recordRuntime } from './local-runtime-history'
+import { buildDocs, checkoutDocsStale, copyDocs, customerDocsBundle, IMAGE_DOCS_PATH, writeDocsBuildMarker } from './local-docs'
 import { keepSchemas, type SchemaSource } from './local-schemas'
 import { applyModelKeys, ensureBlueprint, ensureOrgKey, ensureProviderModels, retireLocalModel, seedLocalRuntime, signIn } from './local-seed'
 import {
@@ -80,7 +83,7 @@ export const IMAGES = {
 export const containerName = (project: LocalProject, component: ComponentName) =>
   `frontera-${project.id}-${component}`
 
-export const volumeName = (project: LocalProject) => `frontera-${project.id}-db`
+export const volumeName = (project: LocalProject) => dbVolumeName(project.id)
 
 interface Running {
   children: Map<ComponentName, ChildProcess>
@@ -144,6 +147,8 @@ export async function runSupervisor(project: LocalProject, ports: PortBlock, ses
     }
     for (const name of [...running.containers].reverse()) stopContainer(name)
     for (const c of state.components) if (c.status === 'running' || c.status === 'starting') set(c.name, { status: 'stopped' })
+    // A failed start says so where it failed (`fail`); this is the stop of a runtime that was up.
+    if (code === 0) recordRuntime(project, { event: 'stopped', at: new Date().toISOString() })
     state = { ...state, phase: 'stopped', supervisorPid: undefined }
     save()
     process.exit(code)
@@ -155,6 +160,7 @@ export async function runSupervisor(project: LocalProject, ports: PortBlock, ses
     set(name, { status: 'failed', detail })
     state = { ...state, phase: 'failed', error: `${name}: ${detail}` }
     save()
+    recordRuntime(project, { event: 'failed', at: new Date().toISOString(), since: state.startedAt, detail: `${name}: ${detail}` })
     await shutdown(1)
   }
 
@@ -278,6 +284,7 @@ export async function runSupervisor(project: LocalProject, ports: PortBlock, ses
     set('studio', { status: 'running', startedAt: new Date().toISOString(), pid: process.pid })
     state = { ...state, phase: 'ready', error: undefined }
     save()
+    recordRuntime(project, { event: 'started', at: new Date().toISOString(), since: state.startedAt })
   } catch (err) {
     const failing = state.components.find((c) => c.status === 'starting')?.name ?? 'service'
     await fail(failing, (err as Error).message)
@@ -393,7 +400,7 @@ async function startStorage(project: LocalProject, ports: PortBlock, secrets: Lo
       projectId: project.id,
       ports: [{ host: ports.storage, container: 9000 }],
       env: { RUSTFS_ACCESS_KEY: secrets.storageAccessKey, RUSTFS_SECRET_KEY: secrets.storageSecretKey },
-      volumes: [{ name: `frontera-${project.id}-storage`, path: '/data' }],
+      volumes: [{ name: storageVolumeName(project.id), path: '/data' }],
       memory: '256m',
       cpus: '0.5',
       args: ['server', '/data'],
@@ -462,7 +469,7 @@ async function startService(
     runnerEnabled,
     jobsEnabled,
     storageEnabled,
-    keylessEmbeddings: keylessEmbeddings(),
+    keylessEmbeddings: localEmbeddingsReachable(),
     documentationBundle: config.mode === 'source' ? customerDocsBundle(config.platformSource) : null,
   })
   const log = logPath(project, 'service')
@@ -479,6 +486,7 @@ async function startService(
     if (!ok) throw new Error('the service did not become healthy; see `frontera local logs service`')
     set('service', { status: 'running', pid: child.pid, startedAt: new Date().toISOString() })
     keepDocs(project, { bundle: customerDocsBundle(config.platformSource) }, log)
+    refreshCheckoutDocs(project, config.platformSource, log)
     return
   }
   const name = containerName(project, 'service')
@@ -504,7 +512,7 @@ async function startService(
   keepDocs(project, { fromContainer: (dest) => copyFromContainer(name, IMAGE_DOCS_PATH, dest) }, log)
 }
 
-/** The release's documentation, for the solution's coding agents (`local docs-mcp`). */
+/** The release's documentation, for the solution's coding agents (`frontera mcp`). */
 function keepDocs(project: LocalProject, from: { bundle?: string | null; fromContainer?: (dest: string) => boolean }, log: string): void {
   if (!from.bundle && !from.fromContainer) {
     appendFileSync(log, '[docs] no customer documentation in the platform checkout; run `bun run docs:build` there\n')
@@ -514,6 +522,36 @@ function keepDocs(project: LocalProject, from: { bundle?: string | null; fromCon
   if (problem) appendFileSync(log, `[docs] the documentation for coding agents was not copied: ${problem}\n`)
 }
 
+/**
+ * From a checkout whose documentation build is behind it (no build, guides
+ * changed since, another version): build it in the background, at low
+ * priority, and refresh the copy when it is done. Start never waits for it:
+ * the copy from the previous build serves until then, and the service rereads
+ * the checkout's publication when it changes on disk.
+ */
+function refreshCheckoutDocs(project: LocalProject, platformSource: string | undefined, log: string): void {
+  if (!platformSource) return
+  const why = checkoutDocsStale(platformSource)
+  if (!why) {
+    // Current: a failure an earlier start recorded no longer applies.
+    writeDocsBuildMarker(project, null)
+    return
+  }
+  appendFileSync(log, `[docs] ${why}; building it in the background (nice -n 10 bun run docs:build); the previous copy serves until it is done\n`)
+  // What `local status` and Forge's Docs say while it builds ("rebuilding"), and if it fails.
+  writeDocsBuildMarker(project, { state: 'building', at: new Date().toISOString(), pid: process.pid, why })
+  void buildDocs(platformSource, log).then((built) => {
+    if (!built) {
+      writeDocsBuildMarker(project, { state: 'failed', at: new Date().toISOString(), why })
+      appendFileSync(log, '[docs] the documentation build did not finish; coding agents keep the previous copy (`bun run docs:build` in the checkout shows why)\n')
+      return
+    }
+    keepDocs(project, { bundle: customerDocsBundle(platformSource) }, log)
+    writeDocsBuildMarker(project, null)
+    appendFileSync(log, '[docs] built the documentation and refreshed the copy for coding agents\n')
+  })
+}
+
 /** The formats of the project's files, for its coding agents and editors (`local schema`). Logged, never a reason to fail start. */
 async function keepFileSchemas(project: LocalProject, source: SchemaSource, log: string): Promise<void> {
   for (const problem of await keepSchemas(project, source)) appendFileSync(log, `[schemas] not kept: ${problem}\n`)

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

@@ -372,7 +372,7 @@ export function mergeItemFiles(
   theirs: Record<string, string | null>,
   opts: Omit<MergeOptions, 'offset'> = {},
 ): { files: FileMerge[]; conflicts: number } {
-  const paths = [...new Set([...Object.keys(base), ...Object.keys(ours), ...Object.keys(theirs)])].sort()
+  const paths = [...new Set([...Object.keys(base), ...Object.keys(ours), ...Object.keys(theirs)])].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
   const files: FileMerge[] = []
   let offset = 0
   for (const path of paths) {

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

@@ -131,6 +131,8 @@ export function itemTitle(kind: string, name: string, files: Record<string, stri
     const own = declared(doc?.config, 'name') ?? declared(doc, 'name')
     if (own) return own
   }
+  // The workspace's own grants beyond read (`blueprint/workspace-grants.yaml`): one file, no display name.
+  if (kind === 'blueprint' && name === 'workspace-grants') return 'Workspace grants'
   if (kind === 'blueprint') {
     const [dir, apiName] = name.split('/')
     const file = Object.entries(files).find(([p]) => p.startsWith(`blueprint/${dir}/${apiName}.`))?.[1]

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

@@ -84,6 +84,13 @@ export interface RemoteItem {
    * is being read; `from`, the snapshot's copy, once fetched.
    */
   assets?: ItemAsset[]
+  /**
+   * Files the pull recovered from the item's deployed bundle because its
+   * source lacks them (a Function's imports from beside its folder), by
+   * project path. Pulled like any other file; listed so it is never mistaken
+   * for the original source.
+   */
+  recovered?: string[]
 }
 
 export interface ItemAsset {
@@ -193,6 +200,8 @@ export interface LockEntry {
   pulledAt: string
   /** Pulled with conflicts not yet resolved; the base above is still the last clean pull. */
   conflict?: LockConflict
+  /** Its files the pull recovered from the deployed bundle, not its source (`RemoteItem.recovered`). */
+  recovered?: string[]
 }
 
 /**
@@ -214,7 +223,7 @@ export function hash(text: string): string {
 }
 
 export function itemHash(files: Record<string, string>): string {
-  return hash(Object.keys(files).sort().map((p) => `${p}\0${files[p]}`).join('\0\0'))
+  return hash(Object.keys(files).sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0)).map((p) => `${p}\0${files[p]}`).join('\0\0'))
 }
 
 export function readLock(root: string): SyncLock | null {
@@ -231,7 +240,7 @@ export function readLock(root: string): SyncLock | null {
 
 /** Sorted keys, two spaces, a final newline: a lock diffs cleanly in review. Always written as v2. */
 export function writeLock(root: string, lock: SyncLock): void {
-  const items = Object.fromEntries(Object.keys(lock.items).sort().map((k) => [k, sortEntry(lock.items[k]!)]))
+  const items = Object.fromEntries(Object.keys(lock.items).sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0)).map((k) => [k, sortEntry(lock.items[k]!)]))
   writeFileSync(join(root, LOCK_FILE), `${JSON.stringify({ version: 2, workspace: lock.workspace, ...(lock.pulledAt ? { pulledAt: lock.pulledAt } : {}), items }, null, 2)}\n`)
 }
 
@@ -240,11 +249,12 @@ function sortEntry(entry: LockEntry): LockEntry {
     ...(entry.id ? { id: entry.id } : {}),
     ...(entry.revision ? { revision: entry.revision } : {}),
     remote: entry.remote,
-    files: Object.fromEntries(Object.keys(entry.files).sort().map((k) => [k, entry.files[k]!])),
+    files: Object.fromEntries(Object.keys(entry.files).sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0)).map((k) => [k, entry.files[k]!])),
     ...(entry.version ? { version: entry.version } : {}),
     ...(entry.state ? { state: entry.state } : {}),
     pulledAt: entry.pulledAt,
     ...(entry.conflict ? { conflict: sortConflict(entry.conflict) } : {}),
+    ...(entry.recovered?.length ? { recovered: [...entry.recovered].sort() } : {}),
   }
 }
 
@@ -252,7 +262,7 @@ function sortConflict(c: LockConflict): LockConflict {
   return {
     remote: c.remote,
     ...(c.revision ? { revision: c.revision } : {}),
-    files: [...c.files].sort(),
+    files: [...c.files].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0)),
     at: c.at,
     ...(c.count !== undefined ? { count: c.count } : {}),
     ...(c.id ? { id: c.id } : {}),
@@ -390,7 +400,7 @@ export function computePlan(root: string, remote: RemoteItem[], lock: SyncLock |
   for (const item of remote) {
     seen.add(item.ref)
     const entry = lock?.items[item.ref]
-    const paths = [...new Set([...Object.keys(item.files), ...Object.keys(entry?.files ?? {})])].sort()
+    const paths = [...new Set([...Object.keys(item.files), ...Object.keys(entry?.files ?? {})])].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
     const files: FileChange[] = paths.map((path) => ({ path, local: readComparable(root, path, opts.base), remote: item.files[path] ?? null }))
     // An Agent's file that neither the base nor the workspace has but the folder does (its first tools, in a new
     // `bindings.json`) is a change here too, as push reads it: otherwise status says nothing while push proposes it.
@@ -475,6 +485,7 @@ function entryFor(item: RemoteItem, now: string): LockEntry {
     ...(item.version ? { version: item.version } : {}),
     ...(item.state ? { state: item.state } : {}),
     pulledAt: now,
+    ...(item.recovered?.length ? { recovered: [...item.recovered].sort() } : {}),
   }
 }
 
@@ -542,7 +553,7 @@ export function applyItems(root: string, workspace: string, items: RemoteItem[],
   for (const item of items) {
     const previous = next.items[item.ref]
     if (opts.merge?.has(item.ref)) {
-      const paths = [...new Set([...Object.keys(item.files), ...Object.keys(previous?.files ?? {})])].sort()
+      const paths = [...new Set([...Object.keys(item.files), ...Object.keys(previous?.files ?? {})])].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
       const result = mergeItemFiles(baseFiles(previous, opts.base), localFiles(root, paths), item.files)
       if (result.conflicts) {
         const files = result.files.filter((f) => f.conflicts.length).map((f) => f.path)
@@ -622,7 +633,7 @@ export function refreshConflict(root: string, workspace: string, item: RemoteIte
   const previous = next.items[item.ref]
   const remote = itemHash(item.files)
   if (!previous?.conflict || previous.conflict.remote === remote) return { lock: next, outcome: 'unchanged', conflicts: previous?.conflict?.count ?? 0, written: [], removed: [] }
-  const paths = [...new Set([...Object.keys(item.files), ...Object.keys(previous.files), ...previous.conflict.files])].sort()
+  const paths = [...new Set([...Object.keys(item.files), ...Object.keys(previous.files), ...previous.conflict.files])].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
   const result = mergeItemFiles(baseFiles(previous, base), localFiles(root, paths), item.files)
   const now = new Date().toISOString()
   const written: string[] = []
@@ -662,7 +673,7 @@ export type Resolution = { edited: true } | { keep?: Side; picks?: Map<number, C
 export function resolveItem(root: string, workspace: string, item: RemoteItem, lock: SyncLock | null, how: Resolution, base?: (path: string) => string | null): { written: string[]; removed: string[]; lock: SyncLock } {
   const next: SyncLock = { version: 2, workspace, items: { ...(lock?.workspace === workspace ? lock.items : {}) } }
   const previous = next.items[item.ref]
-  const paths = [...new Set([...Object.keys(item.files), ...Object.keys(previous?.files ?? {}), ...(previous?.conflict?.files ?? [])])].sort()
+  const paths = [...new Set([...Object.keys(item.files), ...Object.keys(previous?.files ?? {}), ...(previous?.conflict?.files ?? [])])].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
   const written: string[] = []
   const removed: string[] = []
   if (!('edited' in how)) {

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

@@ -1,13 +1,15 @@
 import { createHash } from 'node:crypto'
-import { appendFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, join, posix } from 'node:path'
 
+import { ignoreInFronteraDir } from '../project-context'
 import matter from 'gray-matter'
 import { parse as parseYaml } from 'yaml'
 
 import { mimeFromPath } from '../commands/skill/bundle-commands'
 import { writeFileAtomic } from '../fs-atomic'
 import { CliError } from '../errors'
+import { readWorkspaceGrants, WORKSPACE_GRANTS_FILE, WORKSPACE_GRANTS_NAME, WORKSPACE_GRANTS_REF } from './local-workspace-grants'
 import { documentChanges, localDocuments, splitDocumentPath, type PulledDocument } from './local-knowledge-documents'
 import { QUALITY_CHECKS_FILE, qualityChecksPath, readQualityChecks } from './local-quality-checks'
 import { lessonsPath, lessonsProposal } from './local-lessons'
@@ -226,7 +228,7 @@ export function itemFiles(root: string, kind: SyncKind, name: string, entry?: Lo
   // What the last pull wrote for it comes along when it is still here (an agent's files are fixed; the rest may not be).
   if (kind !== 'agent' && kind !== 'knowledge') for (const p of Object.keys(entry?.files ?? {})) if (!paths.includes(p)) paths.push(p)
   const files: Record<string, string> = {}
-  for (const path of [...new Set(paths)].sort()) {
+  for (const path of [...new Set(paths)].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))) {
     if (path.endsWith('.workspace') || assets.includes(path)) continue
     const text = readLocal(root, path)
     if (text === null) continue
@@ -266,6 +268,8 @@ export function projectRefs(root: string): Map<string, { kind: SyncKind; name: s
   for (const n of dirs('skills')) if (existsSync(join(root, 'skills', n, 'SKILL.md'))) add('skill', n)
   for (const n of dirs('knowledge')) if (existsSync(join(root, 'knowledge', n, 'knowledge.json'))) add('knowledge', n)
   for (const dir of BLUEPRINT_DIRS) for (const f of dirs(`blueprint/${dir}`)) if (/\.(ya?ml|json)$/.test(f)) add('blueprint', `${dir}/${f.replace(/\.(ya?ml|json)$/, '')}`)
+  // The workspace's own grants beyond read: one Blueprint item, `blueprint/workspace-grants`.
+  if (existsSync(join(root, WORKSPACE_GRANTS_FILE))) add('blueprint', WORKSPACE_GRANTS_NAME)
   for (const f of dirs('mcp')) if (f.endsWith('.plugin.json') && f !== '.plugin.json') add('plugin', f.slice(0, -'.plugin.json'.length))
   for (const f of dirs('chat-apps')) if (f.endsWith('.json') && f !== '.json') add('chat-app', f.slice(0, -'.json'.length))
   for (const slug of dirs('agents')) if (existsSync(join(root, lessonsPath(slug)))) add('lessons', slug)
@@ -368,7 +372,7 @@ export function pushCandidates(input: CandidateInput): PushItem[] {
   const here = projectRefs(root)
   const refs = new Set<string>([...plan.map((p) => p.ref), ...here.keys()])
   const out: PushItem[] = []
-  for (const ref of [...refs].sort()) {
+  for (const ref of [...refs].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))) {
     const slash = ref.indexOf('/')
     const kind = (byPlan.get(ref)?.kind ?? here.get(ref)?.kind ?? ref.slice(0, slash)) as SyncKind
     const name = byPlan.get(ref)?.name ?? here.get(ref)?.name ?? ref.slice(slash + 1)
@@ -400,7 +404,7 @@ export function pushCandidates(input: CandidateInput): PushItem[] {
     if (status === 'same' && Object.keys(files).length === 0) continue
     const isNew = !entry && !theirs
     const baseFiles: Record<string, string> = !isNew && theirs && entry && itemHash(theirs.files) === entry.remote ? theirs.files : {}
-    const diffPaths = [...new Set([...Object.keys(baseFiles), ...Object.keys(files)])].sort()
+    const diffPaths = [...new Set([...Object.keys(baseFiles), ...Object.keys(files)])].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
     const diff: PushFile[] = diffPaths.map((path) => ({ path, base: baseFiles[path] ?? null, local: files[path] ?? null })).filter((f) => f.base !== f.local)
     const item: PushItem = {
       ref,
@@ -441,12 +445,15 @@ export function pushCandidates(input: CandidateInput): PushItem[] {
     else if (status === 'conflict') block('moved', BLOCK_REASON.moved)
     else if (status === 'unresolved') block('conflicts', BLOCK_REASON.conflicts)
     else if (deleted && NOT_DELETED[kind]) block('shape', NOT_DELETED[kind]!)
+    // Never proposed as a deletion: the platform refuses one, since deleting the file changes no grant.
+    else if (deleted && ref === WORKSPACE_GRANTS_REF) block('shape', `Deleting ${WORKSPACE_GRANTS_FILE} changes no grant: to take read_sensitive away, put the file back and list the type with \`permissions: [read]\``)
     else if (status === 'deleted-remote') block('workspace-deleted', BLOCK_REASON['workspace-deleted'])
     else if (deleted) {
       // Proposable: Apply deletes it there, after everything that names it is updated.
     } else if (problem) block('shape', problem)
     else if (!Object.keys(files).length) block('shape', 'No files to propose')
     else if (kind === 'blueprint' && Object.keys(files).length > 1) block('shape', `${Object.keys(files).join(' and ')}: keep one file per Blueprint artifact`)
+    else if (ref === WORKSPACE_GRANTS_REF && readWorkspaceGrants(root)?.problems.length) block('shape', readWorkspaceGrants(root)!.problems.join('; '))
     else if (assetState?.changed && entry?.revision && theirs?.revision && entry.revision !== theirs.revision && textSame) {
       // A pull never writes over an asset the folder has, so one the workspace changed since reads as a change here.
       block('moved', 'Its assets changed in the workspace since your last pull: delete the copies here to bring the workspace’s, then propose')
@@ -577,12 +584,8 @@ const REQUESTS_DIR = join(SYNC_DIR, 'requests')
 
 /** `.frontera/sync/` stays out of git, the requests with it. */
 function ignoreSync(root: string): void {
-  const ignore = join(root, '.frontera', '.gitignore')
-  mkdirSync(dirname(ignore), { recursive: true })
-  const text = existsSync(ignore) ? readFileSync(ignore, 'utf8') : ''
-  if (text.split(/\r?\n/).some((l) => l.trim() === 'sync/' || l.trim() === 'sync')) return
-  if (text) appendFileSync(ignore, `${text.endsWith('\n') ? '' : '\n'}sync/\n`)
-  else writeFileSync(ignore, 'local/\nsync/\n')
+  // A pulled or linked project: its sync state, and this machine's profile binding, stay out of git.
+  ignoreInFronteraDir(root, ['local/', 'sync/'])
 }
 
 /** The requests file for this workspace; another workspace's (a relinked project) reads as none. */
@@ -626,7 +629,7 @@ export function recordRequest(root: string, workspace: string, view: RequestView
   const file = readRequests(root, workspace)
   const now = (opts.now ?? new Date()).toISOString()
   const before = file.requests[view.request.id]
-  const refs = view.items.map((i) => i.ref).sort()
+  const refs = view.items.map((i) => i.ref).sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
   const titles = Object.fromEntries(refs.map((r) => [r, opts.titles?.[r] ?? before?.titles[r] ?? r]))
   file.requests[view.request.id] = {
     id: view.request.id,
@@ -713,7 +716,7 @@ export function sameDocument(path: string, a: string, b: string): boolean {
 /** Quality checks as a set: by question, each one's lists in order of their words. */
 function checkSet(text: string): unknown {
   return readQualityChecks(text)
-    .map((c) => ({ ...c, documents: [...(c.documents ?? [])].sort(), keywords: [...(c.keywords ?? [])].sort() }))
+    .map((c) => ({ ...c, documents: [...(c.documents ?? [])].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0)), keywords: [...(c.keywords ?? [])].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0)) }))
     .sort((x, y) => x.question.localeCompare(y.question))
 }