@frontera-sdk/cli 1.52.28 → 1.52.29

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

@@ -0,0 +1,986 @@
+import { createHash } from 'node:crypto'
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, posix } from 'node:path'
+
+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 { 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'
+import { importedFiles } from './local-function-shared'
+import { isIgnoredName } from './local-dev-sync'
+import { comparableText, withoutSecrets } from './local-secrets'
+import { deepEqual } from './local-sync-merge'
+import { itemTitle } from './local-sync-names'
+import { hash, itemHash, readLocal, safePath, writeLock, type LockEntry, type PlanItem, type RemoteItem, type SyncKind, type SyncLock } from './local-sync-plan'
+import { dropBase, SYNC_DIR, writeBase, type RemoteSnapshot } from './local-sync-snapshot'
+
+/**
+ * Change requests v1, the project's side (docs/specs/2026-10-17-change-requests-v1-design.md
+ * §4, §7, §11): what a push proposes, the request it keeps, and what Apply
+ * did, in words.
+ *
+ *   what is pushed     items changed here (a merge or a resolve leaves them so) and items only here
+ *   what is refused    an item the workspace changed too (pull and merge first), one with conflicts,
+ *                      a deletion, and kinds a request does not carry (plugins, evaluations, datasets)
+ *   each item          the lock's id, the revision its base is (the Blueprint's for a Blueprint file),
+ *                      every file of the item, and for a Function its `function deploy` build
+ *   the request        `.frontera/sync/requests.json` (not committed): the current one, so the next
+ *                      push updates it, and a copy of each item's base for the Changes view
+ *
+ * Pure but for the project's files: the platform calls and the build are the
+ * command's (`commands/local/sync-request.ts`).
+ */
+
+/** The kinds a change request carries. */
+export const PUSH_KINDS: readonly SyncKind[] = ['blueprint', 'skill', 'knowledge', 'plugin', 'function', 'workflow', 'agent', 'evaluation', 'chat-app', 'lessons']
+
+/** Why the other kinds are not proposed, in the reader's words. */
+export const NOT_PROPOSED: Partial<Record<SyncKind, string>> = {
+  dataset: 'Datasets aren’t proposed; upload them on the platform',
+  brand: 'The organization’s brand is set on the platform, in Settings; it isn’t proposed from a project',
+  library: 'Library installations are made from the library on the platform; this file only records them',
+  app: 'An App’s code ships with its own project, and the Functions it may start are set on the platform',
+}
+
+/** Kinds the platform cannot delete, and what to do instead. */
+const NOT_DELETED: Partial<Record<SyncKind, string>> = {
+  function: 'A Function can’t be deleted in a workspace: switch it off on the platform, or keep its file',
+  lessons: 'An Agent’s rules are retired on the platform, where they are reviewed: a change request only proposes new ones',
+}
+
+/** Why an item cannot be proposed now. */
+export type BlockCode = 'moved' | 'conflicts' | 'deleted' | 'workspace-deleted' | 'kind' | 'shape'
+
+/** A skill's file that is not text (an image, a font, a template): uploaded as a skill asset when proposed. */
+export interface PushAsset {
+  /** Relative to the skill's folder, as the platform keeps it: `assets/logo.png`. */
+  path: string
+  /** Project path. */
+  file: string
+  sha256: string
+  bytes: number
+  mime: string
+  visible: boolean
+  change: 'new' | 'changed' | 'same'
+}
+
+/** What the project brings of a knowledge base's documents. */
+export interface PushDocuments {
+  upload: Array<{ fileName: string; sha256: string; bytes: number; mime: string; replaces: string | null; change: 'new' | 'changed' }>
+  remove: Array<{ fileName: string; sourceId: string }>
+}
+
+export interface PushFile {
+  path: string
+  /** The file as the item's base has it; null when the base does not have it (or the item is new). */
+  base: string | null
+  /** The file here; null when it was removed here. */
+  local: string | null
+}
+
+export interface PushItem {
+  ref: string
+  kind: SyncKind
+  name: string
+  title: string
+  /** `changed`: the workspace has it and it changed here. `new`: only here. `deleted`: deleted here, so Apply deletes it there. */
+  change: 'changed' | 'new' | 'deleted'
+  proposable: boolean
+  /** Why not, when it is not. */
+  blocked: BlockCode | null
+  reason: string | null
+  /** The platform's id, from the lock (or the snapshot). */
+  id: string | null
+  /** The revision the item was changed from; for a Blueprint file, the Blueprint's. */
+  baseRevision: string | null
+  /** Every file of the item as it stands here: what is sent. */
+  files: Record<string, string>
+  /** Each file that differs from the base, for the preview and the Changes view. */
+  diff: PushFile[]
+  /** The base's files, whole: kept with the request for its Changes view. */
+  base: Record<string, string>
+  /** What is left out, said rather than dropped (a secret's value, a knowledge base's documents). */
+  notes: string[]
+  /** A skill's assets, the whole set, when it has any here or in the workspace. */
+  assets?: PushAsset[]
+  /** A knowledge base's documents, when they are brought. */
+  documents?: PushDocuments
+}
+
+const BLUEPRINT_DIRS = ['semantic-types', 'shared-fields', 'object-types', 'link-types', 'metrics', 'actions'] as const
+
+const BLUEPRINT_WORD: Record<string, string> = {
+  'semantic-types': 'semantic type',
+  'shared-fields': 'shared field',
+  'object-types': 'object type',
+  'link-types': 'link type',
+  metrics: 'metric',
+  actions: 'Action',
+}
+
+const SKIP_DIRS = new Set(['node_modules', '.frontera', '.git', 'dist', 'build', 'coverage'])
+
+/** Files under a folder, project-relative, skipping hidden files, editor leftovers and the workspace's conflict copies. */
+function filesUnder(root: string, rel: string, depth = 0): string[] {
+  const dir = join(root, rel)
+  if (depth > 8 || !existsSync(dir)) return []
+  let names: string[]
+  try {
+    names = readdirSync(dir).sort()
+  } catch {
+    return []
+  }
+  const out: string[] = []
+  for (const name of names) {
+    if (SKIP_DIRS.has(name) || isIgnoredName(name)) continue
+    const path = posix.join(rel, name)
+    let stat
+    try {
+      stat = lstatSync(join(root, path))
+    } catch {
+      continue
+    }
+    if (stat.isDirectory()) out.push(...filesUnder(root, path, depth + 1))
+    else if (stat.isFile()) out.push(path)
+  }
+  return out
+}
+
+/** The relative imports a Function file makes inside `functions/`, followed through its helpers. */
+/** A Function's file and what it imports: its helpers in `functions/`, and the shared files it imports from outside it. */
+function functionImports(root: string, entry: string): string[] {
+  return importedFiles(root, entry)
+}
+
+/**
+ * Every file of one item as the project holds it, in the layout a pull
+ * writes and a request carries (`change-request-candidates.ts` on the
+ * service). The lock's paths that still exist come along, so nothing the
+ * last pull wrote is left behind.
+ */
+export function itemFiles(root: string, kind: SyncKind, name: string, entry?: LockEntry, opts: { documents?: boolean } = {}): { files: Record<string, string>; notes: string[]; problem?: string; assets?: string[] } {
+  const notes: string[] = []
+  let paths: string[] = []
+  const assets: string[] = []
+  switch (kind) {
+    case 'agent':
+      paths = ['agent.json', 'operating.json', 'bindings.json'].map((f) => `agents/${name}/${f}`)
+      break
+    case 'workflow': {
+      paths = [`workflows/${name}.yaml`, `workflows/${name}.yml`]
+      if (!paths.some((p) => readLocal(root, p) !== null)) {
+        const other = [`workflows/${name}.json`, `workflows/${name}.workflow.yaml`, `workflows/${name}.workflow.yml`].find((p) => readLocal(root, p) !== null)
+        if (other) return { files: {}, notes, problem: `${other}: a change request carries a workflow as workflows/${name}.yaml; rename the file to propose it` }
+      }
+      break
+    }
+    case 'function': {
+      if (existsSync(join(root, 'functions', name, 'package.json'))) paths = filesUnder(root, `functions/${name}`)
+      else {
+        const entryFile = `functions/${name}.ts`
+        paths = [...functionImports(root, entryFile), `functions/${name}.test.ts`]
+      }
+      break
+    }
+    case 'skill': {
+      for (const path of filesUnder(root, `skills/${name}`)) {
+        const rel = path.slice(`skills/${name}/`.length)
+        const top = rel.split('/')[0]
+        if (rel === 'SKILL.md' || top === 'refs' || top === 'references' || top === 'scripts' || rel.endsWith('.md')) paths.push(path)
+        else if (!path.endsWith('.workspace')) assets.push(path)
+      }
+      break
+    }
+    case 'plugin':
+      paths = [`mcp/${name}.plugin.json`]
+      break
+    case 'chat-app':
+      paths = [`chat-apps/${name}.json`]
+      break
+    case 'lessons':
+      paths = [lessonsPath(name)]
+      break
+    case 'evaluation': {
+      const [agent, dataset] = name.split('.')
+      paths = [`agents/${agent}/evals/${dataset}.yaml`, `agents/${agent}/evals/${dataset}.yml`]
+      break
+    }
+    case 'knowledge': {
+      // Its settings and its quality checks; documents only when brought.
+      paths = [`knowledge/${name}/knowledge.json`, qualityChecksPath(name)]
+      const documents = filesUnder(root, `knowledge/${name}`).filter((p) => !paths.includes(p))
+      if (documents.length && !opts.documents) notes.push(`Its ${documents.length} document${documents.length === 1 ? '' : 's'} stay${documents.length === 1 ? 's' : ''} as the workspace has them unless you bring them; the request carries the knowledge base’s settings`)
+      break
+    }
+    case 'blueprint':
+      paths = [`blueprint/${name}.yaml`, `blueprint/${name}.yml`, `blueprint/${name}.json`]
+      break
+    default:
+      return { files: {}, notes }
+  }
+  // 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()) {
+    if (path.endsWith('.workspace') || assets.includes(path)) continue
+    const text = readLocal(root, path)
+    if (text === null) continue
+    if (kind === 'plugin') {
+      const clean = withoutSecrets(text)
+      files[path] = clean.text
+      notes.push(...clean.notes)
+    } else files[path] = text
+  }
+  return { files, notes, ...(kind === 'skill' ? { assets } : {}) }
+}
+
+/**
+ * The items the project holds, by ref, as a request names them: Agents,
+ * workflows, Functions (a file or a folder of their own), skills, knowledge
+ * bases, Blueprint files, and plugins (listed so a push can say why not).
+ */
+export function projectRefs(root: string): Map<string, { kind: SyncKind; name: string }> {
+  const out = new Map<string, { kind: SyncKind; name: string }>()
+  const add = (kind: SyncKind, name: string) => out.set(`${kind}/${name}`, { kind, name })
+  const dirs = (rel: string) => {
+    try {
+      return readdirSync(join(root, rel)).filter((n) => !isIgnoredName(n) && !SKIP_DIRS.has(n)).sort()
+    } catch {
+      return []
+    }
+  }
+  for (const slug of dirs('agents')) if (existsSync(join(root, 'agents', slug, 'agent.json'))) add('agent', slug)
+  for (const f of dirs('workflows')) {
+    const m = /^(.+?)(?:\.workflow)?\.(ya?ml|json)$/.exec(f)
+    if (m) add('workflow', m[1]!)
+  }
+  for (const f of dirs('functions')) {
+    if (/\.ts$/.test(f) && !/\.(test|d)\.ts$/.test(f)) add('function', f.replace(/\.ts$/, ''))
+    else if (existsSync(join(root, 'functions', f, 'package.json'))) add('function', f)
+  }
+  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)$/, '')}`)
+  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)
+  for (const slug of dirs('agents')) {
+    for (const f of dirs(`agents/${slug}/evals`)) {
+      const m = /^([^.]+)\.ya?ml$/.exec(f)
+      if (m) add('evaluation', `${slug}.${m[1]}`)
+    }
+  }
+  return out
+}
+
+/** An item's name as people know it, as every surface says it (`local-sync-names.ts`). */
+function titleFor(kind: SyncKind, name: string, files: Record<string, string>, known?: string): string {
+  return itemTitle(kind, name, files, known)
+}
+
+export interface CandidateInput {
+  root: string
+  plan: PlanItem[]
+  lock: SyncLock | null
+  snapshot: RemoteSnapshot | null
+  /** The snapshot's items with their files: what the workspace holds as last fetched. */
+  remote: RemoteItem[]
+  /**
+   * Knowledge bases whose documents are brought (opt-in, as for a pull):
+   * what the pull wrote of each (`documents.json`) and what the workspace has now.
+   */
+  documents?: {
+    names: Set<string>
+    pulled: Record<string, Record<string, PulledDocument>>
+    platform: Map<string, Array<{ id: string; fileName: string }>>
+  }
+}
+
+const BLOCK_REASON: Record<Exclude<BlockCode, 'kind' | 'shape'>, string> = {
+  moved: 'Changed in the workspace too since your last pull: pull and merge it first',
+  conflicts: 'Has conflicts from a pull: resolve them first',
+  deleted: 'Deleted here',
+  'workspace-deleted': 'The workspace deleted it: decide in a pull whether to keep it here',
+}
+
+const sha256 = (bytes: Uint8Array) => createHash('sha256').update(bytes).digest('hex')
+
+/** The paths a skill's front matter marks visible (`visibleAssets:`), as `skill push` reads them. */
+function visibleAssets(skillMd: string | undefined): Set<string> {
+  if (!skillMd) return new Set()
+  try {
+    const fm = matter(skillMd).data as { visibleAssets?: unknown }
+    return new Set(Array.isArray(fm.visibleAssets) ? fm.visibleAssets.filter((v): v is string => typeof v === 'string') : [])
+  } catch {
+    return new Set()
+  }
+}
+
+/**
+ * A skill's assets here against the workspace's (the snapshot's copies):
+ * the whole set the push would send, each marked new, changed or the same,
+ * and those the workspace has that this folder no longer does.
+ */
+export function skillAssets(root: string, name: string, paths: string[], theirs: RemoteItem | undefined): { assets: PushAsset[]; removed: string[]; changed: boolean } {
+  const prefix = `skills/${name}/`
+  const visible = visibleAssets(readLocal(root, `${prefix}SKILL.md`) ?? undefined)
+  const remote = new Map((theirs?.assets ?? []).map((a) => [a.path, a]))
+  const assets: PushAsset[] = []
+  for (const file of paths) {
+    let bytes: Uint8Array
+    try {
+      bytes = new Uint8Array(readFileSync(safePath(root, file)))
+    } catch {
+      continue
+    }
+    const rel = file.slice(prefix.length)
+    const digest = sha256(bytes)
+    const copy = remote.get(file)
+    let change: PushAsset['change'] = 'new'
+    if (copy) {
+      let theirBytes: Uint8Array | null = copy.bytes ?? null
+      if (!theirBytes && copy.from && existsSync(copy.from)) theirBytes = new Uint8Array(readFileSync(copy.from))
+      change = theirBytes && sha256(theirBytes) === digest ? 'same' : 'changed'
+    }
+    assets.push({ path: rel, file, sha256: digest, bytes: bytes.byteLength, mime: mimeFromPath(file), visible: visible.has(rel), change })
+  }
+  const removed = [...remote.keys()].filter((p) => !paths.includes(p))
+  return { assets, removed, changed: removed.length > 0 || assets.some((a) => a.change !== 'same') }
+}
+
+const kb = (n: number) => (n < 1024 ? `${n} B` : n < 1024 * 1024 ? `${Math.round(n / 1024)} KB` : `${(n / 1024 / 1024).toFixed(1)} MB`)
+
+/**
+ * What a push would propose, item by item: every item changed here or only
+ * here, with what it sends, or why it cannot be proposed now. Items that
+ * match the workspace, or only changed there, are not listed.
+ */
+export function pushCandidates(input: CandidateInput): PushItem[] {
+  const { root, plan, snapshot } = input
+  const lock = input.lock && (!snapshot || input.lock.workspace === snapshot.workspace) ? input.lock : null
+  const remote = new Map(input.remote.map((r) => [r.ref, r]))
+  const byPlan = new Map(plan.map((p) => [p.ref, p]))
+  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()) {
+    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)
+    const p = byPlan.get(ref)
+    const entry = lock?.items[ref]
+    const theirs = remote.get(ref)
+    // A plan's "only here" for a Function in its own folder is named after its entry file: the folder names it here.
+    if (p?.status === 'local-only' && !entry && !here.has(ref)) continue
+    // An Agent's lessons are never in the plan: they are proposed while the file differs from what the last pull wrote.
+    const lessons = kind === 'lessons' ? lessonsProposal(root, input.lock?.workspace ?? snapshot?.workspace ?? '', name) : null
+    if (kind === 'lessons' && !lessons) continue
+    // Not in the plan: something the folder has that the workspace and the last pull never did.
+    const status = p?.status ?? 'local-only'
+    if (status === 'new' || status === 'changed') continue
+    const deleted = status === 'deleted-local'
+    const bringDocuments = kind === 'knowledge' && !!input.documents?.names.has(name)
+    const { files, notes, problem, assets: assetPaths } = deleted ? { files: {} as Record<string, string>, notes: [] as string[], problem: undefined, assets: undefined } : itemFiles(root, kind, name, entry, { documents: bringDocuments })
+    // What a file hash does not cover: a skill's assets, and a knowledge base's documents when they are brought.
+    const assetState = kind === 'skill' && !deleted && (assetPaths?.length || theirs?.assets?.length) ? skillAssets(root, name, assetPaths ?? [], theirs) : null
+    const docs = bringDocuments && !deleted && input.documents
+      ? documentChanges(localDocuments(root, name), input.documents.pulled[name] ?? {}, input.documents.platform.get(name) ?? [])
+      : null
+    const extra = Boolean(assetState?.changed) || Boolean(docs && (docs.upload.length || docs.remove.length))
+    // `same` in the plan reads the base's paths; a file added to the item since is still a change here.
+    // A Plugin whose only difference is this computer's secrets (a header set here) is the same, as status reads it.
+    const pluginSame = kind === 'plugin' && !!theirs && Object.keys(files).length > 0 && Object.keys(files).every((p) => theirs.files[p] !== undefined && comparableText(p, readLocal(root, p) ?? '', theirs.files[p]!) === theirs.files[p])
+    const textSame = !entry || itemHash(files) === entry.remote || !theirs || itemHash(theirs.files) !== entry.remote || pluginSame
+    if (status === 'same' && textSame && !extra) continue
+    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 diff: PushFile[] = diffPaths.map((path) => ({ path, base: baseFiles[path] ?? null, local: files[path] ?? null })).filter((f) => f.base !== f.local)
+    const item: PushItem = {
+      ref,
+      kind,
+      name,
+      title: titleFor(kind, name, kind === 'lessons' ? { [`agents/${name}/agent.json`]: readLocal(root, `agents/${name}/agent.json`) ?? '' } : deleted ? baseFiles : files, theirs?.title ?? (p && p.title !== p.name ? p.title : undefined)),
+      change: deleted ? 'deleted' : isNew ? 'new' : 'changed',
+      proposable: true,
+      blocked: null,
+      reason: null,
+      id: entry?.id ?? theirs?.id ?? null,
+      baseRevision: null,
+      files,
+      diff,
+      base: baseFiles,
+      notes,
+    }
+    if (assetState) {
+      item.assets = assetState.assets
+      for (const a of assetState.assets) if (a.change !== 'same') notes.push(`Asset ${a.path}: ${a.change === 'new' ? 'new' : 'changed'} (${kb(a.bytes)})`)
+      for (const r of assetState.removed) notes.push(`Asset ${r.slice(`skills/${name}/`.length)}: removed here, so it leaves the skill`)
+    }
+    if (docs) {
+      item.documents = { upload: docs.upload.map(({ content: _content, ...d }) => d), remove: docs.remove }
+      for (const d of docs.upload) notes.push(`Document ${d.fileName}: ${d.change === 'new' ? 'new' : 'changed'} (${kb(d.bytes)})${d.replaces ? '; the copy you pulled is taken off once everything else is applied' : ''}`)
+      for (const d of docs.remove) notes.push(`Document ${d.fileName}: you removed it after bringing it, so it is taken off the workspace (this cannot be undone)`)
+      notes.push(...docs.notes)
+    }
+    if (lessons) {
+      item.change = lessons.pulled ? 'changed' : 'new'
+      if (lessons.added.length) notes.push(`${lessons.added.length} new rule${lessons.added.length === 1 ? '' : 's'}, proposed for review: ${lessons.added.length === 1 ? 'it reaches' : 'they reach'} the Agent once a reviewer approves ${lessons.added.length === 1 ? 'it' : 'them'} on the platform`)
+      if (lessons.removed.length) notes.push(`${lessons.removed.length} rule${lessons.removed.length === 1 ? '' : 's'} removed here ${lessons.removed.length === 1 ? 'isn’t' : 'aren’t'} proposed: an active rule is retired on the platform, where rules are reviewed`)
+      if (!lessons.added.length && !lessons.removed.length) notes.push('Proposes the rules the workspace doesn’t have yet, for review')
+    }
+    const block = (code: BlockCode, reason: string) => Object.assign(item, { proposable: false, blocked: code, reason })
+    if (NOT_PROPOSED[kind]) block('kind', NOT_PROPOSED[kind]!)
+    else if (!PUSH_KINDS.includes(kind)) block('kind', 'Not a kind a change request carries')
+    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]!)
+    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 (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')
+    }
+    if (item.proposable && deleted) {
+      item.baseRevision = (kind === 'blueprint' || kind === 'evaluation' ? snapshot?.groups[kind] : undefined) ?? theirs?.revision ?? entry?.revision ?? null
+      if (!item.baseRevision) block('shape', 'The workspace’s revision of it isn’t known: fetch, then propose')
+    } else if (item.proposable && !isNew) {
+      // The base is what the workspace holds now (the plan says only this side moved): its current
+      // revision, which for a Blueprint file is the Blueprint's.
+      item.baseRevision = (kind === 'blueprint' || kind === 'evaluation' ? snapshot?.groups[kind] : undefined) ?? (theirs && entry && itemHash(theirs.files) === entry.remote ? theirs.revision : undefined) ?? entry?.revision ?? null
+    } else if (item.proposable && kind === 'blueprint') {
+      item.baseRevision = snapshot?.groups.blueprint ?? null
+    }
+    out.push(item)
+  }
+  return out
+}
+
+/** Whether pushing these needs the organization key at Apply: any Blueprint item does. */
+export function needsOrganizationKey(items: Array<{ kind: string; proposable?: boolean }>): boolean {
+  return items.some((i) => i.kind === 'blueprint' && i.proposable !== false)
+}
+
+// ── What the platform takes ─────────────────────────────────────────────────
+
+export interface FunctionBuild {
+  manifest: Record<string, unknown>
+  /** base64 */
+  bundle: string
+  /** base64 tar.gz of the source, when the Function sits in a project */
+  source?: string | null
+}
+
+export interface PushBodyItem {
+  ref: string
+  id?: string | null
+  baseRevision?: string | null
+  files: Record<string, string>
+  build?: FunctionBuild
+  deleted?: true
+  assets?: Array<{ path: string; storageKey: string; mime: string; bytes: number; sha256: string; visible?: boolean }>
+  documents?: { upload: Array<{ fileName: string; folder?: string; sha256: string; bytes: number; mime: string; replaces: string | null }>; remove: Array<{ fileName: string; sourceId: string }> }
+}
+
+/** A document as a request lists it: its own file name, and its folder when it is in one. */
+function asRequestDocument<T extends { fileName: string }>(d: T): T & { folder?: string } {
+  const { folder, fileName } = splitDocumentPath(d.fileName)
+  return { ...d, fileName, ...(folder ? { folder } : {}) }
+}
+
+/** The entry `function deploy` builds for a Function item. */
+export function functionEntryOf(root: string, name: string, find: (root: string, name: string) => string | null): string {
+  if (existsSync(join(root, 'functions', name, 'package.json'))) {
+    const entry = find(root, name)
+    if (!entry) throw new CliError(`functions/${name}/ has no entry file to build`, { code: 'USAGE', hint: `add functions/${name}/index.ts, or a file whose automation() is named ${name}` })
+    return entry
+  }
+  return `functions/${name}.ts`
+}
+
+/**
+ * Each proposable item as the platform takes it: a Function is built first,
+ * a skill's assets uploaded (content-addressed, so an asset the workspace
+ * has already is not stored twice), a deletion sent with no files, and a
+ * knowledge base's documents listed by digest (their bytes follow once the
+ * request exists).
+ */
+export async function pushBody(
+  items: PushItem[],
+  build: (item: PushItem) => Promise<FunctionBuild>,
+  uploadAsset: (item: PushItem, asset: PushAsset) => Promise<string> = async () => {
+    throw new CliError('skill assets need the platform to upload to', { code: 'USAGE', hint: 'propose with `frontera local sync push`, which uploads them' })
+  },
+): Promise<PushBodyItem[]> {
+  const out: PushBodyItem[] = []
+  for (const item of items) {
+    if (!item.proposable) continue
+    const assets = item.assets ? await Promise.all(item.assets.map(async (a) => ({
+      path: a.path,
+      storageKey: await uploadAsset(item, a),
+      mime: a.mime,
+      bytes: a.bytes,
+      sha256: a.sha256,
+      ...(a.visible ? { visible: true } : {}),
+    }))) : undefined
+    out.push({
+      ref: item.ref,
+      ...(item.id ? { id: item.id } : {}),
+      ...(item.baseRevision ? { baseRevision: item.baseRevision } : {}),
+      files: item.files,
+      ...(item.change === 'deleted' ? { deleted: true as const } : {}),
+      ...(item.kind === 'function' && item.change !== 'deleted' ? { build: await build(item) } : {}),
+      ...(assets ? { assets } : {}),
+      ...(item.documents ? { documents: { upload: item.documents.upload.map(({ change: _change, ...d }) => asRequestDocument(d)), remove: item.documents.remove.map(asRequestDocument).map(({ folder: _folder, ...d }) => d) } } : {}),
+    })
+  }
+  return out
+}
+
+// ── The request this project keeps ──────────────────────────────────────────
+
+export type RequestState = 'draft' | 'open' | 'approved' | 'merging' | 'merged' | 'closed'
+
+export interface KeptRequest {
+  id: string
+  title: string
+  state: RequestState
+  refs: string[]
+  /** What people call each item, so the home and the page name them without reading the platform. */
+  titles: Record<string, string>
+  proposedAt: string
+  updatedAt: string
+  /** When Apply last ran, and whether it went through. */
+  applied?: { at: string; ok: boolean }
+}
+
+export interface RequestsFile {
+  version: 1
+  workspace: string
+  /** The request the next push updates: open until it is applied or closed. */
+  current: string | null
+  requests: Record<string, KeptRequest>
+}
+
+const REQUESTS_JSON = join(SYNC_DIR, 'requests.json')
+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')
+}
+
+/** The requests file for this workspace; another workspace's (a relinked project) reads as none. */
+export function readRequests(root: string, workspace: string): RequestsFile {
+  const empty: RequestsFile = { version: 1, workspace, current: null, requests: {} }
+  try {
+    const file = join(root, REQUESTS_JSON)
+    if (!existsSync(file)) return empty
+    const parsed = JSON.parse(readFileSync(file, 'utf8')) as RequestsFile
+    if (!parsed || parsed.version !== 1 || parsed.workspace !== workspace || typeof parsed.requests !== 'object' || !parsed.requests) return empty
+    return parsed
+  } catch {
+    return empty
+  }
+}
+
+export function writeRequests(root: string, file: RequestsFile): void {
+  ignoreSync(root)
+  writeFileAtomic(join(root, REQUESTS_JSON), `${JSON.stringify(file, null, 2)}\n`, 0o644)
+}
+
+/** A request still taking pushes: the next push updates it rather than opening another. */
+export function isOpen(state: string | null | undefined): boolean {
+  return state === 'draft' || state === 'open' || state === 'approved'
+}
+
+/** The current request, when there is one still open or being applied. */
+export function currentRequest(file: RequestsFile): KeptRequest | null {
+  const kept = file.current ? file.requests[file.current] : undefined
+  return kept ?? null
+}
+
+/** The platform's view of a request, as much of it as this file keeps. */
+export interface RequestViewLike {
+  request: { id: string; title: string; state: string; createdAt?: string; updatedAt?: string }
+  items: Array<{ ref: string }>
+}
+
+/** Record what the platform said about a request; an applied or closed one stops being current. */
+export function recordRequest(root: string, workspace: string, view: RequestViewLike, opts: { titles?: Record<string, string>; applied?: { ok: boolean }; pushed?: boolean; now?: Date } = {}): RequestsFile {
+  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 titles = Object.fromEntries(refs.map((r) => [r, opts.titles?.[r] ?? before?.titles[r] ?? r]))
+  file.requests[view.request.id] = {
+    id: view.request.id,
+    title: view.request.title,
+    state: view.request.state as RequestState,
+    refs,
+    titles,
+    proposedAt: before?.proposedAt ?? view.request.createdAt ?? now,
+    updatedAt: now,
+    // A push after a failed Apply proposes the request again: it no longer reads "Apply failed".
+    ...(opts.applied ? { applied: { at: now, ok: opts.applied.ok } } : before?.applied && !opts.pushed ? { applied: before.applied } : {}),
+  }
+  // Applied or closed, it stays listed (the card says "Applied") and the next push opens a new one.
+  file.current = view.request.id
+  writeRequests(root, file)
+  return file
+}
+
+/**
+ * The base versions kept with a request: the files each item was changed
+ * from, for its Changes view. `replace: false` (a push of named items) keeps
+ * the other items' copies.
+ */
+export function writeRequestBase(root: string, id: string, items: PushItem[], opts: { replace?: boolean } = {}): void {
+  if (!/^[0-9a-f-]{36}$/i.test(id)) return
+  ignoreSync(root)
+  const dir = join(root, REQUESTS_DIR, id, 'base')
+  const listed = join(dir, '.items')
+  const previous = opts.replace === false && existsSync(listed) ? readFileSync(listed, 'utf8').split('\n').filter(Boolean) : []
+  if (opts.replace !== false) rmSync(dir, { recursive: true, force: true })
+  mkdirSync(dir, { recursive: true })
+  for (const item of items) {
+    for (const [path, text] of Object.entries(item.base)) {
+      safePath(root, path)
+      const full = safePath(dir, path)
+      mkdirSync(dirname(full), { recursive: true })
+      writeFileSync(full, text)
+    }
+  }
+  // Which items the copy is for, whether each was new (a new item has no base to keep), and its base's
+  // paths (a deletion sends no files, so its Changes view lists them from here).
+  const lines = new Map(previous.map((l) => [l.split('\t')[0]!, l]))
+  for (const i of items) lines.set(i.ref, `${i.ref}\t${i.change}\t${Object.keys(i.base).join('\u001f')}`)
+  writeFileSync(listed, `${[...lines.values()].join('\n')}\n`)
+}
+
+/** A base file kept with a request, or null; `known` says whether the copy exists at all, `paths` an item's base files. */
+export function readRequestBase(root: string, id: string): { known: boolean; read: (path: string) => string | null; paths: (ref: string) => string[] } {
+  const dir = join(root, REQUESTS_DIR, id, 'base')
+  const known = /^[0-9a-f-]{36}$/i.test(id) && existsSync(join(dir, '.items'))
+  const listed = known ? readFileSync(join(dir, '.items'), 'utf8').split('\n').filter(Boolean).map((l) => l.split('\t')) : []
+  return {
+    known,
+    paths: (ref) => (listed.find((l) => l[0] === ref)?.[2] ?? '').split('\u001f').filter(Boolean),
+    read: (path) => {
+      if (!known) return null
+      try {
+        const full = safePath(dir, path)
+        return existsSync(full) ? readFileSync(full, 'utf8') : null
+      } catch {
+        return null
+      }
+    },
+  }
+}
+
+// ── After Apply ─────────────────────────────────────────────────────────────
+
+/** Whether two versions of a file say the same: the same document for JSON and YAML (key order aside), the same text otherwise. */
+export function sameDocument(path: string, a: string, b: string): boolean {
+  if (a === b) return true
+  try {
+    if (/^agents\/[^/]+\/evals\/[^/]+\.ya?ml$/.test(path)) return deepEqual(evaluationCases(a), evaluationCases(b))
+    // A knowledge base's quality checks are a set: the platform lists them in its own order.
+    if (path.endsWith(`/${QUALITY_CHECKS_FILE}`)) return deepEqual(checkSet(a), checkSet(b))
+    if (/\.json$/i.test(path)) return deepEqual(JSON.parse(a), JSON.parse(b))
+    if (/\.ya?ml$/i.test(path)) return deepEqual(parseYaml(a), parseYaml(b))
+  } catch {
+    return false
+  }
+  return false
+}
+
+/** 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() }))
+    .sort((x, y) => x.question.localeCompare(y.question))
+}
+
+/**
+ * An evaluation file's cases as the platform keeps them: each question with
+ * its expected answer and phrases, in order. A case's name and gold flag are
+ * the platform's to give (a pull names cases by position), so two files with
+ * the same cases say the same.
+ */
+function evaluationCases(text: string): unknown {
+  const doc = (parseYaml(text) ?? {}) as { cases?: Array<Record<string, unknown>> }
+  return (doc.cases ?? []).map((c) =>
+    c.scenario !== undefined
+      ? { scenario: c.scenario, expect: c.expect ?? null }
+      : {
+          question: (c.conversation as Array<{ user?: string }> | undefined)?.[0]?.user ?? null,
+          expected: typeof c.expected === 'string' ? c.expected : null,
+          contains: Array.isArray(c.expectedContains) ? c.expectedContains : [],
+          // A check's text is the platform's to word.
+          checks: Array.isArray(c.checks) ? (c.checks as Array<Record<string, unknown>>).map(({ text: _text, ...check }) => check) : [],
+          judged: Array.isArray(c.judged) ? c.judged : [],
+        },
+  )
+}
+
+/**
+ * After an Apply went through and a fetch read the new versions: each
+ * applied item's base moves to the workspace's version, as a pull leaves it.
+ * A file that says the same as the workspace's (the platform may order an
+ * Agent's keys its own way) takes the workspace's text, so the item reads as
+ * up to date; one that differs is left alone and shows as a change here.
+ * Returns the refs moved and the files rewritten.
+ */
+export function adoptApplied(root: string, workspace: string, refs: string[], remote: RemoteItem[], lock: SyncLock | null, now = new Date(), opts: { deleted?: string[] } = {}): { adopted: string[]; rewritten: string[] } {
+  const byRef = new Map(remote.map((r) => [r.ref, r]))
+  const next: SyncLock = { version: 2, workspace, ...(lock?.workspace === workspace && lock.pulledAt ? { pulledAt: lock.pulledAt } : {}), items: { ...(lock?.workspace === workspace ? lock.items : {}) } }
+  const moved: RemoteItem[] = []
+  const rewritten: string[] = []
+  const forgotten: string[] = []
+  for (const ref of refs) {
+    // Deleted here and applied, so gone there too: the item leaves the lock and its base, as a pull's Delete here
+    // leaves it (whatever a fetch that did not read the whole index still lists).
+    if (opts.deleted?.includes(ref)) {
+      if (next.items[ref]) {
+        forgotten.push(...Object.keys(next.items[ref]!.files))
+        delete next.items[ref]
+      }
+      continue
+    }
+    const item = byRef.get(ref)
+    if (!item) continue
+    for (const [path, text] of Object.entries(item.files)) {
+      const here = readLocal(root, path)
+      if (here !== null && here !== text && sameDocument(path, here, text)) {
+        writeFileSync(safePath(root, path), text)
+        rewritten.push(path)
+      }
+    }
+    next.items[ref] = {
+      ...(item.id ? { id: item.id } : {}),
+      ...(item.revision ? { revision: item.revision } : {}),
+      remote: itemHash(item.files),
+      files: Object.fromEntries(Object.entries(item.files).map(([p, c]) => [p, hash(c)])),
+      ...(item.version ? { version: item.version } : {}),
+      pulledAt: now.toISOString(),
+    }
+    moved.push(item)
+  }
+  if (!moved.length && !forgotten.length) return { adopted: [], rewritten }
+  if (moved.length) writeBase(root, moved, lock)
+  if (forgotten.length) dropBase(root, forgotten)
+  writeLock(root, next)
+  const gone = (opts.deleted ?? []).filter((r) => refs.includes(r))
+  return { adopted: [...moved.map((m) => m.ref), ...gone], rewritten }
+}
+
+// ── In words ────────────────────────────────────────────────────────────────
+
+export const KIND_WORD: Record<SyncKind, string> = {
+  agent: 'Agent',
+  workflow: 'Workflow',
+  function: 'Function',
+  skill: 'Skill',
+  knowledge: 'Knowledge base',
+  blueprint: 'Blueprint',
+  plugin: 'Plugin',
+  evaluation: 'Evaluation',
+  dataset: 'Dataset',
+  theme: 'Slide theme',
+  'chat-app': 'Chat App',
+  app: 'App',
+  brand: 'Brand',
+  library: 'Library',
+  lessons: 'Lessons for Agent',
+}
+
+/**
+ * What an Agent's bindings file changes: its tools (Functions and workflows),
+ * its Context (the object types it reads), or both. Unread, it says both.
+ */
+function bindingsParts(file: PushFile | undefined): string[] {
+  const read = (text: string | null | undefined) => {
+    try {
+      const doc = JSON.parse(text ?? '{}') as Record<string, unknown>
+      return { tools: JSON.stringify([doc.functions ?? [], doc.workflows ?? []]), context: JSON.stringify(doc.blueprint ?? []) }
+    } catch {
+      return null
+    }
+  }
+  const before = read(file?.base)
+  const after = read(file?.local)
+  if (!file || !before || !after) return ['tools and Context']
+  const parts = [before.tools !== after.tools ? 'tools' : '', before.context !== after.context ? 'Context' : ''].filter(Boolean)
+  return parts.length ? parts : ['tools and Context']
+}
+
+/** What changed in an item, in the product's words: "configuration and behavior settings". */
+export function changedParts(kind: SyncKind, name: string, paths: string[], files: PushFile[] = []): string[] {
+  const parts = new Set<string>()
+  for (const path of paths) {
+    if (kind === 'agent') {
+      if (path.endsWith('/agent.json')) parts.add('configuration')
+      else if (path.endsWith('/operating.json')) parts.add('behavior settings')
+      else if (path.endsWith('/bindings.json')) for (const p of bindingsParts(files.find((f) => f.path === path))) parts.add(p)
+    } else if (kind === 'skill') {
+      const rel = path.slice(`skills/${name}/`.length)
+      parts.add(rel === 'SKILL.md' ? 'instructions' : rel.startsWith('scripts/') ? 'scripts' : 'references')
+    } else if (kind === 'workflow') parts.add('definition')
+    else if (kind === 'function') parts.add('code')
+    else if (kind === 'knowledge') parts.add(path.endsWith(`/${QUALITY_CHECKS_FILE}`) ? 'quality checks' : 'settings')
+    else if (kind === 'plugin') parts.add('settings and policy')
+    else if (kind === 'evaluation') parts.add('cases')
+    else if (kind === 'chat-app') parts.add('experience')
+    else if (kind === 'lessons') parts.add('rules')
+  }
+  return [...parts]
+}
+
+function joinWords(words: string[]): string {
+  if (words.length <= 1) return words[0] ?? ''
+  return `${words.slice(0, -1).join(', ')} and ${words[words.length - 1]}`
+}
+
+/** One line per item, as the Overview says it: "Agent Support Concierge: behavior settings changed". */
+export function itemLine(item: { kind: SyncKind; name: string; title: string; change: 'changed' | 'new' | 'deleted'; changedPaths?: string[]; changedFiles?: PushFile[]; assetsChanged?: boolean; documentsChanged?: boolean }): string {
+  const [dir, apiName] = item.name.split('/')
+  const word = BLUEPRINT_WORD[dir ?? '']
+  // A Blueprint file says what it is: "Object type Ticket".
+  const label = item.kind === 'blueprint' ? (word && apiName ? `${word[0]!.toUpperCase()}${word.slice(1)} ${item.title}` : `Blueprint ${item.title}`) : `${KIND_WORD[item.kind]} ${item.title}`
+  if (item.change === 'deleted') return `${label}: delete`
+  // The platform keeps no lessons file, so "new" or "changed" depends only on
+  // whether this project pulled one; what the request does is the same either way.
+  if (item.kind === 'lessons') return `${label}: rules proposed for review`
+  if (item.change === 'new') return `${label}: new`
+  const parts = changedParts(item.kind, item.name, item.changedPaths ?? [], item.changedFiles)
+  if (item.assetsChanged) parts.push('assets')
+  if (item.documentsChanged) parts.push('documents')
+  return parts.length ? `${label}: ${joinWords(parts)} changed` : `${label}: changed`
+}
+
+/** The line for a candidate, with what its files do not show (assets, documents). */
+export function pushItemLine(item: PushItem): string {
+  return itemLine({
+    ...item,
+    changedPaths: item.diff.map((f) => f.path),
+    changedFiles: item.diff,
+    assetsChanged: Boolean(item.assets?.some((a) => a.change !== 'same')) || item.notes.some((n) => n.startsWith('Asset ') && n.includes('removed here')),
+    documentsChanged: Boolean(item.documents && (item.documents.upload.length || item.documents.remove.length)),
+  })
+}
+
+// ── Apply's outcome ─────────────────────────────────────────────────────────
+
+export type StepStatus = 'done' | 'failed' | 'not-run'
+
+export interface ApplyStep {
+  key: string
+  phase: string
+  ref: string
+  label: string
+  status: StepStatus
+  error?: string
+  notes?: string[]
+}
+
+export interface ApplyOutcome {
+  ok: boolean
+  steps: ApplyStep[]
+  failure?: { key: string; ref: string; itemIds: string[]; message: string }
+  compensation: Array<{ label: string; type: string; status: 'put-back' | 'failed' | 'irreversible'; error?: string }>
+}
+
+/** Apply's outcome as the service sent it, read defensively: a field it lacks reads as empty. */
+export function parseOutcome(raw: unknown): ApplyOutcome {
+  const o = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
+  const steps = (Array.isArray(o.steps) ? o.steps : []).flatMap((s): ApplyStep[] => {
+    if (!s || typeof s !== 'object') return []
+    const r = s as Record<string, unknown>
+    const status: StepStatus = r.status === 'done' || r.status === 'failed' ? r.status : 'not-run'
+    return [{
+      key: String(r.key ?? ''),
+      phase: String(r.phase ?? ''),
+      ref: String(r.ref ?? ''),
+      label: String(r.label ?? r.key ?? ''),
+      status,
+      ...(typeof r.error === 'string' ? { error: r.error } : {}),
+      ...(Array.isArray(r.notes) ? { notes: r.notes.filter((n): n is string => typeof n === 'string') } : {}),
+    }]
+  })
+  const f = o.failure as Record<string, unknown> | undefined
+  const compensation = (Array.isArray(o.compensation) ? o.compensation : []).flatMap((c) => {
+    if (!c || typeof c !== 'object') return []
+    const r = c as Record<string, unknown>
+    const status = r.status === 'failed' || r.status === 'irreversible' ? r.status : 'put-back'
+    return [{ label: String(r.label ?? ''), type: String(r.type ?? ''), status: status as 'put-back' | 'failed' | 'irreversible', ...(typeof r.error === 'string' ? { error: r.error } : {}) }]
+  })
+  return {
+    ok: o.ok === true,
+    steps,
+    ...(f && typeof f === 'object' ? { failure: { key: String(f.key ?? ''), ref: String(f.ref ?? ''), itemIds: Array.isArray(f.itemIds) ? f.itemIds.map(String) : [], message: String(f.message ?? 'A step failed') } } : {}),
+    compensation,
+  }
+}
+
+const STEP_MARK: Record<StepStatus, string> = { done: '✓', failed: '✗', 'not-run': '·' }
+const BACK_WORD = { 'put-back': 'put back', failed: 'could not be put back', irreversible: 'cannot be withdrawn' } as const
+
+/** Apply's steps, and after a failure what was put back, as `request apply` prints them. */
+export function describeOutcome(outcome: ApplyOutcome, titles: Record<string, string> = {}): string[] {
+  const lines = outcome.steps.flatMap((s) => [
+    `  ${STEP_MARK[s.status]} ${s.label}${s.status === 'not-run' && !outcome.ok ? '  (not run)' : ''}`,
+    ...(s.notes ?? []).map((n) => `      · ${n}`),
+  ])
+  if (outcome.ok) return [`Applied ${outcome.steps.length} step${outcome.steps.length === 1 ? '' : 's'}:`, ...lines]
+  const failed = outcome.failure
+  const name = failed ? titles[failed.ref] ?? failed.ref : 'a step'
+  return [
+    `Not applied: ${failed ? `${name} failed: ${failed.message}` : 'a step failed'}`,
+    ...lines,
+    ...(outcome.compensation.length
+      ? ['', 'What was put back:', ...outcome.compensation.map((c) => `  ${c.label}: ${BACK_WORD[c.status]}${c.error ? ` (${c.error})` : ''}`)]
+      : ['', 'Nothing had changed yet, so nothing needed putting back.']),
+  ]
+}
+
+export interface Check {
+  ref: string
+  itemId?: string
+  code: string
+  message: string
+}
+
+/** The checks that say where an item stands, in the reader's words; the others say what is wrong in a file, as they are. */
+const CHECK_WORDS: Record<string, string> = {
+  stale_base: 'Changed in the workspace since it was proposed: pull and merge it, then propose again',
+  gone: 'No longer in the workspace: propose it again as new, or leave it out',
+  exists: 'Now exists in the workspace: pull and merge it first',
+}
+
+/** The blocking checks a refusal carries (`details.checks`), read defensively. */
+export function checksOf(details: unknown): Check[] {
+  const d = (details && typeof details === 'object' ? details : {}) as { checks?: unknown; details?: { checks?: unknown } }
+  const list = Array.isArray(d.checks) ? d.checks : Array.isArray(d.details?.checks) ? d.details!.checks as unknown[] : []
+  return list.flatMap((c) => {
+    if (!c || typeof c !== 'object') return []
+    const r = c as Record<string, unknown>
+    if (typeof r.ref !== 'string' || typeof r.message !== 'string') return []
+    return [{ ref: r.ref, ...(typeof r.itemId === 'string' ? { itemId: r.itemId } : {}), code: typeof r.code === 'string' ? r.code : 'invalid', message: (typeof r.code === 'string' && CHECK_WORDS[r.code]) || r.message }]
+  })
+}