@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/local/local-portability.ts

@@ -1,5 +1,8 @@
+import { posix } from 'node:path'
+
 import { parse as parseYaml } from 'yaml'
 
+import { actionSemanticConflicts, type SemanticFacts } from '../blueprint/action-semantic-fit'
 import { unnamedObjectBindings } from './local-objects'
 import { governedActionIds, referencesIn } from './local-sync-refs'
 
@@ -38,7 +41,7 @@ export interface RuntimeCapabilities {
   media: boolean
   /** Built-in connections signed in with OAuth or a service account (Google Sheets, BigQuery…). */
   connections: boolean
-  /** Calculated properties (a location from latitude and longitude); `blueprint apply` cannot create one yet. */
+  /** Calculated properties other than a location (which `blueprint apply` adds); none has a route from a file yet. */
   calculatedFields: boolean
   /** Governed Actions: `local` deploys those that write the Blueprint's own records (D3). */
   governedActions: 'local' | 'none'
@@ -78,6 +81,26 @@ export type Need =
   | { kind: 'app-code'; external?: boolean }
   /** An Agent's object tools whose object definition the pull couldn't name (an older platform). */
   | { kind: 'objects-unnamed'; count: number }
+  /**
+   * A Function's code imports files the pull couldn't bring (its source in the
+   * workspace doesn't hold them), by project path without extension: it can't
+   * build here, as `local dev` says with FUNCTION_IMPORT_MISSING.
+   */
+  | { kind: 'imports-missing'; paths: string[] }
+  /**
+   * A governed Action the local runtime refuses as written (the Action draft
+   * route's checks, such as an input value the set property's semantic type
+   * refuses): `local dev` tries it and it fails to apply, with that reason.
+   */
+  | { kind: 'action-refused'; reasons: string[] }
+  /**
+   * A governed Action that offers a value the semantic type of the property it
+   * writes refuses, as the workspace runs it: it deploys here as it is there,
+   * the conflict said as a warning inherited from the workspace, and a request
+   * with such a value is refused when it is submitted, here as there. (An
+   * index from before this read the same Action as `action-refused`.)
+   */
+  | { kind: 'action-inherited'; reasons: string[] }
 
 export interface Portability {
   class: PortabilityClass
@@ -108,8 +131,17 @@ export function judge(need: Need, ctx: Context = {}): { class: PortabilityClass;
       const fit = ctx.actions?.get(need.name)
       // Unknown here: what the build says about it decides; at fetch it comes down with the Blueprint.
       if (!fit || fit.runsLocally) return null
+      if (fit.refused) return { class: 'adapted', text: `goes without governed Action ${need.name} here: the local runtime refuses it as written` }
       return { class: 'adapted', text: `governed Action ${need.name} is switched off here: ${fit.reason}` }
     }
+    case 'imports-missing':
+      return { class: 'platform-only', text: `won’t build here: it imports ${listed(need.paths)}, which its source in the workspace doesn’t hold, so the pull couldn’t bring ${need.paths.length === 1 ? 'it' : 'them'}` }
+    case 'action-refused':
+      // Not left off: `local dev` still deploys it, and the runtime refuses it, so the build says it failed.
+      return { class: 'platform-only', text: `the local runtime refuses it as written: ${need.reasons.join(' ')}` }
+    case 'action-inherited':
+      // It runs here as it does in the workspace: a warning, not an adaptation.
+      return { class: 'portable', text: `runs here as the workspace runs it, with a warning inherited from the workspace: ${need.reasons.join(' ')} The Blueprint’s author fixes the Action’s contract in the workspace` }
     case 'action-unnamed':
       return { class: 'platform-only', text: `runs ${need.count === 1 ? 'a governed Action' : `${need.count} governed Actions`} this key can’t name: add an organization key to bring ${need.count === 1 ? 'it' : 'them'}` }
     case 'connection':
@@ -123,19 +155,19 @@ export function judge(need: Need, ctx: Context = {}): { class: PortabilityClass;
     case 'media':
       return caps.media ? null : { class: 'platform-only', text: 'reads the platform’s media files, so the local runtime leaves it off' }
     case 'media-stub':
-      return caps.media ? null : { class: 'stubbed', text: `its files stay on the platform: an empty Media Set, ${need.set}, stands in for them here` }
+      return caps.media ? null : { class: 'stubbed', text: `its files stay on the platform: a stand-in Media Set, ${need.set}, holds placeholder files for them here` }
     case 'calculated':
       return caps.calculatedFields
         ? null
-        : { class: 'adapted', text: `${need.fields.join(', ')} ${need.fields.length === 1 ? 'is' : 'are'} left off: calculated fields aren’t applied locally yet` }
+        : { class: 'adapted', text: `${need.fields.join(', ')} ${need.fields.length === 1 ? 'is' : 'are'} left off: only a location is a calculated field a file can add` }
     case 'markings':
       return { class: 'adapted', text: `reads every row: its markings come from the platform’s dataset, and ${need.dataset} has none` }
     case 'external-effect':
       return { class: 'stubbed', text: 'switched off here: it changes a system outside the local runtime' }
     case 'app-draft':
-      return { class: 'adapted', text: 'saved as the owner’s draft here and opened as its preview, its Agents running their drafts: a Chat App publishes only published Agents, and the local runtime’s Agents are drafts' }
+      return { class: 'adapted', text: 'saved as the owner’s draft here: Studio opens it at /apps/<slug> as its draft preview, its Agents running their drafts. It publishes once its Agents are published (a Chat App publishes only published Agents)' }
     case 'app-code':
-      return { class: 'adapted', text: `saved here with the Functions it may start, without its code: an App’s code is its own project, deployed to this runtime on its own${need.external ? '; it is hosted on its own domain, whose sign-in stays on the platform' : ''}` }
+      return { class: 'adapted', text: `saved here with the Functions it may start; its code is its own project in apps/<slug>/, which a pull brings unless --no-app-code, where \`frontera app dev\` runs it against this runtime and \`frontera app deploy\` deploys it here${need.external ? '; it is hosted on its own domain, whose sign-in stays on the platform' : ''}` }
     case 'objects-unnamed':
       return { class: 'adapted', text: `goes without ${need.count === 1 ? 'one of its object tools' : `${need.count} of its object tools`} here: the pull couldn’t read ${need.count === 1 ? 'its object definition' : 'their object definitions'} on the platform` }
     case 'context-unread':
@@ -143,6 +175,39 @@ export function judge(need: Need, ctx: Context = {}): { class: PortabilityClass;
   }
 }
 
+const listed = (paths: string[]) => (paths.length > 1 ? `${paths.slice(0, -1).join(', ')} and ${paths[paths.length - 1]}` : paths.join(''))
+
+/**
+ * Why an item won't run locally at all, as a pull's summary says it: the
+ * reason, what fixes it, and whose fix it is. Empty when it runs, even adapted.
+ */
+export interface Blocker {
+  reason: string
+  fix: string
+  /** Who makes the fix: the item's owner in the workspace, or whoever works in this project. */
+  owner: string
+}
+
+export function blockers(needs: readonly Need[]): Blocker[] {
+  return needs.flatMap((n): Blocker[] => {
+    if (n.kind === 'imports-missing') {
+      return [{
+        reason: `it imports ${listed(n.paths)}, which its source in the workspace doesn’t hold, so it can’t build here`,
+        fix: `deploy it again in the workspace from its full source with a current CLI, then pull it; or add ${n.paths.length === 1 ? 'the file' : 'the files'} here if you have the source`,
+        owner: 'whoever deploys this Function in the workspace',
+      }]
+    }
+    if (n.kind === 'action-refused') {
+      return [{
+        reason: `the local runtime refuses it as written: ${n.reasons.join(' ')}`,
+        fix: 'change the Action (or the semantic type it writes) so the values agree, in the workspace’s Blueprint, then pull it',
+        owner: 'the Blueprint’s author in the workspace',
+      }]
+    }
+    return []
+  })
+}
+
 /** The class an item gets from its needs: the most limiting one wins. */
 export function classify(needs: Need[], ctx: Context = {}): Portability {
   let cls: PortabilityClass = 'portable'
@@ -172,7 +237,7 @@ export interface ObjectTypeFit {
   leftOff: boolean
   /** It reads a Media Set's catalog: the runtime holds it over an empty Media Set of this API name. */
   mediaStub?: string | null
-  /** Calculated properties, by apiName: the runtime holds the type without them. */
+  /** Calculated properties other than a location, by apiName: the runtime holds the type without them. */
   calculated: string[]
   /** Its rows are read by markings from the platform's dataset: here it reads every row. */
   readsEveryRow: boolean
@@ -206,7 +271,8 @@ export function objectTypeFit(doc: Doc, hasLocalDataset: (dataset: string) => bo
     const set = mediaCatalogSet(doc)
     return set ? { leftOff: false, mediaStub: set, calculated: [], readsEveryRow: false } : { leftOff: true, calculated: [], readsEveryRow: false }
   }
-  const calculated = properties.filter((p) => p.calculation).map((p) => String(p.apiName ?? ''))
+  // A location (from latitude and longitude) is added by `blueprint apply`; another calculation has no route from a file.
+  const calculated = properties.filter((p) => p.calculation && (p.calculation as { kind?: unknown }).kind !== 'location').map((p) => String(p.apiName ?? ''))
   const dataset = doc.backing?.dataset
   const readsEveryRow = doc.rowAccess === 'markings' && !doc.markingsColumn && typeof dataset === 'string' && hasLocalDataset(dataset)
   return { leftOff: false, calculated, readsEveryRow }
@@ -232,8 +298,16 @@ export interface ActionFit {
   runsLocally: boolean
   /** Why not, in words. */
   reason?: string
+  /** The local runtime refuses the file as written (not merely switches it off). */
+  refused?: boolean
   /** The object type it acts on. */
   subject: string | null
+  /**
+   * The values it offers that the semantic types it writes refuse, as the
+   * workspace has them (`changed: false`): it deploys as the workspace runs it,
+   * and these are said as warnings inherited from the workspace.
+   */
+  inheritedWarnings?: string[]
 }
 
 const ONTOLOGY_EDITS = new Set(['create', 'update', 'delete'])
@@ -246,18 +320,55 @@ const ONTOLOGY_EDITS = new Set(['create', 'update', 'delete'])
  * command, or an edit with nothing to set would be bound to a connector on the
  * platform, which calls a real system: here it is published switched off.
  */
-export function actionFit(doc: Doc): ActionFit {
+export function actionFit(doc: Doc, semantic?: SemanticFacts, opts: { changed?: boolean } = {}): ActionFit {
   const subject = typeof doc.subject?.objectType === 'string' ? doc.subject.objectType : null
+  // A value the semantic type it writes refuses (`actionSemanticConflicts`). The person's own change
+  // is refused before anything else, as the platform refuses a write that adds one: the runtime holds
+  // no such Action. The workspace's Action (as pulled) deploys as the workspace runs it, with a warning.
+  const conflicts = semantic ? actionSemanticConflicts(doc, semantic) : []
+  if (conflicts.length && opts.changed) return { runsLocally: false, refused: true, reason: `the local runtime refuses it: ${conflicts.map((c) => c.message).join(' ')}`, subject }
+  const inherited = conflicts.length ? { inheritedWarnings: conflicts.map((c) => c.message) } : {}
   const effect = typeof doc.effect?.kind === 'string' ? doc.effect.kind : null
-  if (!effect || !ONTOLOGY_EDITS.has(effect)) return { runsLocally: false, reason: 'it changes a system outside the local runtime', subject }
+  if (!effect || !ONTOLOGY_EDITS.has(effect)) return { runsLocally: false, reason: 'it changes a system outside the local runtime', subject, ...inherited }
   const changes = (Array.isArray(doc.businessOutcomes) ? doc.businessOutcomes : []).flatMap((o: Doc) => (Array.isArray(o?.expectedChanges) ? o.expectedChanges : []))
   const sets = changes.some((c: Doc) => c?.kind === 'property_set' && c?.value?.kind === 'input')
-  if (effect !== 'delete' && !sets) return { runsLocally: false, reason: 'it sets no field from its inputs, so there is nothing to write locally', subject }
-  return { runsLocally: true, subject }
+  if (effect !== 'delete' && !sets) return { runsLocally: false, reason: 'it sets no field from its inputs, so there is nothing to write locally', subject, ...inherited }
+  return { runsLocally: true, subject, ...inherited }
 }
 
-export function actionNeeds(doc: Doc): Need[] {
-  return actionFit(doc).runsLocally ? [] : [{ kind: 'external-effect' }]
+/** What a pulled Action needs here: it is the workspace's as pulled, so a semantic-type conflict is inherited. */
+export function actionNeeds(doc: Doc, semantic?: SemanticFacts): Need[] {
+  const conflicts = semantic ? actionSemanticConflicts(doc, semantic) : []
+  const inherited: Need[] = conflicts.length ? [{ kind: 'action-inherited', reasons: conflicts.map((c) => c.message) }] : []
+  return [...inherited, ...(actionFit(doc).runsLocally ? [] : [{ kind: 'external-effect' } as const])]
+}
+
+// ── Functions ────────────────────────────────────────────────────────────────
+
+const CODE_FILE = /\.(ts|tsx|mts|js|mjs)$/
+const RELATIVE_SPEC = /(?:from|import)\s*\(?\s*['"](\.{1,2}\/[^'"]+)['"]/g
+const RESOLVE = ['', '.ts', '.tsx', '.mts', '.js', '.mjs', '.json', '/index.ts', '/index.js']
+
+/**
+ * The project files a Function's code imports that neither it nor any other
+ * pulled item holds, by project path without extension: what `local dev`'s
+ * bundler would fail to resolve (FUNCTION_IMPORT_MISSING). Tests are left
+ * out (a test's import fails the unit step, not the build), and so is the
+ * project's `vendor/` SDK, which every project has.
+ */
+export function missingFunctionImports(files: Record<string, string>, has: (path: string) => boolean): string[] {
+  const missing = new Set<string>()
+  for (const [path, text] of Object.entries(files)) {
+    if (!CODE_FILE.test(path) || /\.test\.[a-z]+$/.test(path) || path.endsWith('.d.ts')) continue
+    for (const m of text.matchAll(RELATIVE_SPEC)) {
+      const base = posix.normalize(posix.join(posix.dirname(path), m[1]!))
+      if (base.startsWith('vendor/') || base.split('/').includes('node_modules')) continue
+      const stem = base.replace(/\.(js|mjs)$/, '')
+      const found = base.startsWith('../') ? false : [...RESOLVE.map((e) => `${base}${e}`), ...RESOLVE.map((e) => `${stem}${e}`)].some((c) => files[c] !== undefined || has(c))
+      if (!found) missing.add(stem.replace(/\.(ts|tsx|mts)$/, ''))
+    }
+  }
+  return [...missing].sort()
 }
 
 // ── Agents and workflows ─────────────────────────────────────────────────────
@@ -330,17 +441,31 @@ export function itemNeeds(kind: string, files: Record<string, string>, connectio
 export function portabilityOf(
   kind: string,
   files: Record<string, string>,
-  opts: { connections?: ReadonlySet<string>; builtIns?: ReadonlyMap<string, BuiltInKind>; hasLocalDataset?: (dataset: string) => boolean; context?: Context } = {},
+  opts: {
+    connections?: ReadonlySet<string>
+    builtIns?: ReadonlyMap<string, BuiltInKind>
+    hasLocalDataset?: (dataset: string) => boolean
+    context?: Context
+    /** The pulled Blueprint's semantic types, shared fields and object types: an Action is checked against them. */
+    semantic?: SemanticFacts
+    /** Whether the pull (or the project) holds a file, by project path: a Function's imports are checked against it. */
+    hasFile?: (path: string) => boolean
+  } = {},
 ): Portability {
   if (kind === 'blueprint') {
     const needs = Object.entries(files).flatMap(([path, text]): Need[] => {
       const doc = parse(path, text) as Doc | null
       if (!doc || typeof doc !== 'object') return []
       if (path.startsWith('blueprint/object-types/')) return objectTypeNeeds(doc, opts.hasLocalDataset ?? (() => true))
-      if (path.startsWith('blueprint/actions/')) return actionNeeds(doc)
+      if (path.startsWith('blueprint/actions/')) return actionNeeds(doc, opts.semantic)
       return []
     })
     return classify(needs, opts.context)
   }
-  return classify(itemNeeds(kind, files, opts.connections, opts.builtIns), opts.context)
+  const needs = itemNeeds(kind, files, opts.connections, opts.builtIns)
+  if (kind === 'function') {
+    const paths = missingFunctionImports(files, opts.hasFile ?? (() => false))
+    if (paths.length) needs.unshift({ kind: 'imports-missing', paths })
+  }
+  return classify(needs, opts.context)
 }

package/src/local/local-ports.ts

@@ -1,10 +1,11 @@
 import { execFileSync } from 'node:child_process'
 import { existsSync, readFileSync } from 'node:fs'
 import { createServer } from 'node:net'
-import { join } from 'node:path'
+import { join, sep } from 'node:path'
 
 import { writeFileAtomic } from '../fs-atomic'
 import { dataDir } from '../paths'
+import { removeRuntimeResources } from './local-docker'
 
 /**
  * Sticky ports, one block per local runtime.
@@ -14,6 +15,9 @@ import { dataDir } from '../paths'
  * across restarts while two projects can run side by side. Same here: each
  * runtime claims a block of ten consecutive ports starting at 54100 and keeps
  * it, recorded in `~/.local/share/frontera/local-ports.json`.
+ *
+ * A block is freed by `frontera local remove`, and, when a new runtime needs
+ * one, for every project whose folder is gone.
  */
 
 export type PortName = 'postgres' | 'service' | 'jobs' | 'runner' | 'studio' | 'cache' | 'embeddings' | 'storage' | 'traces'
@@ -58,20 +62,108 @@ function blockFrom(start: number): PortBlock {
   }
 }
 
-/** The block this project already owns, or a fresh one nobody else has claimed. */
-export function claimPorts(projectId: string, root: string): PortBlock {
+/** A block freed because its project folder is gone. */
+export interface ReclaimedBlock {
+  /** The runtime's id: the block's key, and what its containers and volumes are named by. */
+  key: string
+  root: string
+  start: number
+}
+
+export interface PortClaim {
+  ports: PortBlock
+  /** Blocks freed to make this claim; empty when the project already had one. */
+  reclaimed: ReclaimedBlock[]
+}
+
+/**
+ * Mount points a folder can vanish under without being deleted: an external
+ * or network drive that is not mounted right now. A project under one whose
+ * mount point is missing is left alone, so unplugging a drive never deletes a
+ * runtime's data.
+ */
+function onAbsentMount(root: string): boolean {
+  const parts = root.split(sep).filter(Boolean)
+  const mountDepth = parts[0] === 'Volumes' || parts[0] === 'mnt' ? 2
+    : parts[0] === 'media' ? 3
+    : parts[0] === 'run' && parts[1] === 'media' ? 4
+    : 0
+  if (!mountDepth || parts.length < mountDepth) return false
+  return !existsSync(sep + parts.slice(0, mountDepth).join(sep))
+}
+
+/** Whether a block's project folder is gone, so the block and its runtime's data may go too. */
+function isStale(entry: { root?: unknown }): entry is { start: number; root: string } {
+  return typeof entry.root === 'string' && entry.root.length > 0 && !existsSync(entry.root) && !onAbsentMount(entry.root)
+}
+
+function removeQuietly(key: string): void {
+  try {
+    removeRuntimeResources(key)
+  } catch {
+    // Without a container runtime there is nothing of it to remove; the block is free either way.
+  }
+}
+
+/**
+ * The block this project already owns, or a fresh one nobody else has claimed.
+ *
+ * A fresh claim first frees every block whose project folder no longer
+ * exists, deleting that runtime's containers and volumes with it
+ * (`cleanup`): they are named by the block's key, and nothing can reach them
+ * once the folder is gone.
+ */
+export function claimPortBlock(
+  projectId: string,
+  root: string,
+  cleanup: (key: string) => void = removeQuietly,
+): PortClaim {
   const registry = readRegistry()
   const existing = registry.blocks[projectId]
-  if (existing) return blockFrom(existing.start)
+  if (existing) return { ports: blockFrom(existing.start), reclaimed: [] }
+  const reclaimed: ReclaimedBlock[] = []
+  for (const [key, entry] of Object.entries(registry.blocks)) {
+    if (!isStale(entry)) continue
+    delete registry.blocks[key]
+    reclaimed.push({ key, root: entry.root, start: entry.start })
+  }
+  // The registry first: a cleanup that fails part-way never leaves a block claimed by nothing.
+  const write = () => writeFileAtomic(registryPath(), `${JSON.stringify(registry, null, 2)}\n`, 0o644)
+  if (reclaimed.length) write()
+  for (const block of reclaimed) cleanup(block.key)
   const taken = new Set(Object.values(registry.blocks).map((b) => b.start))
   for (let i = 0; i < MAX_BLOCKS; i++) {
     const start = BASE + i * BLOCK
     if (taken.has(start)) continue
     registry.blocks[projectId] = { start, root }
-    writeFileAtomic(registryPath(), `${JSON.stringify(registry, null, 2)}\n`, 0o644)
-    return blockFrom(start)
+    write()
+    return { ports: blockFrom(start), reclaimed }
   }
-  throw new Error('no free local port block left; remove stale entries from ~/.local/share/frontera/local-ports.json')
+  throw new Error(
+    `no free local port block left: all ${MAX_BLOCKS} belong to projects whose folders still exist; `
+      + 'run `frontera local remove` in a project you no longer need',
+  )
+}
+
+/** `claimPortBlock`, for a caller with no one to tell what was freed. */
+export function claimPorts(projectId: string, root: string): PortBlock {
+  return claimPortBlock(projectId, root).ports
+}
+
+/** The one line that says which blocks a claim freed, or null when it freed none. */
+export function reclaimedNote(reclaimed: readonly ReclaimedBlock[]): string | null {
+  if (!reclaimed.length) return null
+  const names = reclaimed.map((b) => b.key)
+  const shown = names.length > 3 ? `${names.slice(0, 3).join(', ')} and ${names.length - 3} more` : names.join(', ')
+  return reclaimed.length === 1
+    ? `Freed the local ports of ${shown}, whose project folder ${reclaimed[0]!.root} is gone, and deleted its containers and volumes.`
+    : `Freed the local ports of ${reclaimed.length} runtimes whose project folders are gone (${shown}), and deleted their containers and volumes.`
+}
+
+/** The block a project owns, or null. */
+export function portBlockOf(projectId: string): PortBlock | null {
+  const entry = readRegistry().blocks[projectId]
+  return entry ? blockFrom(entry.start) : null
 }
 
 export function releasePorts(projectId: string): void {

package/src/local/local-project-notices.ts

@@ -0,0 +1,234 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { agentActionGapLine, agentActionGaps } from './local-agent-action-grants'
+import { agentLeanPlugins, agentLeanPluginsLine } from './local-agent-lean-plugins'
+import { emptyWorkflowLine, emptyWorkflows, workspaceWorkflows } from './local-empty-workflows'
+import { earlierPullShadows, sdkShadowLine } from './local-app-code'
+import { vendoredShadows } from './local-app-sdk'
+import { staleSampleDataLine } from './local-sample-data'
+import { sampleDatasetNames } from './local-synthetic-data'
+import { readSnapshot, type RemoteSnapshot } from './local-sync-snapshot'
+import { vendoredSdkLine, vendoredSdkState } from './local-vendored-sdk'
+
+/**
+ * What a coding agent needs to know about a project before it trusts what
+ * the local runtime shows, said by `local dev` and `local status` (and the
+ * MCP status tool) rather than left in generated files: what a pull could not
+ * bring and why, sample data an older generator made, a vendored SDK that is
+ * not this CLI's, Apps whose code stays on the platform or won't install as
+ * pulled, and Agents told to submit governed Actions their grants never offer.
+ */
+export interface ProjectNotices {
+  /** From the pull's index (`.frontera/sync/remote.json`): one line each. */
+  pull: string[]
+  /**
+   * Each pulled Agent's own notes from the pull's index (no behavior settings
+   * on the platform, a connection that stays there), one line per note with
+   * the Agents it is about. Said by `local status`, not as a warning: what
+   * came, not something to fix.
+   */
+  agentNotes?: string[]
+  /** Each App the folder describes without its code, with how to get the code. */
+  apps: string[]
+  sampleData: string | null
+  sdk: string | null
+  /** Each Agent whose instructions or procedures name governed Actions it can't submit (`agentActionGaps`), or whose Plugins aren't offered (`agentLeanPlugins`), with the fix. */
+  agents: string[]
+  /** Each workflow with no steps: it applies, but does nothing (`emptyWorkflows`). */
+  workflows: string[]
+}
+
+export function projectNotices(root: string): ProjectNotices {
+  const snap = readSnapshot(root)
+  return {
+    pull: snap ? pullNoteLines(root, snap) : [],
+    agentNotes: snap ? agentPullNoteLines(root, snap) : [],
+    apps: snap ? appCodeLines(root, snap) : [],
+    sampleData: staleSampleDataLine(root, sampleDatasetNames(root)),
+    sdk: vendoredSdkLine(vendoredSdkState(root)),
+    agents: [...agentActionGaps(root).map(agentActionGapLine), ...agentLeanPlugins(root).map(agentLeanPluginsLine)],
+    workflows: emptyWorkflows(root).map((slug, _i, all) => emptyWorkflowLine(slug, all.length ? workspaceWorkflows(root) : null)),
+  }
+}
+
+/** The notices as lines, each with what it is about first; empty when there are none. */
+export function noticeLines(n: ProjectNotices): string[] {
+  return [...n.pull, ...n.apps, ...(n.sampleData ? [n.sampleData] : []), ...(n.sdk ? [n.sdk] : []), ...n.agents, ...(n.workflows ?? [])]
+}
+
+const BEHAVIOR_UNREAD = /behavior settings couldn’t be read on the platform(?: \((.*?)\))?, so no operating\.json was pulled/
+const CONTEXT_UNREAD = /Context and data couldn’t be read on the platform: ([^.]*)/
+
+/**
+ * The pull's notes an agent has to act on or work around: Agents whose
+ * behavior settings or Context could not be read (and why), and what the
+ * whole pull left out. The rest of the index's notes describe what came, and
+ * `local dev` says it as it applies each item.
+ */
+export function pullNoteLines(root: string, snap: RemoteSnapshot): string[] {
+  const lines: string[] = []
+  const agentsHere = (ref: string) => existsSync(join(root, 'agents', ref.slice('agent/'.length), 'agent.json'))
+  const unread = new Map<string, string[]>()
+  for (const [ref, item] of Object.entries(snap.items)) {
+    if (!ref.startsWith('agent/') || !agentsHere(ref)) continue
+    for (const note of item.notes ?? []) {
+      const behavior = BEHAVIOR_UNREAD.exec(note)
+      if (behavior) {
+        const why = behavior[1] ?? 'the platform didn’t say why'
+        unread.set(why, [...(unread.get(why) ?? []), ref.slice('agent/'.length)])
+      }
+      const context = CONTEXT_UNREAD.exec(note)
+      if (context) lines.push(`${ref}: its Context and data couldn’t be read on the platform (${context[1]!.trim()}), so here it may read every object type the project holds, more than it may there`)
+    }
+  }
+  for (const [why, slugs] of unread) {
+    const own = slugs.filter((s) => existsSync(join(root, 'agents', s, 'operating.json')))
+    lines.push(
+      `${slugs.length === 1 ? `agent/${slugs[0]}: its` : `${slugs.length} Agents (${slugs.join(', ')}): their`} behavior settings weren’t pulled (${why}), so the project has no operating.json from the workspace`
+      + `${own.length ? `; ${own.map((s) => `agents/${s}/operating.json`).join(', ')} ${own.length === 1 ? 'was' : 'were'} written here and may differ from the workspace’s` : ''}`
+      + `. Nothing here can show the workspace’s settings: \`frontera local sync pull ${slugs.map((s) => `agent/${s}`).join(' ')}\` reads them again (a platform from this release on lets the project’s workspace key read them)`,
+    )
+  }
+  for (const note of snap.notes ?? []) lines.push(`the pull: ${shortList(pullNoteText(note, snap.workspace, root))}`)
+  return lines
+}
+
+/**
+ * Each pulled Agent's notes in the pull index that `pullNoteLines` doesn't
+ * already say (behavior settings or Context that couldn't be read), one
+ * line per note: "agent/vera: has no behavior settings in its snapshot on
+ * the platform (operating.json): …", or "agent/leo, agent/nova and
+ * agent/vera: each has …" when several Agents share it. Only Agents whose
+ * folder is in the project.
+ */
+export function agentPullNoteLines(root: string, snap: RemoteSnapshot): string[] {
+  const byNote = new Map<string, string[]>()
+  for (const [ref, item] of Object.entries(snap.items).sort(([a], [b]) => a.localeCompare(b))) {
+    if (!ref.startsWith('agent/') || !existsSync(join(root, 'agents', ref.slice('agent/'.length), 'agent.json'))) continue
+    for (const note of item.notes ?? []) {
+      if (BEHAVIOR_UNREAD.test(note) || CONTEXT_UNREAD.test(note)) continue
+      byNote.set(note, [...(byNote.get(note) ?? []), ref])
+    }
+  }
+  // "Has no …" reads on after the Agent's name in lower case; a name or an acronym first keeps its case.
+  const lower = (note: string) => (/^[A-Z][a-z]/.test(note) ? `${note[0]!.toLowerCase()}${note.slice(1)}` : note)
+  return [...byNote].map(([note, refs]) => {
+    // "No behavior settings on the platform", for an Agent given an operating.json here since: it no longer runs on the defaults here.
+    const own = /\boperating\.json\b/.test(note) ? refs.map((r) => `agents/${r.slice('agent/'.length)}/operating.json`).filter((f) => existsSync(join(root, f))) : []
+    const since = own.length ? `; since then ${andList(own)} ${own.length === 1 ? 'was' : 'were'} written here, so ${own.length === 1 ? 'that Agent runs' : 'those Agents run'} on ${own.length === 1 ? 'it' : 'them'} here, not on the defaults` : ''
+    return `${refs.length === 1 ? `${refs[0]}: ${lower(note)}` : `${andList(refs)}: each ${lower(note)}`}${since}`
+  })
+}
+
+/** "a, b and c". */
+const andList = (items: string[]) => (items.length < 2 ? items.join('') : `${items.slice(0, -1).join(', ')} and ${items.at(-1)}`)
+
+/** A pull index note that governed Actions stayed out, as the CLI and older CLIs wrote it. */
+const UNGRANTED = /^(\d+) governed Actions? acts? on object types (?:this|the) workspace isn’t granted, so (?:it stays|they stay) out: (.+)$/
+
+/**
+ * The Agents and Apps in the project whose files name any of these governed
+ * Actions (an Agent's instructions or procedures, an App's description), as
+ * "Agent desk" and "App ops-console": what would miss them here.
+ */
+function namedBy(root: string, actions: string[]): string[] {
+  const escape = (name: string) => name.replace(/[.*+?^$()|[\]\\{}]/g, '\\$&')
+  const pattern = new RegExp(`\\b(?:${actions.map(escape).join('|')})\\b`)
+  const named = (text: string) => !!text && pattern.test(text)
+  const read = (file: string) => {
+    try {
+      return readFileSync(file, 'utf8')
+    } catch {
+      return ''
+    }
+  }
+  const out: string[] = []
+  for (const slug of folderNames(join(root, 'agents'))) {
+    if (['agent.json', 'operating.json'].some((f) => named(read(join(root, 'agents', slug, f))))) out.push(`Agent ${slug}`)
+  }
+  for (const f of folderNames(join(root, 'apps')).filter((n) => n.endsWith('.json'))) {
+    if (named(read(join(root, 'apps', f)))) out.push(`App ${f.replace(/\.json$/, '')}`)
+  }
+  return out
+}
+
+function folderNames(dir: string): string[] {
+  try {
+    return readdirSync(dir).filter((n) => !n.startsWith('.')).sort()
+  } catch {
+    return []
+  }
+}
+
+/**
+ * A note of the pull's index, naming the workspace it means: the one the
+ * project was pulled from, which a copy linked to no workspace (or to
+ * another) can't call "this workspace". Notes from an older CLI said "this".
+ * The note that governed Actions stayed out says it plainly and with its next
+ * step: which of the project's Agents and Apps name them (read from `root`),
+ * and that a workspace admin grants the object types before a pull brings
+ * them. Its list of names stays last, for `shortList`.
+ */
+export function pullNoteText(note: string, workspace: string | null | undefined, root?: string): string {
+  const ungranted = UNGRANTED.exec(note)
+  if (ungranted) {
+    const n = Number(ungranted[1])
+    const names = ungranted[2]!.split(', ')
+    const one = n === 1
+    const where = workspace ? `this copy’s workspace (${workspace.slice(0, 8)})` : 'this copy’s workspace'
+    const users = root ? namedBy(root, names) : []
+    const who = users.length
+      ? `${andList(users)} name${users.length === 1 ? 's' : ''} ${one ? 'it' : 'some of them'} and can’t submit ${one ? 'it' : 'those'} here`
+      : `No Agent or App here names ${one ? 'it' : 'them'}`
+    return `${n} governed Action${one ? ' acts' : 's act'} on object types ${where} isn’t granted, so ${one ? 'it wasn’t' : 'they weren’t'} pulled. ${who}; to bring ${one ? 'it' : 'them'}, a workspace admin grants those object types to the workspace, then pull again. ${one ? 'It is' : 'They are'}: ${names.join(', ')}`
+  }
+  if (!workspace) return note
+  return note.replace(/\b(?:this|the) workspace(?= is(?:n’t)? granted)/g, `the workspace it was pulled from (${workspace.slice(0, 8)})`)
+}
+
+/** A note's list of names cut to the first few: "…stay out: a, b, c, d, … (75)". */
+export function shortList(note: string): string {
+  const at = note.lastIndexOf(': ')
+  if (at < 0) return note
+  const names = note.slice(at + 2).split(', ')
+  return names.length > 5 ? `${note.slice(0, at + 2)}${names.slice(0, 4).join(', ')}, … (${names.length})` : note
+}
+
+/**
+ * Each App the project describes (`apps/<slug>.json`, as a pull writes it)
+ * without its code in `apps/<slug>/` (a pull with `--no-app-code`, or one
+ * whose source the platform didn't hold): the file is what the App is and the
+ * Functions it may start. Said with the version the workspace deployed and
+ * the pull that brings that code. A pulled App whose code is here but whose
+ * package.json and bun.lock disagree is said too, with the command that
+ * settles it, before a render or a check finds it.
+ */
+export function appCodeLines(root: string, snap: RemoteSnapshot): string[] {
+  return Object.entries(snap.items).flatMap(([ref, item]) => {
+    if (!ref.startsWith('app/')) return []
+    const slug = ref.slice('app/'.length)
+    const file = join(root, 'apps', `${slug}.json`)
+    if (!existsSync(file)) return []
+    // Its code is here: said only when it won't install as it is (package.json and bun.lock disagree).
+    if (existsSync(join(root, 'apps', slug))) {
+      const shadows = vendoredShadows(join(root, 'apps', slug))
+      // An earlier pull's folder, unchanged since: the pull that brings the deployed source again is the first fix.
+      const repull = shadows.length && earlierPullShadows(root, slug).length ? { repull: ref } : {}
+      return shadows.length ? [`${ref}: ${sdkShadowLine(`apps/${slug}`, shadows, repull)}`] : []
+    }
+    let version: string | undefined
+    try {
+      const doc = JSON.parse(readFileSync(file, 'utf8')) as { version?: unknown }
+      version = typeof doc.version === 'string' && doc.version ? doc.version : undefined
+    } catch {
+      version = undefined
+    }
+    version ??= item.version?.replace(/^v/, '')
+    return [
+      version
+        ? `${ref}: apps/${slug}.json is the App’s description only; its code (version ${version}) isn’t in the project (pulled with --no-app-code or by an earlier CLI, or the platform held no source for it). \`frontera local sync pull ${ref}\` brings it into apps/${slug}/, where \`frontera local dev\` builds it like any App folder`
+        : `${ref}: apps/${slug}.json is the App’s description only, and it was never deployed in the workspace, so the platform holds no code for it: \`frontera app init\` starts one`,
+    ]
+  })
+}