@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/local/local-applied.ts

@@ -7,6 +7,7 @@ import { allTargets, describeTarget, datasetDocument, isIgnoredName, type SyncTa
 import type { LocalProject } from './local-project'
 import { standInTools } from './local-stand-ins'
 import { importedFiles } from './local-function-shared'
+import { NOT_A_DIFFERENCE_HERE } from './local-org-settings'
 
 /**
  * What `frontera local dev` has applied to this runtime, by content hash. It
@@ -127,8 +128,64 @@ export interface SolutionItem {
   name: string
   /** Path in the solution (the Blueprint is its folder). */
   path: string
-  /** `applied`: the runtime has this content; `changed`: edited since; `new`: never applied here. */
-  state: 'applied' | 'changed' | 'new'
+  /**
+   * `applied`: the runtime has this content; `changed`: edited since; `new`: never applied here;
+   * `failed`: the runtime refused this content; `partial`: it applied, but the runtime refused
+   * some of what it holds (a governed Action, a metric): `detail` names them.
+   */
+  state: 'applied' | 'changed' | 'new' | 'failed' | 'partial'
+  /** failed, partial: what the runtime refused, in words; a held item (`waiting`): what it waits for. */
+  detail?: string
+  /** failed: the error's code, when the apply gave one. */
+  code?: string
+  /** failed: what fixes it. Running `local dev` again on the same files does not. */
+  fix?: string
+  /** new or changed, but the last apply of exactly these files was held back for another item (`detail`). */
+  waiting?: boolean
+}
+
+/** What fixes a Function whose imports the pull couldn't bring: the Function's owner, or the files here. */
+export const IMPORT_MISSING_FIX = 'the pull couldn’t bring the files it imports (its source in the workspace doesn’t hold them): whoever owns the Function deploys it again from its source with a current CLI, then you pull it; or add the files here'
+
+/**
+ * What fixes a knowledge base the runtime could not read because its
+ * organization has no embedding model that runs: not its file. The model is
+ * the runtime's: a start sets one from this computer's keys (the keyless
+ * local embeddings when there is none, or the provider refuses it).
+ */
+export const EMBEDDING_MISSING_FIX = 'not its file: the runtime has no embedding model that runs. `frontera local status` says why under Setting and Embeddings; a key the provider refuses is replaced with `frontera local key-set <provider>`, and `frontera local stop` then `frontera local start` sets a model (the keyless local embeddings when no key works); the next `frontera local dev` reads it again'
+
+/**
+ * What fixes an item whose apply failed for these very files: the hint the
+ * apply gave, what a known failure needs, else fixing the file. Applying the
+ * same files again does not.
+ */
+export function failureFix(entry: Pick<BuildEntry, 'error' | 'code' | 'hint'>, file: string): string {
+  if (entry.code === 'FUNCTION_IMPORT_MISSING' || /^imports .+, which (?:isn[’']t|aren[’']t) in the project/i.test(entry.error ?? '')) return IMPORT_MISSING_FIX
+  if (/set this organization['’]s embedding model|embedding model .*is not available/i.test(entry.error ?? '')) return EMBEDDING_MISSING_FIX
+  if (entry.hint) return entry.hint
+  return `change ${file} so the runtime takes it; \`frontera local dev\` applies it once the file changes`
+}
+
+/** The code an apply's error carries (`error [FUNCTION_IMPORT_MISSING]: …`), and its first `hint:` line. */
+export function failureCodeAndHint(output: string): { code?: string; hint?: string } {
+  const code = /error \[([A-Z][A-Z0-9_]*)\]/.exec(output)?.[1]
+  const hint = /^\s*hint:\s*(.+)$/m.exec(output)?.[1]?.trim()
+  return { ...(code ? { code } : {}), ...(hint ? { hint } : {}) }
+}
+
+/**
+ * What the runtime refused inside a Blueprint that applied, by reference
+ * (`action/holdAmenityBooking`, `metric/occupancyRate`, `objectType/Photo`):
+ * each one a failure `status`, `local check` and `local dev` count alike.
+ */
+export function refusedBlueprintItems(entry: Pick<BuildEntry, 'actions' | 'parts' | 'objects'> | undefined): string[] {
+  if (!entry) return []
+  return [
+    ...Object.entries(entry.objects ?? {}).flatMap(([name, o]) => (o.refused ? [`objectType/${name}`] : [])),
+    ...Object.entries(entry.parts ?? {}).flatMap(([ref, p]) => (p.refused ? [ref] : [])),
+    ...Object.entries(entry.actions ?? {}).flatMap(([name, a]) => ((a.status === 'left-off' && a.refused) || a.status === 'failed' ? [`action/${name}`] : [])),
+  ]
 }
 
 /**
@@ -136,25 +193,35 @@ export interface SolutionItem {
  * dev` recorded after its last successful publish, against the files now. Null
  * when the project has no Blueprint.
  */
-export function blueprintApplyState(project: LocalProject, organizationId: string | null): SolutionItem['state'] | null {
+export function blueprintApplyState(project: LocalProject, organizationId: string | null): 'applied' | 'changed' | 'new' | null {
   const now = treeHash(join(project.root, 'blueprint'))
   if (!now) return null
   const was = organizationId ? loadHashes(project, organizationId).get('blueprint') : undefined
   return was === undefined ? 'new' : was === now ? 'applied' : 'changed'
 }
 
-/** Each file `local dev` applies, and whether the runtime has its current content. */
-export function solutionStatus(project: LocalProject, organizationId: string | null): SolutionItem[] {
+/** Each file `local dev` applies, and whether the runtime has its current content; `only` keeps the targets it accepts. */
+export function solutionStatus(project: LocalProject, organizationId: string | null, only?: (target: SyncTarget) => boolean): SolutionItem[] {
   const applied = organizationId ? loadHashes(project, organizationId) : new Map<string, string | null>()
-  return allTargets(project.root).map((target) => {
+  const build = loadBuild(project, organizationId)
+  return allTargets(project.root).filter((target) => !only || only(target)).map((target) => {
     const was = applied.get(target.key)
     const now = contentHash(project, target)
-    return {
+    const item: SolutionItem = {
       kind: target.kind,
       name: describeTarget(target),
       path: target.kind === 'blueprint' ? 'blueprint/' : target.file,
       state: was === undefined ? 'new' : was === now ? 'applied' : 'changed',
     }
+    // The last build is for these files: what the runtime refused is said, not "Applied".
+    const entry = build[target.key]
+    if (!entry || entry.hash !== now) return item
+    if (entry.status === 'failed') return { ...item, state: 'failed', detail: entry.error ?? 'the runtime refused it', ...(entry.code ? { code: entry.code } : {}), fix: failureFix(entry, item.path) }
+    // Held back for another item: it applies once that one does, not by running `local dev` again.
+    if (entry.status === 'blocked' && item.state !== 'applied') return { ...item, waiting: true, detail: entry.error ?? (entry.needs?.length ? `waits for ${entry.needs.join(', ')}` : 'held back') }
+    const refused = target.kind === 'blueprint' ? refusedBlueprintItems(entry) : []
+    if (refused.length && item.state === 'applied') return { ...item, state: 'partial', detail: `the runtime refused ${refused.length === 1 ? 'one item' : `${refused.length} items`} in it: ${refused.join(', ')}` }
+    return item
   })
 }
 
@@ -188,13 +255,44 @@ export interface BuildEntry {
   unnamedActions?: number
   /** failed: the runtime's error, one line. */
   error?: string
+  /** failed: the error's code (`FUNCTION_IMPORT_MISSING`), when it had one. */
+  code?: string
+  /** failed: what the apply said fixes it (its `hint:` line), when it said. */
+  hint?: string
   /** The content hash the outcome is for. */
   hash: string | null
+  /**
+   * A knowledge base: how the runtime's embeddings stood against the
+   * workspace's when it was applied (`embeddingsDiffer`; `same` when they
+   * match), which decides the threshold it searches with. Another now
+   * applies it again, unchanged files or not.
+   */
+  embeddings?: 'same' | 'workspace' | 'platform-default' | 'keyless'
+  /**
+   * A workflow: the version its file was pushed as (the push that made this
+   * entry). Tests run exactly this version, live or draft: the newest draft
+   * can be an older push once a later one was promoted.
+   */
+  version?: number
+  /**
+   * A workflow: the version the last promotion `local dev` made made live here
+   * (this push's, or an earlier one's while no later push was promoted). What an
+   * Agent's "Promoted workflow … so … can start it" says, read now.
+   */
+  live?: number
   at: string
   /** The Blueprint: each object type as the runtime holds it. */
-  objects?: Record<string, { status: 'built' | 'adapted' | 'stubbed' | 'left-off'; adaptations?: string[] }>
+  objects?: Record<string, { status: 'built' | 'adapted' | 'stubbed' | 'left-off'; adaptations?: string[]; refused?: string }>
   /** The Blueprint: each governed Action, deployed (`runs`) or not, with why. */
-  actions?: Record<string, { status: 'runs' | 'switched-off' | 'failed' | 'left-off'; reason?: string }>
+  actions?: Record<string, { status: 'runs' | 'switched-off' | 'failed' | 'left-off'; reason?: string; findings?: string[]; refused?: boolean; inherited?: string[] }>
+  /**
+   * The Blueprint: each link type, metric, semantic type and shared field left off the
+   * runtime, by its row's reference (`metric/workOrdersRaised`), with why; `refused` when
+   * the runtime refused that file itself.
+   */
+  parts?: Record<string, { reason: string; refused: boolean }>
+  /** The Blueprint: each saved object set's id on the runtime, by its file's reference (`open-work-orders`). */
+  objectSetIds?: Record<string, string>
 }
 
 interface BuildFile {
@@ -217,7 +315,9 @@ function readBuildFile(project: LocalProject, organizationId: string): Partial<B
 
 /** The settings the runtime holds differently from the workspace, as `local dev` last compared them. */
 export function loadSettingsDifferences(project: LocalProject, organizationId: string | null): string[] {
-  return (organizationId ? readBuildFile(project, organizationId)?.settings?.differences : undefined) ?? []
+  const recorded = (organizationId ? readBuildFile(project, organizationId)?.settings?.differences : undefined) ?? []
+  // A flag recorded by an older CLI that changes nothing here (`NOT_A_DIFFERENCE_HERE`) is not said.
+  return recorded.filter((d) => ![...NOT_A_DIFFERENCE_HERE].some((key) => d.startsWith(`Feature ${key} `)))
 }
 
 /** Record where the runtime's settings differ from the workspace's. Never throws. */
@@ -261,6 +361,12 @@ export function recordBuild(project: LocalProject, organizationId: string, key:
   }
 }
 
+/** The version `local dev` last pushed a workflow's file as, when the record has one. */
+export function pushedWorkflowVersion(project: LocalProject, organizationId: string | null, slug: string): number | undefined {
+  const entry = loadBuild(project, organizationId)[`workflow:${slug}`]
+  return entry && (entry.status === 'built' || entry.status === 'adapted' || entry.status === 'stubbed') && typeof entry.version === 'number' ? entry.version : undefined
+}
+
 /** Forget the outcomes of targets the project no longer has. */
 export function pruneBuild(project: LocalProject, organizationId: string, keep: ReadonlySet<string>): void {
   const items = loadBuild(project, organizationId)
@@ -335,7 +441,26 @@ export function adaptationOf(warning: string): string {
   return text.charAt(0).toUpperCase() + text.slice(1)
 }
 
-export type ItemBuildState = BuildStatus | 'not-applied'
+/**
+ * How an item stands here: its recorded build, `not-applied` when no apply
+ * is for its files as they are, and `needs-setup` for one that applied but
+ * names a secret the runtime has no value for (`Needs a value for X`): it
+ * is on the runtime, and fails when used until the value is set, so it is
+ * counted with what to fix, not with what runs adapted.
+ */
+export type ItemBuildState = BuildStatus | 'not-applied' | 'needs-setup'
+
+/** An adaptation saying the item names a secret with no value here. */
+export const NEEDS_VALUE = /^Needs a value for ([A-Z][A-Z0-9_]*)\b/
+
+/** Adapted or stubbed with a secret missing: `needs-setup`, its secrets said first. */
+export function withSetupNeeded(state: ItemBuildState, adaptations: readonly string[]): { state: ItemBuildState; reason: string | null } | null {
+  if (state !== 'adapted' && state !== 'stubbed' && state !== 'needs-setup') return null
+  const needs = adaptations.filter((a) => NEEDS_VALUE.test(a))
+  if (!needs.length) return state === 'needs-setup' ? { state: 'adapted', reason: adaptations.join('; ') || null } : null
+  const rest = adaptations.filter((a) => !NEEDS_VALUE.test(a))
+  return { state: 'needs-setup', reason: [...needs, ...rest].join('; ') }
+}
 
 export interface ItemBuild {
   state: ItemBuildState
@@ -344,10 +469,18 @@ export interface ItemBuild {
   /** The one line that says why, when there is one: "Needs workflow telco-fault-triage". */
   reason: string | null
   adaptations: string[]
+  /** failed: what fixes it (applying the same files again does not). */
+  fix?: string
+  /**
+   * Said beside its state without changing it: what the item's own files get
+   * wrong the same way on the platform (an Agent's instructions naming
+   * governed Actions its grants never offer it), each with its fix.
+   */
+  warnings?: string[]
 }
 
-const BUILD_RANK: Record<ItemBuildState, number> = { built: 0, adapted: 1, stubbed: 2, 'not-applied': 3, blocked: 4, failed: 5 }
-const BUILD_LABEL: Record<ItemBuildState, string> = { built: 'Built', adapted: 'Adapted', stubbed: 'Stubbed', 'not-applied': 'Not applied yet', blocked: 'Blocked', failed: 'Failed' }
+const BUILD_RANK: Record<ItemBuildState, number> = { built: 0, adapted: 1, stubbed: 2, 'needs-setup': 3, 'not-applied': 4, blocked: 5, failed: 6 }
+export const BUILD_LABEL: Record<ItemBuildState, string> = { built: 'Built', adapted: 'Adapted', stubbed: 'Stubbed', 'needs-setup': 'Needs setup', 'not-applied': 'Not applied yet', blocked: 'Blocked', failed: 'Failed' }
 
 function lower(text: string): string {
   return text ? text.charAt(0).toLowerCase() + text.slice(1) : text
@@ -362,7 +495,7 @@ function lower(text: string): string {
  * Blueprint".
  */
 export function buildView(project: LocalProject, organizationId: string | null): Map<string, ItemBuild> {
-  const build = loadBuild(project, organizationId)
+  const build = withCurrentPromotions(loadBuild(project, organizationId))
   const applied = organizationId ? loadHashes(project, organizationId) : new Map<string, string | null>()
   const targets = allTargets(project.root)
   const byRef = new Map<string, SyncTarget[]>()
@@ -370,12 +503,16 @@ export function buildView(project: LocalProject, organizationId: string | null):
   const hashes = new Map(targets.map((t) => [t.key, contentHash(project, t)]))
   const blueprint = build.blueprint
 
-  const stateOf = (t: SyncTarget): { state: ItemBuildState; entry?: BuildEntry } => {
+  const stateOf = (t: SyncTarget): { state: ItemBuildState; entry?: BuildEntry; changedSince?: boolean } => {
     const entry = build[t.key]
     const now = hashes.get(t.key) ?? null
     if (entry && entry.hash === now) return { state: entry.status, entry }
     // Applied before the build was recorded: it is built.
     if (!entry && now && applied.get(t.key) === now) return { state: 'built' }
+    // Failed at its last apply, and what it builds from changed since (its file, or for a Function the
+    // vendored SDK or a file beside it): still a failure until an apply says otherwise, not "not applied
+    // yet", so a refreshed SDK or a new Function next to it doesn't make the failure drop out of the count.
+    if (entry?.status === 'failed' && now) return { state: 'failed', entry, changedSince: true }
     return { state: 'not-applied' }
   }
 
@@ -392,9 +529,10 @@ export function buildView(project: LocalProject, organizationId: string | null):
     if (ref.startsWith('objectType/')) {
       const obj = blueprint?.objects?.[ref.slice('objectType/'.length)]
       // The Blueprint not built (failed, waiting, or never applied) holds every object type back.
-      if (blueprint && blueprint.status !== 'built' && blueprint.status !== 'adapted') return `${words}: the Blueprint ${blueprint.status === 'failed' ? 'didn’t build' : 'isn’t built yet'}`
+      if (blueprint && blueprint.status !== 'built' && blueprint.status !== 'adapted' && blueprint.status !== 'stubbed') return `${words}: the Blueprint ${blueprint.status === 'failed' ? 'didn’t build' : 'isn’t built yet'}`
       if (!blueprint && existsSync(join(project.root, 'blueprint'))) return `${words}: the Blueprint isn’t built yet`
       if (!obj) return `${words}, which isn’t in the project’s Blueprint`
+      if (obj.refused) return `${words}, which the local runtime refused: ${obj.refused}`
       return obj.status === 'left-off' ? `${words}, which the local runtime leaves off` : words
     }
     const held = byRef.get(ref)
@@ -411,6 +549,8 @@ export function buildView(project: LocalProject, organizationId: string | null):
     if (entry.status === 'blocked') {
       const needs = entry.needs ?? []
       if (!needs.length) {
+        // Held back for its own reason (the apply watchdog): its words, not a missing dependency.
+        if (entry.error) return entry.error
         const n = entry.unnamedActions ?? 0
         return `Runs ${n === 1 ? 'a governed Action' : `${n} governed Actions`} named only by the platform’s id: add an organization key and pull it again`
       }
@@ -425,30 +565,79 @@ export function buildView(project: LocalProject, organizationId: string | null):
     const found = stateOf(t)
     const { entry } = found
     // Adapted only by what the runtime is missing (no runner has polled yet): it is built as its files say, with a note.
-    const state = found.state === 'adapted' && entry?.adaptations?.length && entry.adaptations.every(isEnvironmentNote) ? 'built' : found.state
-    const reason = entry ? reasonOf(entry, 0) || null : null
-    out.set(t.key, { state, label: BUILD_LABEL[state], reason, adaptations: state === 'adapted' || state === 'stubbed' ? (entry?.adaptations ?? []) : [] })
+    const environmentOnly = found.state === 'adapted' && !!entry?.adaptations?.length && entry.adaptations.every(isEnvironmentNote)
+    // A secret with no value here: it applied, and fails when used until the value is set.
+    const setup = environmentOnly ? null : withSetupNeeded(found.state, entry?.adaptations ?? [])
+    const state: ItemBuildState = environmentOnly ? 'built' : (setup?.state ?? found.state)
+    // "No runner has polled for 229s" was the poll's age when it applied, not the runner now: not repeated as
+    // the item's reason (a restored database brings back an old poll time). "Never polled" still is.
+    const own = environmentOnly ? entry!.adaptations!.filter((a) => !isPollAgeNote(a)).join('; ') || null : setup ? setup.reason : entry ? reasonOf(entry, 0) || null : null
+    const reason = found.changedSince ? `${own ?? 'The runtime refused it'} (at its last apply; its files changed since, and \`frontera local dev\` applies it again)` : own
+    out.set(t.key, { state, label: BUILD_LABEL[state], reason, adaptations: state === 'adapted' || state === 'stubbed' || state === 'needs-setup' ? (entry?.adaptations ?? []) : [], ...(state === 'failed' && entry ? { fix: failureFix(entry, t.kind === 'blueprint' ? 'blueprint/' : t.file) } : {}) })
   }
   return out
 }
 
+/** "Promoted workflow intake v2 so desk can start it": the adaptation an Agent's tools record when its binding promoted a workflow. */
+const PROMOTED = /^Promoted workflow (\S+) v(\d+) so (.+) can start it$/
+
+/** `promoted workflow intake v3…` in an apply's output → 3, for that workflow. */
+export function promotedVersionOf(output: string, slug: string): number | undefined {
+  const escaped = slug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const all = [...output.matchAll(new RegExp(`promoted workflow ${escaped} v(\\d+)\\b`, 'gi'))]
+  return all.length ? Number(all[all.length - 1]![1]) : undefined
+}
+
+/**
+ * Each "Promoted workflow X vN so Y can start it" with the version live now:
+ * the latest promotion `local dev` recorded for X (its push's, `live`), not the
+ * one the Agent's binding made when it was applied. A record from before `live`
+ * was kept reads the workflow's pushed version, when it was pushed after the
+ * binding: once a binding promoted it, every later push is promoted too.
+ */
+export function withCurrentPromotions(build: Record<string, BuildEntry>): Record<string, BuildEntry> {
+  const now = (text: string, at: string): string => {
+    const m = PROMOTED.exec(text)
+    if (!m) return text
+    const workflow = build[`workflow:${m[1]}`]
+    const recorded = workflow?.live ?? (workflow?.version !== undefined && workflow.at > at ? workflow.version : undefined)
+    const latest = Math.max(Number(m[2]), recorded ?? 0)
+    return latest === Number(m[2]) ? text : `Promoted workflow ${m[1]} v${latest} so ${m[3]} can start it`
+  }
+  let changed = false
+  const out: Record<string, BuildEntry> = {}
+  for (const [key, entry] of Object.entries(build)) {
+    const adaptations = entry.adaptations?.map((a) => now(a, entry.at))
+    if (adaptations && adaptations.some((a, i) => a !== entry.adaptations![i])) {
+      changed = true
+      out[key] = { ...entry, adaptations }
+    } else out[key] = entry
+  }
+  return changed ? out : build
+}
+
 /** A warning about the runtime rather than the item: it says nothing about how the item runs differently here. */
 export function isEnvironmentNote(text: string): boolean {
   return /no automation runner has (ever )?polled/i.test(text)
 }
 
+/** The deploy's "no automation runner has polled for 229s": how old the last poll was at that moment. */
+export function isPollAgeNote(text: string): boolean {
+  return /no automation runner has polled for \d+\s?s\b/i.test(text)
+}
+
 /** Several targets as one item (an Agent: its file, its behavior settings and its tools): the worst one speaks. */
 export function combineBuilds(builds: Array<ItemBuild | undefined>): ItemBuild {
   const present = builds.filter((b): b is ItemBuild => !!b)
   if (!present.length) return { state: 'not-applied', label: BUILD_LABEL['not-applied'], reason: null, adaptations: [] }
   const worst = [...present].sort((a, b) => BUILD_RANK[b.state] - BUILD_RANK[a.state])[0]!
   const adaptations = [...new Set(present.flatMap((b) => b.adaptations))]
-  return { ...worst, adaptations, reason: worst.reason ?? (worst.state === 'adapted' || worst.state === 'stubbed' ? adaptations.join('; ') || null : null) }
+  return { ...worst, adaptations, reason: worst.reason ?? (worst.state === 'adapted' || worst.state === 'stubbed' || worst.state === 'needs-setup' ? adaptations.join('; ') || null : null) }
 }
 
 /** How many items the home lists are in each state, for "49 built · 2 adapted · 3 blocked". */
 export function buildCounts(states: ItemBuildState[]): Record<ItemBuildState, number> {
-  const counts: Record<ItemBuildState, number> = { built: 0, adapted: 0, stubbed: 0, 'not-applied': 0, blocked: 0, failed: 0 }
+  const counts: Record<ItemBuildState, number> = { built: 0, adapted: 0, stubbed: 0, 'needs-setup': 0, 'not-applied': 0, blocked: 0, failed: 0 }
   for (const s of states) counts[s] += 1
   return counts
 }
@@ -459,6 +648,7 @@ export function buildSummaryLine(counts: Record<ItemBuildState, number>): string
     counts.built ? `${counts.built} built` : '',
     counts.adapted ? `${counts.adapted} adapted` : '',
     counts.stubbed ? `${counts.stubbed} stubbed` : '',
+    counts['needs-setup'] ? `${counts['needs-setup']} need${counts['needs-setup'] === 1 ? 's' : ''} setup` : '',
     counts.blocked ? `${counts.blocked} blocked` : '',
     counts.failed ? `${counts.failed} failed` : '',
     counts['not-applied'] ? `${counts['not-applied']} not applied yet` : '',

package/src/local/local-apply-history.ts

@@ -0,0 +1,84 @@
+import { readFileSync } from 'node:fs'
+import { join, sep } from 'node:path'
+
+import { writeFileAtomic } from '../fs-atomic'
+import type { LocalProject } from './local-project'
+
+/**
+ * Each apply `local dev` ran, newest last: when it started and finished,
+ * what started it and what came of it. Forge's Activity lists each as its
+ * own event, so an apply nine minutes after the first says when it ran and
+ * why ("files changed: agents/desk/agent.json") instead of reusing the
+ * first one's time. A round that found nothing changed is not an apply and
+ * is not kept.
+ */
+
+export interface ApplyRecord {
+  /** When its first item started applying. */
+  since: string
+  finished: string
+  /** What started it: "runtime started", "files changed: …", "the runtime is answering again". */
+  trigger: string
+  /** Items it applied, and items that failed, in this round only. */
+  applied: number
+  failed: number
+}
+
+/** How many applies are kept: Activity shows the recent ones. */
+const KEEP = 30
+
+function historyPath(stateDir: string): string {
+  return join(stateDir, 'applies.json')
+}
+
+/** The applies kept, oldest first; none when the file is missing or unreadable. */
+export function readApplies(stateDir: string): ApplyRecord[] {
+  try {
+    const list = JSON.parse(readFileSync(historyPath(stateDir), 'utf8')) as unknown
+    return Array.isArray(list) ? list.filter((r): r is ApplyRecord => !!r && typeof (r as ApplyRecord).since === 'string' && typeof (r as ApplyRecord).trigger === 'string') : []
+  } catch {
+    return []
+  }
+}
+
+/** Keep one finished apply. Never throws: a missed record must never fail an apply. */
+export function recordApply(project: LocalProject, record: ApplyRecord): void {
+  try {
+    const list = [...readApplies(project.stateDir), record].slice(-KEEP)
+    writeFileAtomic(historyPath(project.stateDir), `${JSON.stringify(list, null, 2)}\n`, 0o644)
+  } catch {
+    // The apply itself is what matters.
+  }
+}
+
+/** "files changed: agents/desk/agent.json and workflows/intake.yaml", or "… and 4 more". */
+export function filesChangedTrigger(paths: Iterable<string>): string {
+  const list = [...new Set([...paths].map((p) => p.split(sep).join('/')))].sort()
+  if (!list.length) return 'files changed'
+  const shown = list.slice(0, 2)
+  const rest = list.length - shown.length
+  return `files changed: ${rest > 0 ? `${shown.join(', ')} and ${rest} more` : shown.join(' and ')}`
+}
+
+/**
+ * Folders whose files never change what the runtime runs: the CLI's and
+ * Forge's own state (`.frontera/`, screenshots under `.frontera/evidence/`
+ * included), the coding agents' settings (`.claude/`, `.codex/`, `.cursor/`,
+ * `.agents/`), Git, packages, and the project's notes (`docs/`). A change
+ * under one is never a reason to apply, so the watcher doesn't even wake up.
+ */
+const NEVER_APPLIED = new Set(['.frontera', '.claude', '.codex', '.cursor', '.agents', '.git', 'node_modules', 'docs', 'dist', 'fixtures'])
+
+/**
+ * Whether a changed path (relative to the project root) can change what the
+ * runtime runs: not under a folder above, not a hidden file or folder, and
+ * not a root file the runtime never reads (README.md, AGENTS.md, .mcp.json).
+ * `library.json` is the one root file that applies.
+ */
+export function canChangeRuntime(rel: string): boolean {
+  const parts = rel.split(sep).flatMap((p) => p.split('/')).filter(Boolean)
+  if (!parts.length) return false
+  if (parts.some((p) => NEVER_APPLIED.has(p) || p.startsWith('.'))) return false
+  if (parts.length === 1) return parts[0] === 'library.json' || !/\.\w+$/.test(parts[0]!)
+  return true
+}

package/src/local/local-apply-summary.ts

@@ -0,0 +1,86 @@
+import { normalize } from 'node:path'
+
+import { refusedBlueprintItems, type BuildEntry } from './local-applied'
+import { lockRefOf, type Unchanged } from './local-check-inherited'
+import { RUNTIME_DOWN_ERROR } from './local-runtime-health'
+
+/** One item that did not apply, for `local dev --once --json`: the item and why. */
+export interface ApplyFailure {
+  item: string
+  error: string
+  /** The item as `local status` names it (`function/staff-availability`, `action/holdBooking`), when known. */
+  ref?: string
+  /** The project file that was applied, when the failure is a target's. */
+  file?: string
+}
+
+/**
+ * What `local dev --once` fails with, or null when everything applied: each
+ * target that failed, and each item the runtime refused inside a Blueprint
+ * that applied (a governed Action, a metric, a link type). Those are the
+ * failures `local status` and `local check` count, so the three say one
+ * number. `blueprint` is the Blueprint's build entry for the files as they
+ * are now; a Blueprint that failed as a whole is one failure, not its parts.
+ */
+export function applyFailures(failing: ReadonlyMap<string, ApplyFailure>, targetCount: number, blueprint: BuildEntry | undefined, refOf?: (key: string) => { ref: string; file?: string } | undefined): { message: string; failed: ApplyFailure[] } | null {
+  const refused = failing.has('blueprint') || !blueprint ? [] : refusedBlueprintItems(blueprint)
+  const named = (key: string, f: ApplyFailure): ApplyFailure => {
+    const at = refOf?.(key)
+    return at ? { ...f, ref: at.ref, ...(at.file ? { file: at.file } : {}) } : f
+  }
+  const failed = [...[...failing].map(([key, f]) => named(key, f)), ...refused.map((ref) => ({ item: ref, error: refusedReason(blueprint!, ref), ...(refOf ? { ref } : {}) }))]
+  if (!failed.length) return null
+  const message = refused.length
+    ? `${failed.length} item${failed.length === 1 ? '' : 's'} didn’t apply: ${failing.size ? `${failing.size} of ${targetCount} failed, and ` : ''}the runtime refused ${refused.length} in the Blueprint (${refused.join(', ')})`
+    : `${failing.size} of ${targetCount} failed to apply`
+  return { message, failed }
+}
+
+function refusedReason(entry: BuildEntry, ref: string): string {
+  const [kind, name] = [ref.slice(0, ref.indexOf('/')), ref.slice(ref.indexOf('/') + 1)]
+  const why = kind === 'action' ? entry.actions?.[name]?.reason : kind === 'objectType' ? entry.objects?.[name]?.refused : entry.parts?.[ref]?.reason
+  return (why ?? 'the local runtime refused it').replace(/^(?!the local runtime refused it)/, 'the local runtime refused it: ')
+}
+
+/**
+ * The failures of an apply, split as `local check` splits them: inherited
+ * when the item is still byte for byte what the last pull wrote (its
+ * `frontera.lock` entry), and so is the file that was applied, so the change
+ * did not make it; made otherwise (an item changed or added here, a file
+ * added to a pulled item, the Blueprint as a whole, a failure with no `ref`). A failure that is the runtime's (it stopped answering, an item
+ * re-applied in a loop) is never inherited: it is not the workspace's.
+ * `strict` counts every failure as made.
+ */
+export function splitApplyFailures(failed: readonly ApplyFailure[], unchanged: Unchanged, opts: { strict?: boolean } = {}): { made: ApplyFailure[]; inherited: ApplyFailure[] } {
+  const made: ApplyFailure[] = []
+  const inherited: ApplyFailure[] = []
+  for (const f of failed) {
+    const runtimes = f.error === RUNTIME_DOWN_ERROR || /applied \d+ times with no change to its files/.test(f.error)
+    const asPulled = !!f.ref && unchanged.refs.has(lockRefOf(f.ref)) && (!f.file || unchanged.files.has(normalize(f.file)))
+    if (!opts.strict && !runtimes && asPulled) inherited.push(f)
+    else made.push(f)
+  }
+  return { made, inherited }
+}
+
+/** The one line an apply whose every failure is inherited ends with. */
+export function inheritedApplyLine(count: number): string {
+  return `${count} inherited failure${count === 1 ? '' : 's'} in items unchanged since the pull: they fail as they do in the workspace, and nothing changed or added here failed (\`frontera local check --strict\` fails on them)`
+}
+
+/**
+ * The items `local dev --once --json` listed as inherited failures, by
+ * reference: from its result when it exited 0, or from its error's details
+ * when something changed or added failed too. Empty when it listed none.
+ */
+export function inheritedRefsOf(data: unknown): Set<string> {
+  const record = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
+  const from = record(data) ? (Array.isArray(data.inheritedFailures) ? data.inheritedFailures : record(data.details) && Array.isArray(data.details.inheritedFailures) ? data.details.inheritedFailures : []) : []
+  return new Set(from.flatMap((f) => (record(f) && typeof f.ref === 'string' ? [f.ref] : [])))
+}
+
+/** What one apply came to, in a line, for a caller that reads `ok` (the MCP `apply`). */
+export function applySummaryLine(ok: boolean, made: number, inherited: number): string {
+  if (!ok) return made ? `${made} item${made === 1 ? '' : 's'} changed or added here didn’t apply${inherited ? `, and ${inheritedApplyLine(inherited).replace(/: they fail.*$/, '')}` : ''}` : 'the apply failed: see log'
+  return inherited ? `Everything changed or added here applied; ${inheritedApplyLine(inherited)}` : 'Everything applied'
+}

package/src/local/local-apply-watchdog.ts

@@ -0,0 +1,95 @@
+/**
+ * A guard on `local dev` re-applying an item whose files did not change.
+ *
+ * An unchanged item is applied again only for a reason that settles after one
+ * apply: its draft was published, a governed Action it deploys isn't running,
+ * a dataset it reads got a new revision, an Action it names was authored
+ * again. A reason that never settles is a bug, and it re-applies the item
+ * forever (a refused Action did, every few seconds, until b57501e3c). So an
+ * item applied `limit` times with the same content hash, no file event for
+ * it, within one drain or with less than `gapMs` between the applies, is not
+ * applied again until its files change.
+ *
+ * Only applies that succeeded count. A failed item is retried only after
+ * something else applied, so failures are bounded by the successes this
+ * guards; counting them would stop an item that is waiting, legitimately, for
+ * a slow dependency.
+ */
+
+export const REAPPLY_LIMIT = 3
+/** The longest gap between two applies that still counts them as one run of re-applies. */
+export const REAPPLY_GAP_MS = 20_000
+
+interface Streak {
+  hash: string | null
+  /** Successful applies of this content since the streak began. */
+  applied: number
+  lastAt: number
+  drain: number
+}
+
+export type WatchdogVerdict = 'apply' | 'stop' | 'stopped'
+
+export class ApplyWatchdog {
+  private readonly streaks = new Map<string, Streak>()
+  /** Items stopped, by the content hash they were stopped at. */
+  private readonly stopped = new Map<string, string | null>()
+  private readonly touched = new Set<string>()
+
+  constructor(
+    private readonly limit = REAPPLY_LIMIT,
+    private readonly gapMs = REAPPLY_GAP_MS,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  /** A file event for the item: whatever it re-applied before starts over. */
+  fileEvent(key: string): void {
+    this.touched.add(key)
+    this.stopped.delete(key)
+  }
+
+  /**
+   * Before applying `key` at `hash` in drain number `drain`: `apply` to go
+   * ahead, `stop` the first time it is held back (say it), `stopped` after.
+   */
+  before(key: string, hash: string | null, drain: number): WatchdogVerdict {
+    const at = this.now()
+    if (this.stopped.has(key)) {
+      if (this.stopped.get(key) === hash) return 'stopped'
+      this.stopped.delete(key)
+    }
+    const fresh = this.touched.delete(key)
+    let streak = this.streaks.get(key)
+    if (!streak || fresh || streak.hash !== hash || (streak.drain !== drain && at - streak.lastAt > this.gapMs)) {
+      streak = { hash, applied: 0, lastAt: at, drain }
+      this.streaks.set(key, streak)
+    }
+    if (streak.applied >= this.limit) {
+      this.stopped.set(key, hash)
+      this.streaks.delete(key)
+      return 'stop'
+    }
+    streak.lastAt = at
+    streak.drain = drain
+    return 'apply'
+  }
+
+  /** After the apply `before` let through. */
+  after(key: string, ok: boolean): void {
+    const streak = this.streaks.get(key)
+    if (!streak) return
+    if (ok) streak.applied += 1
+    streak.lastAt = this.now()
+  }
+
+  /** How many times an item was applied before it was stopped: for the line that says so. */
+  get applyLimit(): number {
+    return this.limit
+  }
+}
+
+/** The line `local dev` says, and records, when it stops re-applying an item. */
+export function stoppedReapplyingLine(what: string, times: number): string {
+  const name = what.charAt(0).toUpperCase() + what.slice(1)
+  return `${name} applied ${times} times with no change to its files: stopped re-applying it; this is a bug, please report it with \`frontera local logs\``
+}