@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/commands/local/sync-request.ts

@@ -1,9 +1,10 @@
-import { readFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 
 import { CliError, UsageError } from '../../errors'
 import { documentPath, readFolders, readPulledDocuments, recordPulledDocuments, sha256Of, type PulledDocument } from '../../local/local-knowledge-documents'
 import { assetFilename } from '../skill/bundle-commands'
+import { outsideImports } from '../../function-outside-imports'
 import { packDirectory } from '../../pack'
 import { createTarGz } from '../../tar'
 import { functionEntry } from '../../local/local-dev-sync'
@@ -13,6 +14,11 @@ import { HISTORY_KINDS, projectAtRevision } from '../../local/local-sync-base'
 import { normalizeOrigin, unwrap } from '../../local/local-sync-client'
 import { getSyncKey, readLink, type SyncLink } from '../../local/local-sync-link'
 import { itemTitle } from '../../local/local-sync-names'
+import { evalsDetail, evalsLine, lastRender, sessionScreenshots } from '../../local/local-request-evidence'
+import { readAppliedRun, readLastRun, recordApplied, recordRun } from '../../local/local-test-baseline'
+import { agentFilesProblem, runCases, selectCaseFiles } from '../../local/local-test-runner'
+import { findAppProjects } from '../../mcp/mcp-apps'
+import { runtimeLink } from '../../mcp/mcp-runtime'
 import { readLock, type SyncKind } from '../../local/local-sync-plan'
 import {
   adoptApplied,
@@ -55,7 +61,10 @@ import { fetchFor, planFor, sourceFor } from './sync'
  *   request [show]           the current request: its items, each against its base, and what happened
  *   request apply            apply it: each step moves a live version, and a failure puts every earlier one back;
  *                            then fetch, so the applied items read as up to date
+ *   request evidence         attach evidence: each Agent's gated evals against its last applied run,
+ *                            each released App's last render, a Forge session's screenshots, a trace link
  *   request close            close it without applying
+ *   push --release desk=1.4.0  also release a Custom App: Apply promotes that deployment, last
  *
  * The request's id is kept in `.frontera/sync/requests.json` (not
  * committed). Keys come from the keychain, as for `sync fetch`; the
@@ -81,6 +90,8 @@ interface Platform {
   call<T>(method: 'GET' | 'POST' | 'PUT', path: string, body?: unknown, opts?: { organizationKey?: string | null; timeoutMs?: number }): Promise<T>
   /** A body sent as it is (a document's bytes, a multipart upload), not as JSON. */
   send<T>(method: 'POST' | 'PUT', path: string, body: RequestBody, contentType: string | null, opts?: { timeoutMs?: number }): Promise<T>
+  /** A body read as it is (an evidence picture). */
+  bytes(path: string): Promise<{ bytes: Uint8Array; mime: string }>
 }
 
 /**
@@ -109,6 +120,11 @@ function platform(link: SyncLink, key: string): Platform {
     async send<T>(method: 'POST' | 'PUT', path: string, body: RequestBody, contentType: string | null, opts: { timeoutMs?: number } = {}): Promise<T> {
       return answer<T>(await request(method, path, contentType ? { 'content-type': contentType } : {}, body, opts.timeoutMs ?? 300_000))
     },
+    async bytes(path: string) {
+      const res = await request('GET', path, {}, undefined, 60_000)
+      if (!res.ok) return answer<never>(res)
+      return { bytes: new Uint8Array(await res.arrayBuffer()), mime: res.headers.get('content-type') ?? 'application/octet-stream' }
+    },
   }
 }
 
@@ -125,6 +141,10 @@ async function answer<T>(res: Response): Promise<T> {
   const message = String(parsed?.message ?? (typeof parsed?.error === 'string' ? parsed.error : '') ?? '').trim() || text.slice(0, 300) || `the platform answered ${res.status}`
   const checks = checksOf(parsed?.details)
   if (checks.length) throw new CliError(message, { code: 'SYNC_CHECKS', hint: 'fix the items the checks name, then push again', details: { checks } })
+  const details = (parsed?.details ?? null) as { code?: string; gate?: Gate } | null
+  if (details?.code === 'GATE_FAILED' && details.gate) {
+    throw new CliError(message, { code: 'SYNC_APPLY_GATED', hint: 'make the checks pass (`frontera local sync request evidence` attaches evals and renders), or a workspace admin applies with `--force --reason "<why>"`', details: { gate: details.gate } })
+  }
   if (res.status === 401) throw new CliError('the platform refused the key', { code: 'UNAUTHORIZED', hint: 'check it is a current workspace key (sk-ws-…) for this platform; `frontera local sync connect` stores a new one' })
   if (res.status === 403) throw new CliError(message, { code: 'FORBIDDEN', hint: 'the key’s role decides what it may propose and apply; ask a workspace admin' })
   if (res.status === 404) throw new CliError(message, { code: 'NOT_FOUND', hint: 'the change request is gone from the workspace; propose again with `frontera local sync push`' })
@@ -145,6 +165,8 @@ interface ViewItem {
   id: string
   ref: string
   kind: SyncKind
+  /** What the item's candidate is: evidence taken for it is bound to it. */
+  candidateDigest?: string
   name: string
   baseRevision: string | null
   state: string
@@ -156,15 +178,107 @@ interface ViewItem {
   deleted?: boolean
   assets?: Array<{ path: string; bytes: number; sha256: string }>
   documents?: { upload: Array<{ fileName: string; folder?: string | null; sha256: string; bytes: number; replaces?: string | null; staged?: boolean }>; remove: Array<{ fileName: string; sourceId: string }> }
+  /**
+   * `blueprint/workspace-grants`, while the request is still to be applied:
+   * each type its file moves, against what the workspace holds now, and the
+   * changes that give the workspace `read_sensitive`, in words.
+   */
+  grantChanges?: GrantChange[]
+  disclosures?: string[]
+}
+
+/** One type's workspace grant as the request moves it (`from` null: the workspace holds none on it). */
+export interface GrantChange {
+  objectType: string
+  from: string[] | null
+  to: string[]
+  disclosure: boolean
+  summary?: string
+}
+
+/**
+ * What a `blueprint/workspace-grants` item changes, under its line: each
+ * disclosure first (the workspace gains `read_sensitive`), then the other
+ * moves. Nothing when the view carries none (a platform before it, or a
+ * request already applied).
+ */
+export function grantChangeLines(item: Pick<ViewItem, 'grantChanges' | 'disclosures'>): string[] {
+  const changes = item.grantChanges ?? []
+  const disclosures = item.disclosures ?? changes.filter((g) => g.disclosure).map((g) => g.summary ?? g.objectType)
+  const said = (g: GrantChange) => g.summary ?? `${g.objectType}: ${g.from ? g.from.join(', ') : 'no grant'} → ${g.to.join(', ')}`
+  if (!changes.length && !disclosures.length) return item.grantChanges ? ['      · changes no grant: the workspace holds each as listed'] : []
+  return [
+    ...disclosures.map((d) => `      ! discloses: ${d}`),
+    ...changes.filter((g) => !g.disclosure).map((g) => `      · ${said(g)}`),
+  ]
+}
+
+/** The release gate as the platform reads it (design 2026-10-18 §6); absent from a platform before it. */
+export interface Gate {
+  required: string[]
+  checks: Array<{ id: string; kind: 'evals' | 'app'; ref: string; label: string; status: 'passed' | 'failed' | 'missing'; detail: string; required: boolean; reported?: string | null; evidenceId?: string | null }>
+  blocking: number
+}
+
+export interface Evidence {
+  id: string
+  kind: string
+  ref: string | null
+  title: string
+  detail: Record<string, unknown>
+  mime: string | null
+  bytes: number
+  hasImage: boolean
+  createdBy: string
+  createdAt: string
+  stale: boolean
 }
 
 interface View {
   request: { id: string; title: string; description: string | null; state: string; authorId: string; createdAt: string; updatedAt: string; mergedAt: string | null; closedAt?: string | null }
   items: ViewItem[]
   events: Array<{ id: string; kind: string; actorId: string; detail: Record<string, unknown> | null; createdAt: string }>
+  gate?: Gate
+  evidence?: Evidence[]
   outcome?: unknown
 }
 
+/** A Custom App release as a change request carries it: `app/<slug>`, naming the deployment Apply promotes. */
+export function releaseItem(slug: string, deployment: string): { ref: string; files: Record<string, string> } {
+  return { ref: `app/${slug}`, files: { [`apps/${slug}.release.json`]: `${JSON.stringify({ deployment }, null, 2)}\n` } }
+}
+
+/** The deployment a release item names. */
+export function releasedDeployment(item: Pick<ViewItem, 'name' | 'files'>): string | null {
+  try {
+    const doc = JSON.parse(item.files[`apps/${item.name}.release.json`] ?? 'null') as { deployment?: unknown } | null
+    return typeof doc?.deployment === 'string' ? doc.deployment : null
+  } catch {
+    return null
+  }
+}
+
+/** `--release desk=1.4.0,portal`: each App's slug and the deployment named (none: the newest). */
+export function parseReleases(flag: string | undefined): Array<{ slug: string; deployment: string | null }> {
+  if (!flag?.trim()) return []
+  return flag.split(',').map((part) => part.trim()).filter(Boolean).map((part) => {
+    const [slug = '', deployment = ''] = part.split('=')
+    if (!/^[A-Za-z0-9][\w.-]*$/.test(slug.trim())) throw new UsageError(`--release: ${part} is not an App slug`, '--release desk=1.4.0 (its deployment id or release label), or --release desk for its newest deployment')
+    return { slug: slug.trim(), deployment: deployment.trim() || null }
+  })
+}
+
+/** The words for a gate check's state. */
+const GATE_WORD = { passed: 'passed', failed: 'failed', missing: 'no evidence' } as const
+
+export function gateLines(gate: Gate | undefined): string[] {
+  if (!gate?.checks.length) return []
+  return [
+    gate.blocking ? `Checks: ${plural(gate.blocking, 'required check')} not passed — Apply waits for them` : 'Checks: every required check passed',
+    ...gate.checks.map((c) => `  ${c.status === 'passed' ? '✓' : c.required ? '✗' : '·'} ${c.label}: ${c.detail}${c.required ? '' : ' (not required)'}${c.status === 'passed' ? '' : ` [${GATE_WORD[c.status]}]`}${c.reported ? `\n      ${c.reported}` : ''}`),
+  ]
+}
+
 const STATE_WORD: Record<string, string> = {
   draft: 'Draft',
   open: 'Proposed',
@@ -198,7 +312,7 @@ export function functionBuilder(project: Pick<LocalProject, 'root'>, ctx: Pick<C
     const at = findAutomationProjectRoot(resolve(root, entry))
     const inside = at !== null && (at === root || at.startsWith(`${root}/`))
     const tgz = inside
-      ? packDirectory(at!, ctx.output, `source of ${item.name}`).tgz
+      ? packDirectory(at!, ctx.output, `source of ${item.name}`, outsideImports(at!, resolve(root, entry))).tgz
       : createTarGz(Object.entries(item.files).map(([rel, text]) => ({ rel, bytes: new TextEncoder().encode(text) })))
     const source = Buffer.from(tgz).toString('base64')
     return { manifest, bundle: Buffer.from(code, 'utf8').toString('base64'), source }
@@ -306,6 +420,29 @@ function previewText(link: SyncLink, items: PushItem[], kept: { title: string }
   return lines.join('\n')
 }
 
+/**
+ * The release items asked for: each App resolved in the workspace, and the
+ * deployment named, or its newest one (what was deployed last, previews
+ * included) when only the slug is given.
+ */
+async function releaseItems(api: Platform, asked: Array<{ slug: string; deployment: string | null }>) {
+  const out: Array<{ ref: string; files: Record<string, string>; slug: string; deployment: string; chosen: boolean }> = []
+  for (const r of asked) {
+    let deployment = r.deployment
+    if (!deployment) {
+      const app = await api.call<{ id: string }>('GET', `/v1/platform-apps/resolve/${encodeURIComponent(r.slug)}`).catch((err: CliError) => {
+        throw err.code === 'NOT_FOUND' ? new UsageError(`the workspace has no Custom App ${r.slug}`, 'deploy it once with `frontera app deploy` in its folder, then release it') : err
+      })
+      const ledger = await api.call<{ deployments: Array<{ id: string; label: string | null; pruned: unknown }> }>('GET', `/v1/platform-apps/${app.id}/deployments`)
+      const newest = ledger.deployments.find((d) => !d.pruned)
+      if (!newest) throw new UsageError(`${r.slug} has no deployment to release`, 'deploy one with `frontera app deploy` in its folder first')
+      deployment = newest.label ?? newest.id
+    }
+    out.push({ ...releaseItem(r.slug, deployment), slug: r.slug, deployment, chosen: !r.deployment })
+  }
+  return out
+}
+
 export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; text: string }> {
   const project = localProject(ctx.cwd)
   const link = needLink(project)
@@ -367,7 +504,8 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
     })
   }
   const going = chosen.filter((i) => i.proposable)
-  if (!going.length) throw new CliError('nothing to propose: nothing changed here since the last pull', { code: 'SYNC_NOTHING_TO_PUSH', hint: 'change an item in the project first; `frontera local sync status` shows where it stands' })
+  const releaseAsks = parseReleases(flagString(ctx, 'release'))
+  if (!going.length && !releaseAsks.length) throw new CliError('nothing to propose: nothing changed here since the last pull', { code: 'SYNC_NOTHING_TO_PUSH', hint: 'change an item in the project first; `frontera local sync status` shows where it stands' })
   const title = flagString(ctx, 'title')?.trim()
   const description = flagString(ctx, 'description')
   const api = platformFor(project, link)
@@ -382,7 +520,10 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
   }
   if (!target && !title) throw new UsageError('give the change request a title', 'frontera local sync push -t "Tighten the refund procedure"')
 
-  const items = await pushBody(going, functionBuilder(project, ctx), assetUploader(project, api))
+  // Custom App releases: each names a deployment that already exists. A later push keeps the releases the request has.
+  const releases = await releaseItems(api, releaseAsks)
+  const keptReleases = target ? (await api.call<View>('GET', `/v1/change-requests/${target.id}`)).items.filter((i) => i.kind === 'app' && !releases.some((r) => r.ref === i.ref)).map((i) => ({ ref: i.ref, files: i.files })) : []
+  const items = [...(await pushBody(going, functionBuilder(project, ctx), assetUploader(project, api))), ...releases.map(({ ref, files }) => ({ ref, files })), ...keptReleases]
   let view: View
   try {
     view = target
@@ -411,13 +552,15 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
       proposed: true,
       created: !target,
       request: { id: view.request.id, title: view.request.title, state: view.request.state, items: view.items.length, refs: view.items.map((i) => i.ref) },
-      pushed: going.map((i) => i.ref),
+      pushed: [...going.map((i) => i.ref), ...releases.map((r) => r.ref)],
+      releases: releases.map((r) => ({ ref: r.ref, deployment: r.deployment })),
       notProposed: notProposed.map((i) => ({ ref: i.ref, code: i.blocked, message: i.reason })),
       organizationKey: { needed: needsOrganizationKey(view.items), stored: orgStored },
     },
     text: [
       `${target ? `Updated “${view.request.title}” in` : `Proposed “${view.request.title}” to`} ${link.workspaceName ?? link.workspace}: ${plural(view.items.length, 'item')}.`,
       ...going.map((i) => `  ${pushItemLine(i)}`),
+      ...releases.map((r) => `  Custom App ${r.slug}: release ${r.deployment}${r.chosen ? ' (its newest deployment)' : ''}; Apply promotes it last`),
       ...(notProposed.length ? ['', 'Not proposed:', ...notProposed.map((i) => `  ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`)] : []),
       ...(orgNote ? ['', orgNote] : []),
       '',
@@ -462,7 +605,11 @@ async function basesFor(project: LocalProject, link: SyncLink, view: View): Prom
       const source = sourceFor(project, link)
       const asked = item.kind === 'blueprint' ? 'blueprint' : item.ref
       const answer = await source.workspace.find<{ ref: string; kind: string; revision: string; content: Record<string, unknown> }>(`/v1/sync/item?ref=${encodeURIComponent(asked)}&revision=${encodeURIComponent(item.baseRevision)}`)
-      if (answer) out[item.ref] = { files: await projectAtRevision(source, item.ref, answer, Object.keys(item.files), directoryOf(snapshot)), known: true }
+      if (answer) {
+        const files = await projectAtRevision(source, item.ref, answer, Object.keys(item.files), directoryOf(snapshot))
+        // A Blueprint revision is the whole model: the item's base is its own file of it (`blueprint/<name>.<ext>`).
+        out[item.ref] = { files: item.kind === 'blueprint' ? Object.fromEntries(Object.entries(files).filter(([p]) => p.startsWith(`blueprint/${item.name}.`))) : files, known: true }
+      }
     } catch {
       // Shown without its base; the page says so.
     }
@@ -511,7 +658,7 @@ function activityOf(view: View, titles: Record<string, string>) {
           text = 'Apply started'
           break
         case 'apply_refused':
-          text = `Apply refused: ${plural(checksOf(d).length, 'check')} failed`
+          text = Array.isArray(d.gate) ? `Apply waited: ${plural(d.gate.length, 'required check')} not passed` : `Apply refused: ${plural(checksOf(d).length, 'check')} failed`
           break
         case 'apply_failed': {
           outcome = parseOutcome({ ok: false, steps: d.steps, failure: d.failure, compensation: d.compensation })
@@ -529,6 +676,15 @@ function activityOf(view: View, titles: Record<string, string>) {
         case 'closed':
           text = 'Closed'
           break
+        case 'gate_forced':
+          text = `Applied with ${plural(Array.isArray(d.skipped) ? d.skipped.length : 0, 'required check')} skipped (Force Apply): ${typeof d.reason === 'string' ? d.reason : ''}`
+          break
+        case 'evidence_attached':
+          text = `Attached ${typeof d.title === 'string' ? d.title : 'evidence'}`
+          break
+        case 'evidence_removed':
+          text = 'Removed a piece of evidence'
+          break
         default:
           text = e.kind.replace(/_/g, ' ')
       }
@@ -551,6 +707,7 @@ async function currentView(project: LocalProject, link: SyncLink): Promise<{ vie
  * then what its proposed files declare. The kept titles are not rewritten.
  */
 function titleOf(item: ViewItem, titles: Record<string, string>): string {
+  if (item.kind === 'app') return `${item.name} ${releasedDeployment(item) ?? ''}`.trim()
   return itemTitle(item.kind, item.name, item.files, titles[item.ref])
 }
 
@@ -577,7 +734,9 @@ async function show(ctx: CommandContext) {
       name: item.name,
       title,
       change,
-      line: itemLine({ kind: item.kind, name: item.name, title, change, changedPaths: base.known ? files.map((f) => f.path) : [], assetsChanged: Boolean(item.assets?.length) && base.known && !files.length, documentsChanged }),
+      line: item.kind === 'app'
+        ? `Custom App ${item.name}: release ${releasedDeployment(item) ?? '(no deployment)'}`
+        : itemLine({ kind: item.kind, name: item.name, title, change, changedPaths: base.known ? files.map((f) => f.path) : [], assetsChanged: Boolean(item.assets?.length) && base.known && !files.length, documentsChanged }),
       state: item.state,
       stateLabel: ITEM_STATE_WORD[item.state] ?? item.state,
       error: item.error,
@@ -586,6 +745,7 @@ async function show(ctx: CommandContext) {
       files,
       build: item.build ? { hasSource: item.build.hasSource } : null,
       ...(item.assets ? { assets: item.assets.map((a) => ({ path: a.path, bytes: a.bytes })) } : {}),
+      ...(item.grantChanges || item.disclosures ? { grantChanges: item.grantChanges ?? [], disclosures: item.disclosures ?? [] } : {}),
       ...(item.documents
         ? {
             documents: {
@@ -608,17 +768,22 @@ async function show(ctx: CommandContext) {
       activity,
       checks: checks.filter((c) => !items.some((i) => i.ref === c.ref)).map((c) => ({ ref: c.ref, code: c.code, message: c.message })),
       organizationKey: { needed: needsOrganizationKey(view.items), stored: orgStored },
+      gate: view.gate ?? null,
+      evidence: view.evidence ?? [],
     },
     text: [
       `${r.title} — ${STATE_WORD[r.state] ?? r.state} · ${plural(items.length, 'item')} · ${link.workspaceName ?? link.workspace}`,
       ...(r.description ? [r.description] : []),
       '',
-      ...items.flatMap((i) => [
+      ...items.flatMap((i, n) => [
         `  ${i.line}  (${i.stateLabel})`,
         ...(i.error ? [`      ! ${i.error}`] : []),
         ...i.checks.map((c) => `      ! ${c.message}`),
+        ...grantChangeLines(view.items[n]!),
         ...(i.baseKnown ? [] : ['      · its base isn’t on this machine; its files are shown whole']),
       ]),
+      ...(view.gate?.checks.length ? ['', ...gateLines(view.gate)] : []),
+      ...(view.evidence?.length ? ['', 'Evidence:', ...view.evidence.map((e) => `  ${e.title}${e.stale ? ' (before the last push)' : ''}`)] : []),
       '',
       'Activity:',
       ...activity.map((a) => `  ${a.at.slice(0, 16).replace('T', ' ')}  ${a.text}`),
@@ -642,10 +807,17 @@ async function apply(ctx: CommandContext) {
     throw new CliError('this change request changes the Blueprint, and applying it needs the organization key; none is stored for this project', { code: 'SYNC_NO_ORG_KEY', hint: 'connect again with `frontera local sync connect --workspace-key - --org-key -` (both keys on stdin), then apply' })
   }
   const migration = flagString(ctx, 'migration')?.trim()
+  const force = flagBool(ctx, 'force')
+  const reason = flagString(ctx, 'reason')?.trim()
+  if (force && !reason) throw new UsageError('--force needs --reason', 'frontera local sync request apply --force --reason "why it applies without its required checks"')
   let answer: View
   try {
-    answer = await platformFor(project, link).call<View>('POST', `/v1/change-requests/${view.request.id}/apply`, migration ? { migrationInstruction: migration } : {}, { organizationKey, timeoutMs: 15 * 60_000 })
+    answer = await platformFor(project, link).call<View>('POST', `/v1/change-requests/${view.request.id}/apply`, { ...(migration ? { migrationInstruction: migration } : {}), ...(force ? { force: { reason } } : {}) }, { organizationKey, timeoutMs: 15 * 60_000 })
   } catch (err) {
+    if (err instanceof CliError && err.code === 'SYNC_APPLY_GATED') {
+      const gate = (err.details as { gate?: Gate } | undefined)?.gate
+      throw new CliError(['not applied: required checks have not passed', ...gateLines(gate).slice(1).filter((l) => l.includes('✗'))].join('\n'), { code: err.code, hint: err.hint, details: err.details })
+    }
     if (err instanceof CliError && err.code === 'SYNC_CHECKS') {
       const checks = checksOf(err.details)
       throw new CliError(`not applied: ${plural(checks.length, 'check')} failed\n${checkLines(checks, allTitles).join('\n')}`, {
@@ -676,7 +848,9 @@ async function apply(ctx: CommandContext) {
     // A deletion shows only in a full read of the workspace's index (an incremental one lists no deletions).
     const deleted = answer.items.filter((i) => i.deleted).map((i) => i.ref)
     const result = await fetchFor(project, link, { full: deleted.length > 0 })
-    const { adopted } = adoptApplied(project.root, link.workspace, answer.items.map((i) => i.ref), snapshotItems(project.root, result.snapshot), readLock(project.root), new Date(), { deleted })
+    // A Custom App release moved a pointer; the App's own sync item (its description) is not the project's to adopt.
+    const adoptable = answer.items.filter((i) => i.kind !== 'app').map((i) => i.ref)
+    const { adopted } = adoptApplied(project.root, link.workspace, adoptable, snapshotItems(project.root, result.snapshot), readLock(project.root), new Date(), { deleted })
     // An Agent's lessons were proposed for review: not proposed again; the next pull brings what reviewers approve.
     adoptProposedLessons(project.root, link.workspace, answer.items.flatMap((i) => (i.ref.startsWith('lessons/') ? [i.ref.slice('lessons/'.length)] : [])))
     fetched = { changed: result.changed.length, adopted, error: null }
@@ -685,6 +859,8 @@ async function apply(ctx: CommandContext) {
   }
   // Documents applied are the project's copies of the workspace's now: recorded as a pull records them.
   await recordAppliedDocuments(project, link, answer).catch(() => null)
+  // The Agents applied: their cases' last local runs become the baseline the next request's evals compare with.
+  recordApplied(project, answer.items.filter((i) => i.kind === 'agent' && !i.deleted).map((i) => i.name))
   return {
     data: { applied: true, outcome, request: { id: answer.request.id, title: answer.request.title, state: answer.request.state }, fetched },
     text: [
@@ -740,11 +916,142 @@ async function close(ctx: CommandContext) {
   return { data: { closed: true, request: { id: view.request.id, title: view.request.title, state: view.request.state } }, text: `Closed “${view.request.title}”. The project’s files are unchanged; the next push opens a new change request.` }
 }
 
-const REQUEST_ACTIONS: Record<string, (ctx: CommandContext) => Promise<{ data: unknown; text: string }>> = { show, apply, close }
+/**
+ * Attach evidence to the current request (design 2026-10-18 §6): each Agent
+ * it changes, run on its gated cases against the local runtime and compared
+ * with its last applied run; each App it releases, by its last render; the
+ * newest screenshots of a Forge session; a trace link. With no flag, all
+ * that applies: evals and renders, and this session's screenshots inside
+ * Forge.
+ */
+async function evidence(ctx: CommandContext) {
+  const project = localProject(ctx.cwd)
+  const link = needLink(project)
+  const current = await currentView(project, link)
+  if (!current) throw new UsageError('no change request to attach evidence to', 'propose one with `frontera local sync push -t "<title>"`')
+  const { view, titles } = current
+  if (!isOpen(view.request.state)) throw new CliError(`“${view.request.title}” is ${STATE_WORD[view.request.state] ?? view.request.state}; it takes no evidence`, { code: 'CONFLICT', hint: 'propose new changes with `frontera local sync push -t "<title>"`' })
+  const session = flagString(ctx, 'screenshots') ?? process.env.FORGE_SESSION ?? null
+  const trace = flagString(ctx, 'trace')
+  const any = flagBool(ctx, 'evals') || flagBool(ctx, 'renders') || flagString(ctx, 'screenshots') !== undefined || trace !== undefined
+  const want = { evals: any ? flagBool(ctx, 'evals') : true, renders: any ? flagBool(ctx, 'renders') : true, screenshots: any ? flagString(ctx, 'screenshots') !== undefined : !!session }
+  const api = platformFor(project, link)
+  const attach = (body: Record<string, unknown>) => api.call<View>('POST', `/v1/change-requests/${view.request.id}/evidence`, body, { timeoutMs: 120_000 })
+  const lines: string[] = []
+  const attached: Array<{ kind: string; ref: string | null; title: string }> = []
+  const skipped: string[] = []
+
+  if (want.evals) {
+    const agents = view.items.filter((i) => i.kind === 'agent' && !i.deleted)
+    if (agents.length) {
+      const runtime = runtimeLink(project)
+      if (typeof runtime === 'string') throw new CliError(`the evals run against the local runtime: ${runtime}`, { code: 'LOCAL_NOT_RUNNING', hint: 'start it with `frontera local start`, or attach only renders and screenshots with `--renders --screenshots <session>`' })
+      const applied = readAppliedRun(project)
+      const last = readLastRun(project)
+      for (const item of agents) {
+        // Chosen as `local test` and MCP `test_run { gate: true }` choose them, and run on what the files say:
+        // a draft that isn't fails its cases with what to run, as there.
+        const files = selectCaseFiles(project.root, { agent: item.name, gate: true })
+        const results = files.length ? await runCases({ serviceUrl: runtime.serviceUrl, creds: runtime.creds, files, live: false, staleDraft: (slug) => agentFilesProblem(project, runtime.creds.organizationId, slug), onResult: () => {} }) : []
+        // Compared with the run when the Agent was last applied from here; never applied from here, with the last run.
+        const baseline = Object.keys(applied).some((k) => k.startsWith(`${item.name}\u0000`)) ? applied : last
+        const detail = evalsDetail({ files, results, baseline, runtime: `local ${runtime.state.version ?? ''}`.trim() })
+        if (results.length) recordRun(project, results)
+        // Cases that couldn't run (the provider refused them) prove nothing either way: attached, they would read as none newly failing.
+        if (detail.couldNotRun.length) {
+          skipped.push(evalsLine(`Evals · ${titleOf(item, titles)}`, detail))
+          continue
+        }
+        const title = `Evals · ${titleOf(item, titles)}`
+        await attach({ kind: 'evals', ref: item.ref, candidateDigest: item.candidateDigest ?? null, title, detail })
+        attached.push({ kind: 'evals', ref: item.ref, title })
+        lines.push(`  ${evalsLine(titleOf(item, titles), detail)}`)
+      }
+    }
+  }
+
+  if (want.renders) {
+    const apps = findAppProjects(project.root)
+    for (const item of view.items.filter((i) => i.kind === 'app')) {
+      const app = apps.find((a) => a.slug === item.name)
+      const render = app ? lastRender(app.root) : null
+      if (!render) {
+        skipped.push(`${item.name}: no render in this project yet (render it with the coding agent's app_render, or open it in Forge's Browser)`)
+        continue
+      }
+      const big = render.image && render.image.byteLength > 2 * 1024 * 1024
+      const title = `Render · ${item.name}${typeof render.detail.path === 'string' ? ` ${render.detail.path}` : ''}`
+      await attach({ kind: 'render', ref: item.ref, title, detail: { ...render.detail, deployment: releasedDeployment(item) }, ...(render.image && !big ? { image: render.image.toString('base64') } : {}) })
+      attached.push({ kind: 'render', ref: item.ref, title })
+      lines.push(`  ${title}${big ? ' (its picture is over 2 MB and stays here)' : ''}`)
+    }
+  }
+
+  if (want.screenshots && session) {
+    const shots = sessionScreenshots(project.root, session)
+    if (!shots.length) skipped.push(`session ${session}: no screenshots saved`)
+    for (const shot of shots) {
+      if (shot.bytes > 2 * 1024 * 1024) {
+        skipped.push(`${shot.name}: over 2 MB`)
+        continue
+      }
+      const title = shot.name.replace(/\.(png|jpe?g|webp)$/i, '').replace(/[-_]+/g, ' ')
+      await attach({ kind: 'screenshot', title, detail: { session, file: shot.name }, image: readFileSync(shot.path).toString('base64') })
+      attached.push({ kind: 'screenshot', ref: null, title })
+      lines.push(`  ${title}`)
+    }
+  }
+
+  if (trace !== undefined) {
+    if (!/^https?:\/\//.test(trace)) throw new UsageError('--trace takes an http(s) address', 'frontera local sync request evidence --trace https://…/traces?trace=<id>')
+    const title = flagString(ctx, 'title')?.trim() || 'Trace'
+    await attach({ kind: 'trace', title, detail: { url: trace } })
+    attached.push({ kind: 'trace', ref: null, title })
+    lines.push(`  ${title}: ${trace}`)
+  }
+
+  const after = await api.call<View>('GET', `/v1/change-requests/${view.request.id}`)
+  recordRequest(project.root, link.workspace, after)
+  return {
+    data: { attached, skipped, gate: after.gate ?? null },
+    text: [
+      attached.length ? `Attached ${plural(attached.length, 'piece')} of evidence to “${view.request.title}”:` : `Nothing attached to “${view.request.title}”.`,
+      ...lines,
+      ...(skipped.length ? ['', 'Not attached:', ...skipped.map((l) => `  ${l}`)] : []),
+      ...(after.gate?.checks.length ? ['', ...gateLines(after.gate)] : []),
+    ].join('\n'),
+  }
+}
+
+const PICTURE_EXT: Record<string, string> = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp' }
+
+/** One evidence picture, kept on this machine (in the runtime's state folder) for Forge to show. */
+async function evidenceImage(ctx: CommandContext) {
+  const project = localProject(ctx.cwd)
+  const link = needLink(project)
+  const id = ctx.positional[2]
+  if (!id || !/^[0-9a-f-]{36}$/.test(id)) throw new UsageError('say which evidence picture', 'frontera local sync request evidence-image <evidence id>')
+  const kept = currentRequest(readRequests(project.root, link.workspace))
+  if (!kept) throw new UsageError('no change request', 'propose one with `frontera local sync push -t "<title>"`')
+  const dir = join(project.stateDir, 'evidence', kept.id)
+  for (const ext of Object.values(PICTURE_EXT)) {
+    const path = join(dir, `${id}.${ext}`)
+    if (existsSync(path)) return { data: { path, mime: Object.entries(PICTURE_EXT).find(([, e]) => e === ext)![0] }, text: path }
+  }
+  const { bytes, mime } = await platformFor(project, link).bytes(`/v1/change-requests/${kept.id}/evidence/${id}/content`)
+  const ext = PICTURE_EXT[mime.split(';')[0]!.trim()]
+  if (!ext) throw new CliError('the platform did not answer with a picture', { code: 'UNAVAILABLE', hint: 'run the command again' })
+  mkdirSync(dir, { recursive: true })
+  const path = join(dir, `${id}.${ext}`)
+  writeFileSync(path, bytes)
+  return { data: { path, mime }, text: path }
+}
+
+const REQUEST_ACTIONS: Record<string, (ctx: CommandContext) => Promise<{ data: unknown; text: string }>> = { show, apply, close, evidence, 'evidence-image': evidenceImage }
 
 export async function syncRequest(ctx: CommandContext): Promise<{ data: unknown; text: string }> {
   const action = ctx.positional[1] ?? 'show'
   const run = REQUEST_ACTIONS[action]
-  if (!run) throw new UsageError(`unknown request action \`${action}\``, 'use show, apply or close')
+  if (!run) throw new UsageError(`unknown request action \`${action}\``, 'use show, evidence, apply or close')
   return run(ctx)
 }