@frontera-sdk/cli 1.53.21 → 1.53.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.53.21",
+  "version": "1.53.22",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -40,8 +40,8 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
     "@faker-js/faker": "10.6.0",
-    "@frontera-sdk/core": "1.53.21",
-    "@frontera-sdk/functions": "1.53.21",
+    "@frontera-sdk/core": "1.53.22",
+    "@frontera-sdk/functions": "1.53.22",
     "ai": "^6.0.319",
     "axe-core": "4.12.1",
     "gray-matter": "^4.0.3",
@@ -49,7 +49,7 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.53.21",
+    "@frontera-sdk/forge-contracts": "1.53.22",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/commands/app/dev.ts

@@ -26,6 +26,7 @@ import { keepDevWrittenFiles, leftLine, putBackLine } from '../../local/local-ap
 import { setAsideCopyPaths } from '../../local/local-app-sdk-paths'
 import { ensureProjectApp, requireProjectFrom } from './shared'
 import { flagBool, flagString, type Command, type CommandContext, type CommandResult } from '../types'
+import { recordExit } from '../../telemetry/cli-telemetry'
 
 const DEFAULT_PORT = 3000
 const READY_TIMEOUT_MS = 30_000
@@ -264,14 +265,20 @@ export const appDev: Command = {
       throw error
     }
 
+    const childStarted = Date.now()
     let stopped = false
+    // The signal that stopped this command, for `frontera.cli.process_exit`: an agent's time limit ends it with SIGTERM.
+    let received: string | null = null
     const stop = () => {
       if (stopped) return
       stopped = true
       child.kill('SIGTERM')
       broker?.server.stop(true)
     }
-    const onSignal = () => stop()
+    const onSignal = (signal: NodeJS.Signals) => {
+      received ??= signal
+      stop()
+    }
     process.on('SIGINT', onSignal)
     process.on('SIGTERM', onSignal)
     // Started by an MCP session (`app_dev`, `app_render`) or Forge (its Start): it stops when that process ends,
@@ -316,6 +323,7 @@ export const appDev: Command = {
         text: `Stopped ${app.slug} local development server.`,
       }
     } finally {
+      const asked = stopped
       unwatch?.()
       process.off('SIGINT', onSignal)
       process.off('SIGTERM', onSignal)
@@ -324,6 +332,7 @@ export const appDev: Command = {
       // Once the framework's server has exited (or after a while, whatever it does), what it wrote goes back.
       // Unref'd: a pending wait would hold this process open for the whole STOP_WAIT_MS after the server exited.
       await Promise.race([child.exited, new Promise((resolve) => setTimeout(resolve, STOP_WAIT_MS).unref())])
+      recordExit('app_dev', { startedAt: childStarted, expected: asked, exitCode: child.exitCode, signal: received ?? child.signalCode })
       const { putBack, left } = kept.atStop()
       for (const line of [putBackLine(putBack, 'stopped'), leftLine(left)]) if (line) ctx.output.note(`[dev] ${line}`)
       if (aside) ctx.output.note(`[dev] ${aside.restore()}`)

package/src/commands/local/dev.ts

@@ -68,6 +68,9 @@ import { failedForRuntime, RUNTIME_DOWN_ERROR, RUNTIME_STOPPED_LINE, runtimeAnsw
 import { noticeLines, projectNotices } from '../../local/local-project-notices'
 import { refreshVendoredSdk, vendoredSdkState } from '../../local/local-vendored-sdk'
 import { flagBool, type Command, type CommandContext } from '../types'
+import { applyEvents } from '../../telemetry/apply-events'
+import { recordExit } from '../../telemetry/cli-telemetry'
+import type { ApplyTrigger } from '../../telemetry/events'
 import { isSharedFunctionFile } from '../../local/local-function-shared'
 import { applyApp } from '../../local/local-apps'
 import { applyBrand, brandUpload } from '../../local/local-brand'
@@ -86,6 +89,15 @@ import { actionFailureLines, dedupeLines, hasIndexedPaths, nameIndexedPaths, ref
 
 const DEBOUNCE_MS = 300
 
+/** How Activity words what started a round; a round started by saved files names them (`filesChangedTrigger`). */
+const TRIGGER_WORDS: Record<Exclude<ApplyTrigger, 'files_changed'>, string> = {
+  once: 'frontera local dev --once',
+  runtime_started: 'runtime started',
+  dev_started: 'frontera local dev started',
+  runtime_answering: 'the runtime is answering again',
+  restore: 'the database was restored to its baseline',
+}
+
 /** How many Blueprint artifacts one apply may leave off for the runtime's refusals before it says the Blueprint failed. */
 const MAX_REFUSED = 12
 
@@ -858,13 +870,14 @@ async function dev(ctx: CommandContext) {
   let runtimeDown = false
   // What starts the next round of applies, for Activity: the files queued since the last one, or a reason of its own.
   const changedFiles = new Set<string>()
-  let nextTrigger: string | null = null
+  let nextTrigger: ApplyTrigger | null = null
+  const events = applyEvents(project)
   /**
    * The round under way, once it applies something: a round that finds every
    * queued item unchanged applies nothing, so it never says "Applying" and is
    * never recorded as an apply.
    */
-  let round: { since: string | null; trigger: string; applied: number; failed: number } = { since: null, trigger: '', applied: 0, failed: 0 }
+  let round: { since: string | null; cause: ApplyTrigger; trigger: string; queued: number; startedAt: number; applied: number; failed: number } = { since: null, cause: 'files_changed', trigger: '', queued: 0, startedAt: 0, applied: 0, failed: 0 }
   const markApplying = () => {
     if (round.since) return
     round.since = new Date().toISOString()
@@ -936,6 +949,7 @@ async function dev(ctx: CommandContext) {
         ctx.output.note(`  ✕ ${line}`)
         recordBuild(project, organizationId, target.key, { what: describeTarget(target), status: 'blocked', needs: [], error: line, hash, at: new Date().toISOString() })
         failing.set(target.key, { item: describeTarget(target), error: line })
+        events.item(target, 'stopped', round.cause, 0)
       }
       return
     }
@@ -955,6 +969,7 @@ async function dev(ctx: CommandContext) {
       failing.set(target.key, { item: describeTarget(target), error: RUNTIME_DOWN_ERROR })
       recordBuild(project, organizationId, target.key, { what: describeTarget(target), status: 'failed', error: RUNTIME_DOWN_ERROR, hash, at: new Date().toISOString() })
       ctx.output.note(`  ✕ ${describeTarget(target)}: ${RUNTIME_STOPPED_LINE}`)
+      events.item(target, 'runtime_down', round.cause, Date.now() - started)
       return
     }
     if (!result.ok && target.kind === 'blueprint') result = { ...result, output: await blueprintFailureOutput(project, result.output, serviceUrl) }
@@ -968,6 +983,7 @@ async function dev(ctx: CommandContext) {
       saveHashes(project, organizationId, applied)
       failed.delete(target.key)
       failing.delete(target.key)
+      events.item(target, 'applied', round.cause, ms)
       ctx.output.note(`  ✓ ${describeTarget(target)} applied (${ms} ms)`)
       if (target.kind === 'blueprint') personasDue = true
       if (target.kind === 'workflow' && promoteAfter.delete(target.key)) {
@@ -1035,6 +1051,7 @@ async function dev(ctx: CommandContext) {
       // "unchanged" afterwards, even when it is restored to what last applied.
       if (applied.delete(target.key)) saveHashes(project, organizationId, applied)
       failed.set(target.key, target)
+      events.item(target, 'failed', round.cause, ms, { output: result.output })
       // A retry that fails the same way is not said again in the same round of changes.
       // A governed Action's checks are each a line to fix: shown whole, not cut to the first seven lines.
       const text = result.failureLines ? result.failureLines.map((l, i) => (i ? `      ${l}` : l)).join('\n') : applyErrorText(result.output)
@@ -1098,7 +1115,8 @@ async function dev(ctx: CommandContext) {
     if (busy) return
     busy = true
     // Why this round runs; "Applying" is said only once an item actually applies (`markApplying`).
-    round = { since: null, trigger: nextTrigger ?? filesChangedTrigger(changedFiles), applied: 0, failed: 0 }
+    const cause = nextTrigger ?? 'files_changed'
+    round = { since: null, cause, trigger: cause === 'files_changed' ? filesChangedTrigger(changedFiles) : TRIGGER_WORDS[cause], queued: pending.size, startedAt: Date.now(), applied: 0, failed: 0 }
     nextTrigger = null
     changedFiles.clear()
     said.clear()
@@ -1119,7 +1137,11 @@ async function dev(ctx: CommandContext) {
               waiting.set(next.key, next)
               failing.set(next.key, { item: describeTarget(next), error: RUNTIME_DOWN_ERROR })
               ctx.output.note(`  ✕ ${describeTarget(next)}: ${RUNTIME_STOPPED_LINE}`)
-            } else ctx.output.note(`  ✕ ${describeTarget(next)}: ${(err as Error).message}`)
+              events.item(next, 'runtime_down', round.cause, 0)
+            } else {
+              ctx.output.note(`  ✕ ${describeTarget(next)}: ${(err as Error).message}`)
+              events.item(next, 'failed', round.cause, 0, { error: err })
+            }
           }
         }
         if (runtimeDown) {
@@ -1166,6 +1188,7 @@ async function dev(ctx: CommandContext) {
       if (round.since) {
         recordApply(project, { since: round.since, finished: new Date().toISOString(), trigger: round.trigger, applied: round.applied, failed: round.failed })
         recordApplying(project, null)
+        events.round({ trigger: round.cause, queued: round.queued, applied: round.applied, failed: round.failed, ms: Date.now() - round.startedAt })
       }
       // A file saved after the queue emptied, before this round ended: its own round.
       if (pending.size && !stopping && !runtimeDown) schedule()
@@ -1181,7 +1204,7 @@ async function dev(ctx: CommandContext) {
   const resumeWaiting = () => {
     if (!waiting.size) return
     ctx.output.note(`  the local runtime is answering again: applying the ${waiting.size === 1 ? 'item' : `${waiting.size} items`} it missed`)
-    nextTrigger ??= 'the runtime is answering again'
+    nextTrigger ??= 'runtime_answering'
     for (const [key, target] of waiting) {
       pending.set(key, target)
       failing.delete(key)
@@ -1216,7 +1239,7 @@ async function dev(ctx: CommandContext) {
     if (!changed.size) {
       if (appsAwayByRestore(project.root).length) {
         secretsDue = true
-        nextTrigger = 'the database was restored to its baseline'
+        nextTrigger = 'restore'
         if (!busy) schedule()
         return
       }
@@ -1225,7 +1248,7 @@ async function dev(ctx: CommandContext) {
       return
     }
     secretsDue = true
-    nextTrigger = 'the database was restored to its baseline'
+    nextTrigger = 'restore'
     for (const t of allTargets(project.root)) if (changed.has(t.key)) pending.set(t.key, t)
     ctx.output.note(`  the database was restored to its baseline: applying ${changed.size === 1 ? 'one item' : `${changed.size} items`} applied since then again`)
     if (!busy) schedule()
@@ -1375,6 +1398,7 @@ async function dev(ctx: CommandContext) {
   const targets = allTargets(project.root)
   // Outcomes of files that are gone are forgotten, so the home lists what the project holds.
   pruneBuild(project, organizationId, new Set(targets.map((t) => t.key)))
+  events.keep(new Set(targets.map((t) => t.key)))
   // An Agent, workflow or Function whose file was deleted is taken out of service here, as the files now say.
   await sweepOrphans()
   await clearDeletedBehavior()
@@ -1399,7 +1423,7 @@ async function dev(ctx: CommandContext) {
   for (const target of targets) pending.set(target.key, target)
   // The first round: the runtime just started (Forge starts this watcher with it), or `local dev` was run by hand.
   const startedAt = Date.parse(state.startedAt ?? '')
-  nextTrigger = once ? 'frontera local dev --once' : Number.isFinite(startedAt) && Date.now() - startedAt < 5 * 60_000 ? 'runtime started' : 'frontera local dev started'
+  nextTrigger = once ? 'once' : Number.isFinite(startedAt) && Date.now() - startedAt < 5 * 60_000 ? 'runtime_started' : 'dev_started'
   await drain()
   if (unchanged) ctx.output.note(`  ${unchanged} unchanged since the last apply (--reapply applies them again)`)
   await sayProjectSecrets()
@@ -1453,17 +1477,18 @@ async function dev(ctx: CommandContext) {
   }, 5_000)
 
   await new Promise<void>((resolve) => {
-    const stop = () => {
+    const stop = (signal: 'SIGINT' | 'SIGTERM') => {
       stopping = true
       rmSync(pidFile, { force: true })
       if (timer) clearTimeout(timer)
       clearInterval(poller)
       watcher?.close()
       stopChildren()
+      recordExit('local_dev', { startedAt: performance.timeOrigin, expected: true, signal })
       resolve()
     }
-    process.once('SIGINT', stop)
-    process.once('SIGTERM', stop)
+    process.once('SIGINT', () => stop('SIGINT'))
+    process.once('SIGTERM', () => stop('SIGTERM'))
   })
   return { data: { applied: applied.size }, text: 'Stopped watching' }
 }

package/src/commands/registry.ts

@@ -60,6 +60,7 @@ import { localCommands } from './local/index-commands'
 import { localSnapshot } from './local/snapshot'
 import { localSteps } from './local/steps'
 import { mcpServe } from './mcp/serve'
+import { telemetryStatus } from './telemetry/status'
 
 /**
  * Flags every command accepts. Declared once so a caller never has to wonder
@@ -108,6 +109,7 @@ export const COMMANDS: readonly Command[] = [
   localSnapshot,
   localSteps,
   mcpServe,
+  telemetryStatus,
 
   appInit,
   appList,
@@ -228,6 +230,7 @@ const NOUN_SUMMARY: Readonly<Record<string, string>> = {
   forge: 'Forge — the local daemon the desktop app talks to',
   mcp: 'Frontera for coding agents — runtime, docs, Apps, browser',
   local: 'A runtime on this machine — apply, test and check the project',
+  telemetry: 'Usage and error data sent from work run inside Forge',
 }
 
 export function nounSummary(noun: string): string {

package/src/commands/telemetry/status.ts

@@ -0,0 +1,39 @@
+import { existsSync } from 'node:fs'
+
+import { listOutbox } from '../../telemetry/outbox'
+import { REASON_TEXT, telemetryMode } from '../../telemetry/enabled'
+import type { Command } from '../types'
+
+/**
+ * What this process would do with telemetry, and why. Reads the environment
+ * and the outbox folder; writes nothing and opens no connection.
+ */
+export const telemetryStatus: Command = {
+  meta: {
+    noun: 'telemetry',
+    verb: 'status',
+    args: [],
+    flags: {},
+    summary: 'Say whether this process would send usage and error data, print it, or record nothing, and why',
+    details: [
+      'Only a process Forge starts records anything: Forge names its outbox folder in FORGE_TELEMETRY_OUTBOX, and its own server sends what is there to the Frontera team. Anywhere else the CLI records nothing. FRONTERA_TELEMETRY=0 or DO_NOT_TRACK=1 switches it off; FRONTERA_TELEMETRY=log prints each event to stderr and sends nothing.',
+    ],
+    examples: ['frontera telemetry status', 'FRONTERA_TELEMETRY=log frontera telemetry status --json'],
+    offline: true,
+    internal: true,
+  },
+  async run() {
+    const mode = telemetryMode(process.env)
+    const outbox = process.env.FORGE_TELEMETRY_OUTBOX?.trim() || null
+    const files = outbox ? listOutbox(outbox) : []
+    const waiting = { open: 0, closed: 0, sending: 0 }
+    for (const f of files) waiting[f.state] += 1
+    // Forge removes the folder when its switch goes off; a process started before keeps the variable but writes nothing.
+    const now = mode.mode === 'send' && !existsSync(mode.outbox) ? { mode: 'off', reason: 'outbox_gone', why: 'started by Forge, which has switched telemetry off since (the outbox folder is gone): nothing is recorded' } : { mode: mode.mode, reason: mode.reason, why: REASON_TEXT[mode.reason] }
+    const where = outbox ? `outbox: ${outbox} (${waiting.closed} waiting to be sent, ${waiting.sending} being sent, ${waiting.open} being written)` : 'outbox: none (FORGE_TELEMETRY_OUTBOX is not set)'
+    return {
+      data: { ...now, outbox, files: waiting },
+      text: [`Telemetry: ${now.mode}`, `  ${now.why}`, `  ${where}`].join('\n'),
+    }
+  },
+}

package/src/local/local-supervisor.ts

@@ -46,6 +46,7 @@ import type { LocalProject } from './local-project'
 import { startLocalEmbeddings } from './local-embeddings'
 import { LOCAL_TRACE_KEYS, startLocalTraces } from './local-traces'
 import { recordRuntime } from './local-runtime-history'
+import { recordExit } from '../telemetry/cli-telemetry'
 import { buildDocs, checkoutDocsStale, copyDocs, customerDocsBundle, IMAGE_DOCS_PATH, writeDocsBuildMarker } from './local-docs'
 import { keepSchemas, type SchemaSource } from './local-schemas'
 import { applyModelKeys, ensureBlueprint, ensureOrgKey, ensureProviderModels, retireLocalModel, seedLocalRuntime, signIn } from './local-seed'
@@ -139,7 +140,7 @@ export async function runSupervisor(project: LocalProject, ports: PortBlock, ses
   const running: Running = { children: new Map(), containers: new Set() }
   let stopping = false
 
-  const shutdown = async (code: number) => {
+  const shutdown = async (code: number, signal?: NodeJS.Signals) => {
     if (stopping) return
     stopping = true
     state = { ...state, phase: 'stopping' }
@@ -157,10 +158,11 @@ export async function runSupervisor(project: LocalProject, ports: PortBlock, ses
     if (code === 0) recordRuntime(project, { event: 'stopped', at: new Date().toISOString() })
     state = { ...state, phase: 'stopped', supervisorPid: undefined }
     save()
+    recordExit('runtime', { startedAt: performance.timeOrigin, expected: code === 0, exitCode: code, signal })
     process.exit(code)
   }
-  process.on('SIGTERM', () => void shutdown(0))
-  process.on('SIGINT', () => void shutdown(0))
+  process.on('SIGTERM', () => void shutdown(0, 'SIGTERM'))
+  process.on('SIGINT', () => void shutdown(0, 'SIGINT'))
 
   const fail = async (name: ComponentName, detail: string) => {
     set(name, { status: 'failed', detail })
@@ -299,9 +301,11 @@ export async function runSupervisor(project: LocalProject, ports: PortBlock, ses
 
   // Watch native children: a crash is reported, not hidden.
   for (const [name, child] of running.children) {
-    child.on('exit', (code) => {
+    const startedAt = Date.parse(state.components.find((c) => c.name === name)?.startedAt ?? '') || Date.now()
+    child.on('exit', (code, signal) => {
       if (stopping) return
       set(name, { status: 'failed', pid: undefined, detail: `exited with code ${code ?? 'signal'}; see \`frontera local logs ${name}\`` })
+      recordExit(name, { startedAt, expected: false, exitCode: code, signal })
     })
   }
 
@@ -311,6 +315,7 @@ export async function runSupervisor(project: LocalProject, ports: PortBlock, ses
       probe: () => portAnswers(ports.jobs, 3_000),
       restart: async () => {
         if (stopping) return
+        recordExit('jobs', { startedAt: Date.parse(state.components.find((c) => c.name === 'jobs')?.startedAt ?? '') || performance.timeOrigin, expected: false })
         const restarted = await restartJobs(project, state, 'it stopped answering, so the supervisor restarted it')
         set('jobs', { status: 'running', startedAt: new Date().toISOString(), detail: undefined })
         appendFileSync(logPath(project, 'studio'), `[supervisor] jobs engine restarted in ${restarted.ms} ms${restarted.lost ? `; ${restarted.lost} lost runs marked failed` : ''}${restarted.note ? `; ${restarted.note}` : ''}\n`)

package/src/main.ts

@@ -16,6 +16,9 @@ import { remoteFromLocalProject, remoteWords } from './remote-guard'
 import { createOutput, type OutputMode } from './output'
 import { readProject } from './project'
 import { commandScope, unaddressedWorkspaceRefusal } from './scopes'
+import { cliTelemetry, INTERRUPTED, invocationVia, projectHashAt, severityOfExit, TERMINATED } from './telemetry/cli-telemetry'
+import { isBackground } from './telemetry/enabled'
+import { errorCode, errorFields } from './telemetry/redact'
 import {
   aliasesFor,
   describeCommand,
@@ -75,7 +78,70 @@ async function resolveVersion(): Promise<string> {
   return import.meta.dir.includes('/node_modules/') ? version : `${version}-dev`
 }
 
+/**
+ * What `frontera.cli.command` says of this process, filled in as dispatch
+ * learns it: registered names only, flag names without their values.
+ */
+const invocation: { noun: string; verb: string; flags: string[]; names: string[]; cwd: string; failure?: unknown } = { noun: 'unknown', verb: '', flags: [], names: [], cwd: process.cwd() }
+
+let recorded = false
+
+/** Once per process, when it ends or is stopped with Ctrl+C; never fails or slows the command. */
+function recordCommand(exitCode: number): void {
+  if (recorded) return
+  recorded = true
+  try {
+    // Forge's own poll that succeeded says nothing anyone did.
+    if (exitCode === 0 && isBackground(process.env)) return
+    const telemetry = cliTelemetry()
+    if (telemetry.mode.mode === 'off') return
+    const { failure } = invocation
+    const error = failure === undefined ? undefined : errorFields(errorCode((failure as { code?: unknown })?.code), failure instanceof Error ? failure.message : String(failure), invocation.names)
+    const project = projectHashAt(invocation.cwd)
+    telemetry.record({
+      name: 'frontera.cli.command',
+      severity: severityOfExit(exitCode),
+      attributes: {
+        'frontera.noun': invocation.noun,
+        'frontera.verb': invocation.verb,
+        'frontera.flags': [...new Set(invocation.flags)].sort().join(','),
+        'frontera.exit_code': exitCode,
+        'frontera.via': invocationVia(process.env),
+        duration_ms: Math.round(performance.now()),
+        ...(project ? { 'frontera.project.hash': project } : {}),
+      },
+      ...(error ? { error } : {}),
+    })
+    telemetry.roll()
+  } catch {
+    // Telemetry never fails the command.
+  }
+}
+
+/**
+ * Ctrl+C or SIGTERM (Forge's time limit, an agent's shell timeout): recorded
+ * as stopped (exit 130 or 143, WARN), with how long it ran, before anything
+ * ends. A command with its own handler for the signal (`local dev`, `app dev`,
+ * the runtime supervisor, `forge serve`) still stops its own way. For it,
+ * SIGTERM is how its owner stops it normally, so only Ctrl+C is recorded as
+ * stopped. With no handler, the signal is raised again with none, so the
+ * process ends exactly as the default would (the shell says 130 or 143).
+ */
+const STOPPED = { SIGINT: INTERRUPTED, SIGTERM: TERMINATED } as const
+
+function onStop(signal: keyof typeof STOPPED): () => void {
+  const handler = () => {
+    const handled = process.listenerCount(signal) > 1
+    if (signal === 'SIGINT' || !handled) recordCommand(STOPPED[signal])
+    if (handled) return
+    process.off(signal, handler)
+    process.kill(process.pid, signal)
+  }
+  return handler
+}
+
 async function main(): Promise<number> {
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, onStop(signal))
   const argv = process.argv.slice(2)
 
   /**
@@ -112,6 +178,8 @@ async function main(): Promise<number> {
   }
 
   const remaining = argv.slice(cursor)
+  // Until a command is found, every word typed is a name to keep out of an error template.
+  invocation.names = remaining.filter((a) => !a.startsWith('-'))
 
   // Flags but no command. Showing help beats "unknown command: --api-url",
   // which reads as a typo in the flag rather than as a missing command.
@@ -126,9 +194,11 @@ async function main(): Promise<number> {
   // Bare `frontera`, `help`, `--help`, `--version` before anything that could
   // fail — help has to work with no credential and no project.
   if (!noun || noun === 'help' || noun === '--help' || noun === '-h') {
+    invocation.noun = 'help'
     return emit(describeCommands(), renderHelp)
   }
   if (noun === '--version' || noun === 'version') {
+    invocation.noun = 'version'
     const version = await resolveVersion()
     return emit({ version }, () => version)
   }
@@ -136,6 +206,8 @@ async function main(): Promise<number> {
   // Nouns with no verb (`frontera init`) take their arguments directly.
   const direct = findCommand(noun, '')
   const command = direct ?? findCommand(noun, maybeVerb)
+  if (nouns(true).includes(noun)) invocation.noun = noun
+  if (command) invocation.verb = command.meta.verb
 
   // `frontera agent --help`, or a bare `frontera agent`: list the noun's
   // commands. Without this the CLI's own hints dead-ended, since a reserved
@@ -158,6 +230,8 @@ async function main(): Promise<number> {
   const args = direct ? [maybeVerb, ...rest].filter((a): a is string => a !== undefined) : rest
   const spec = flagsFor(command.meta)
   const { positional, flags, repeated } = parseArgs(args, spec, aliasesFor(command.meta))
+  invocation.flags = Object.keys(flags)
+  invocation.names = [...positional, ...Object.values(flags).filter((v): v is string => typeof v === 'string')]
 
   if (flags.help === true) {
     return emit(describeCommand(command.meta), () => renderCommandHelp(command.meta))
@@ -185,6 +259,7 @@ async function main(): Promise<number> {
 
     const dirFlag = typeof flags.dir === 'string' ? flags.dir : undefined
     const cwd = dirFlag ?? process.cwd()
+    invocation.cwd = cwd
 
     /**
      * A missing argument outranks a missing project directory.
@@ -407,6 +482,7 @@ async function main(): Promise<number> {
     // rather than each API client rewording its own 401/403.
     const laneFailure = sessionLaneFailure(command.meta, token, err)
     const failure = (laneFailure && (await onLocalRuntime(laneFailure, command.meta, typeof flags.dir === 'string' ? flags.dir : process.cwd(), { apiUrl: apiUrlUsed, token }).catch(() => null))) ?? laneFailure ?? err
+    invocation.failure = failure
     return output.fail(personaToken ? redact(failure, personaToken) : failure)
   }
 }
@@ -423,6 +499,7 @@ main()
     process.exitCode = code
   })
   .catch((err) => {
+    invocation.failure = err
     // Only reachable for a throw outside the try — an unknown command, argument
     // parsing, or help rendering. Asked for JSON on the command line, it is JSON
     // (X10: `trace get --json` was no command, and said so only in prose).
@@ -438,3 +515,4 @@ main()
     if (err instanceof CliError && err.hint) process.stderr.write(`  ${err.hint}\n`)
     process.exitCode = code === 'USAGE' ? EXIT.USAGE : EXIT.FAILURE
   })
+  .finally(() => recordCommand(Number(process.exitCode ?? 0)))

package/src/mcp/mcp-apps.ts

@@ -138,6 +138,8 @@ export interface EnsureDevServerOptions {
   owner?: 'mcp' | 'forge' | 'detached'
   /** The port to listen on. Default: a free one from 3100. */
   port?: number
+  /** Variables for the server's process on top of this one's (Forge's telemetry outbox). */
+  env?: Record<string, string>
   /** Called once when the server this call started ends, however it ends. */
   onExit?: (exit: DevServerExit) => void
 }
@@ -291,7 +293,7 @@ export async function ensureDevServer(project: LocalProject, app: AppProjectRef,
   const from = statSync(log).size
   const [exe, ...pre] = options.command ?? selfCommand()
   const owned = options.owner !== 'detached'
-  const env: NodeJS.ProcessEnv = { ...process.env, ...credential.env, NO_COLOR: '1', ...(credential.token ? { [TOKEN_ON_STDIN_ENV]: '1' } : {}) }
+  const env: NodeJS.ProcessEnv = { ...process.env, ...options.env, ...credential.env, NO_COLOR: '1', ...(credential.token ? { [TOKEN_ON_STDIN_ENV]: '1' } : {}) }
   delete env[DEV_OWNER_ENV]
   const child = spawn(exe!, [...pre, 'app', 'dev', '--no-open', '--port', String(port)], {
     cwd: app.root,

package/src/mcp/mcp-protocol.ts

@@ -1,5 +1,8 @@
 import { createInterface } from 'node:readline'
 
+import { cliTelemetry, projectHashAt } from '../telemetry/cli-telemetry'
+import { errorCode, errorFields, outputErrorCode } from '../telemetry/redact'
+
 /**
  * The part of the Model Context Protocol `frontera mcp` speaks: JSON-RPC 2.0,
  * one message per line on stdio, with tools only. Calls run concurrently and
@@ -65,17 +68,45 @@ export async function answerMcpMessage(message: McpMessage, info: McpServerInfo,
       const input = (message.params?.arguments ?? {}) as Record<string, unknown>
       const tool = tools.find((t) => t.name === name)
       if (!tool) return reply(errorResult(`unknown tool "${name}"`))
+      const started = performance.now()
+      let result: ToolResult
+      let thrown: unknown
       try {
-        return reply(await tool.run(input))
+        result = await tool.run(input)
       } catch (err) {
-        return reply(errorResult((err as Error).message))
+        thrown = err
+        result = errorResult((err as Error).message)
       }
+      const ms = performance.now() - started
+      // After the reply is written: telemetry's file work never adds to the tool's latency.
+      setImmediate(() => recordToolCall(tool.name, input, result, thrown, ms))
+      return reply(result)
     }
     default:
       return { jsonrpc: '2.0', id: message.id, error: { code: -32601, message: `Method not found: ${String(message.method)}` } }
   }
 }
 
+/** `frontera.cli.mcp_tool`: the tool, whether it worked, how long it took, and a failure's code and template; never its input or output. */
+function recordToolCall(tool: string, input: Record<string, unknown>, result: ToolResult, thrown: unknown, ms: number): void {
+  try {
+    const telemetry = cliTelemetry()
+    if (telemetry.mode.mode === 'off') return
+    const text = result.content.find((c) => c.type === 'text')?.text ?? ''
+    const names = Object.values(input).filter((v): v is string => typeof v === 'string')
+    const code = thrown === undefined ? outputErrorCode(text) : errorCode((thrown as { code?: unknown })?.code)
+    const project = projectHashAt(process.cwd())
+    telemetry.record({
+      name: 'frontera.cli.mcp_tool',
+      severity: result.isError ? 'ERROR' : 'INFO',
+      attributes: { 'frontera.tool': tool, 'frontera.ok': !result.isError, duration_ms: Math.round(ms), ...(project ? { 'frontera.project.hash': project } : {}) },
+      ...(result.isError ? { error: errorFields(code, text, names) } : {}),
+    })
+  } catch {
+    // Telemetry never fails a tool call.
+  }
+}
+
 /** Serve over stdio until stdin closes, then wait for the calls still running. */
 export async function serveMcp(args: {
   info: McpServerInfo