@frontera-sdk/cli 1.52.45 → 1.52.46

package/src/commands/local/index-commands.ts

@@ -36,8 +36,13 @@ import { newSessionToken } from '../../local/local-studio-server'
 import { migrateMcpConfigs } from '../../local/local-scaffold'
 import { DEFAULT_REGISTRY, runSupervisor } from '../../local/local-supervisor'
 import { compareWithLastRun, readLastRun, recordRun } from '../../local/local-test-baseline'
-import { agentFilesProblem, caseConcurrency, caseCount, runCases, selectCaseFiles, waitedWords, type CaseFile, type CaseResult } from '../../local/local-test-runner'
+import { agentFilesProblem, caseConcurrency, caseCount, caseRepeat, DEFAULT_PASS_RATE, judgedWords, passRateThreshold, repeatWords, runCases, selectCaseFiles, waitedWords, type CaseFile, type CaseResult } from '../../local/local-test-runner'
+import { compareWithRun, comparisonWords, listTestRuns, readTestRun, runOnModel, saveTestRun, stuckWords } from '../../local/local-test-models'
+import { modelSubstitutions, skippedCases, skippedWords } from '../../local/local-test-scope'
 import { devServerLine, listDevServers, stopDevServers } from '../../mcp/mcp-apps'
+import { restartJobs } from '../../local/local-jobs'
+import { conversationTranscript } from '../../mcp/mcp-conversations'
+import { runtimeLink } from '../../mcp/mcp-runtime'
 import { caseTraces, evidenceLine, failingCaseEvidence } from '../../local/local-case-evidence'
 import { notRunGroups, notRunWords } from '../../local/local-case-not-run'
 import { findWorkflowTestFiles, recordWorkflowTestRun, runWorkflowTests, workflowFileState, type WorkflowTestFile, type WorkflowTestResult } from '../../local/local-workflow-tests'
@@ -54,12 +59,16 @@ import { localDocsMcp } from './docs-mcp'
 import { localInit } from './init'
 import { localKeyList, localKeyRemove, localKeySet } from './key'
 import { localModelAdd, localModelDefault, localModelRemove, localModelsAvailable, localProviderAdd, localProviderRemove, localProviders } from './providers'
+import { localPublish } from './publish'
+import { localFmt, localNew } from './new'
+import { localEmbeddings } from './embeddings'
 import { localRemove } from './remove'
 import { localSchema } from './schema'
 import { localSync } from './sync'
 import { keylessEmbeddingsStatus, KEYLESS_RETRIEVAL_NOTE } from '../../local/local-org-settings'
 import { withFix } from '../../local/fix-words'
 import { isKeyCustodianProblem, KEY_CUSTODIAN_FIX, runtimeKeyCustodianProblem } from '../../local/local-key-custodian'
+import { readLock, recentWriters, writerWords } from '../../local/local-writers'
 
 /**
  * `frontera local …`: Frontera's runtimes on this machine, for FDEs and the coding agents working with them.
@@ -353,6 +362,53 @@ export const localStop: Command = {
   run: stop,
 }
 
+/**
+ * `frontera local restart jobs`: the jobs engine alone, back (X2). The
+ * service, Studio and the App dev servers keep running, and the runs the
+ * engine lost are marked failed so they stop holding the queue.
+ */
+async function restart(ctx: CommandContext) {
+  const project = localProject(ctx.cwd)
+  const what = ctx.positional[0]
+  if (what !== 'jobs') throw new UsageError(what ? `\`local restart\` restarts the jobs engine only, not ${what}` : 'say what to restart: jobs', '`frontera local restart jobs`; `frontera local start` brings back anything else that is down')
+  const state = readState(project)
+  if (!state || state.phase !== 'ready' || !state.supervisorPid || !isAlive(state.supervisorPid)) {
+    throw new CliError('the local runtime is not running', { code: 'LOCAL_NOT_RUNNING', hint: 'start it with `frontera local start`, which starts the jobs engine too' })
+  }
+  let restarted: Awaited<ReturnType<typeof restartJobs>>
+  try {
+    restarted = await ctx.output.task('Restarting the jobs engine', () => restartJobs(project, state, 'restarted with `frontera local restart jobs`'))
+  } catch (err) {
+    throw new CliError(`the jobs engine did not restart: ${(err as Error).message}`, { code: 'LOCAL_JOBS_RESTART', hint: '`frontera local logs jobs` says why; `frontera local start` restarts the whole runtime and keeps its data' })
+  }
+  const dev = listDevServers(project).length
+  return {
+    data: { restarted: 'jobs', ms: restarted.ms, lostRuns: restarted.lost, ...(restarted.note ? { note: restarted.note } : {}), devServersKept: dev },
+    text: [
+      `The jobs engine is back (${restarted.ms} ms).${restarted.lost === null ? '' : restarted.lost ? ` ${restarted.lost} run${restarted.lost === 1 ? '' : 's'} it had open ${restarted.lost === 1 ? 'was' : 'were'} lost with it and marked failed: run ${restarted.lost === 1 ? 'it' : 'them'} again.` : ' No run was lost.'}`,
+      ...(restarted.note ? [`  note: ${restarted.note}`] : []),
+      `The service, Studio${dev ? ` and ${dev} App dev server${dev === 1 ? '' : 's'}` : ''} kept running.`,
+    ].join('\n'),
+  }
+}
+
+export const localRestart: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'restart',
+    args: [{ name: 'component', required: true, description: 'jobs: the jobs engine that runs workflows and background work' }],
+    flags: {},
+    summary: 'Restart the local runtime\'s jobs engine alone, keeping the service and App dev servers running, and fail the runs it lost',
+    details: [
+      'The jobs engine keeps its runs in memory: a run still open when it restarts has no executor any more, so it is marked failed, saying the engine restarted, and stops holding the queue. Run it again.',
+      'The runtime\'s supervisor does the same on its own when the engine stops answering on its port twice in a row (it checks every 30 seconds). `frontera local status` shows each part as it is now.',
+    ],
+    examples: ['frontera local restart jobs'],
+    offline: true,
+  },
+  run: restart,
+}
+
 /**
  * Each project object set's id on the runtime, by its file's reference, read
  * where `frontera blueprint object-sets` reads them; null when the runtime is
@@ -415,6 +471,9 @@ async function status(ctx: CommandContext) {
   const orphans = (state.phase === 'ready' && isAlive(state.supervisorPid) && state.credentials ? await projectOrphans(project, `http://127.0.0.1:${state.ports.service}`, state.credentials).catch(() => null) : null) ?? []
   // Encryption keys the runtime can't read (data keys a hosted OpenBao locked): every secret and governed Action record fails until a reset.
   const keyProblem = state.phase === 'ready' && isAlive(state.supervisorPid) ? await runtimeKeyCustodianProblem(`http://127.0.0.1:${state.ports.service}`) : null
+  // Who last changed the runtime or the files, one line per session, and the run holding the runtime (X9).
+  const writers = recentWriters(project.stateDir)
+  const lock = readLock(project.stateDir)
   return {
     data: {
       ...rest,
@@ -436,6 +495,8 @@ async function status(ctx: CommandContext) {
       // On the runtime, not in the files: each with what fixes it (`local dev` archives an Agent or workflow whose file was deleted).
       ...(orphans.length ? { notInProject: orphans } : {}),
       ...(keyProblem ? { keyCustodian: { problem: keyProblem, fix: KEY_CUSTODIAN_FIX } } : {}),
+      writers,
+      ...(lock ? { lock: { command: lock.command, session: lock.session, harness: lock.harness, since: lock.since } } : {}),
     },
     text: [
       renderStatus({ ...state, components }, project, undefined, live, setIds, personas, secrets, liveApps ?? null, down),
@@ -443,6 +504,7 @@ async function status(ctx: CommandContext) {
       ...(stuck.length ? ['', 'Knowledge', ...stuck.map((k) => `  warning: ${k.problem}`)] : []),
       ...(orphans.length ? ['', 'On the runtime, not in the project', ...orphans.map((o) => `  warning: ${orphanLine(o)}`)] : []),
       ...(devServers.length ? ['', 'App dev servers', ...devServers.map((s) => `  ${devServerLine(s)}`)] : []),
+      ...(lock || writers.length ? ['', 'Writers', ...(lock ? [`  held by \`frontera ${lock.command}\` since ${lock.since.slice(11, 19)}: other commands that change the runtime wait for it`] : []), ...writers.map((w) => `  ${writerWords(w)}`)] : []),
     ].join('\n'),
   }
 }
@@ -586,27 +648,54 @@ async function test(ctx: CommandContext) {
   }
   const serviceUrl = `http://127.0.0.1:${state.ports.service}`
   let concurrency: number | undefined
+  let repeat: number | undefined
+  let passRate: number | undefined
   try {
     concurrency = caseConcurrency(flagString(ctx, 'concurrency'))
+    repeat = caseRepeat(flagString(ctx, 'repeat'))
+    passRate = passRateThreshold(flagString(ctx, 'pass-rate'))
   } catch (err) {
-    throw new UsageError((err as Error).message, 'frontera local test --concurrency 1')
+    throw new UsageError((err as Error).message, 'frontera local test --repeat 5 --pass-rate 0.8')
   }
-  const results: CaseResult[] = total
+  if (passRate !== undefined && !repeat) throw new UsageError('--pass-rate is the share of a repeated case’s runs that must pass: give --repeat too', 'frontera local test --repeat 5 --pass-rate 0.8')
+  // L1: another model for the run, and a kept run to compare with.
+  const model = flagString(ctx, 'model')?.trim() || null
+  if (model && flagBool(ctx, 'live')) throw new UsageError('--model runs the drafts on another model; --live tests the published versions as they are', 'frontera local test --model <slug>, without --live')
+  const baselineRef = flagString(ctx, 'baseline')?.trim()
+  const baseline = baselineRef ? readTestRun(project, baselineRef) : null
+  if (baselineRef && !baseline) {
+    const kept = listTestRuns(project)
+    throw new UsageError(`no kept test run ${baselineRef}`, kept.length ? `give one of: last, last-own, last-<model>, or a run id (${kept.slice(-5).join(', ')})` : 'every `frontera local test` keeps its run; run one first')
+  }
+  const runAll = async (): Promise<CaseResult[]> => total
     ? await runCases({
         serviceUrl,
-        creds: state.credentials,
+        creds: state.credentials!,
         files,
         live: flagBool(ctx, 'live'),
         // The draft is what the files say, or the cases say what to run first.
         staleDraft: (slug) => agentFilesProblem(project, state.credentials!.organizationId, slug),
         concurrency,
+        ...(repeat ? { repeat } : {}),
+        ...(passRate ? { passRate } : {}),
         onResult: (r) => {
           // A case never sent after the run stopped is said once, below, not once each.
           if (r.notRun?.skipped) return
-          ctx.output.note(`  ${r.passed ? '✓' : r.notRun ? '–' : '✕'} ${r.agent} · ${r.name}${r.passed ? '' : r.notRun ? ` — couldn’t run: ${r.notRun.what}` : ` — ${r.reason}`}${r.passed && r.retried ? ' (run twice: the provider refused the first try for its limits)' : ''}${r.waited?.length ? ` (${waitedWords(r.waited)})` : ''} (${r.ms} ms)`)
+          ctx.output.note(`  ${r.passed ? (r.repeat?.flaky ? '~' : '✓') : r.notRun ? '–' : '✕'} ${r.agent} · ${r.name}${r.passed ? '' : r.notRun ? ` — couldn’t run: ${r.notRun.what}` : ` — ${r.reason}`}${repeatWords(r)}${judgedWords(r)}${r.passed && r.retried ? ' (run twice: the provider refused the first try for its limits)' : ''}${r.waited?.length ? ` (${waitedWords(r.waited)})` : ''} (${r.ms} ms)`)
         },
       })
     : []
+  let swap: { swapped: string[]; unchanged: string[] } | null = null
+  let results: CaseResult[]
+  if (model && total) {
+    const ran = await runOnModel(project, { serviceUrl, creds: state.credentials! }, files.map((f) => f.agent), model, async (on) => {
+      ctx.output.note(`Testing on ${model}: ${on.swapped.join(', ') || 'no Agent'}${on.unchanged.length ? ` (${on.unchanged.join(', ')} name no model and keep the runtime's default)` : ''}; each is put back after the run`)
+      return runAll()
+    })
+    swap = ran
+    results = ran.value
+    if (ran.stuck.length) ctx.output.note(`  warning: ${stuckWords(ran.stuck, model)}`)
+  } else results = await runAll()
   // What kept cases from running, once each, with its fix: never a verdict on the Agent.
   const notRun = notRunGroups(results)
   for (const g of notRun) {
@@ -629,15 +718,33 @@ async function test(ctx: CommandContext) {
   // Every case's last-turn trace beside its conversation (`--json`), passing ones included; a failing one's came with its evidence.
   const traces = await caseTraces(project, results, { known: evidence })
   const comparison = compareWithLastRun(results, readLastRun(project))
-  if (results.length) recordRun(project, results)
+  // Another model's run is not the Agents' last run: a newly failing case there says nothing of the files.
+  if (results.length && !model) recordRun(project, results)
+  const kept = results.length ? saveTestRun(project, results, model) : null
+  const against = baseline ? compareWithRun(results, baseline) : null
   // Each workflow case's last run, for Studio's Evaluations and Forge's home.
   recordWorkflowTestRun(project, workflows)
   const failed = [...results.filter((r) => !r.passed && !r.notRun).map((f) => `${f.agent} · ${f.name}`), ...workflows.filter((r) => !r.passed).map((f) => `workflow ${f.workflow} · ${f.name}`)]
   const notRunCount = notRun.reduce((n, g) => n + g.cases.length, 0)
   const passed = results.length + workflows.length - failed.length - notRunCount
   const newly = comparison.newlyFailing.length ? `, ${comparison.newlyFailing.length} newly failing since the last run` : ''
-  const summary = `${passed} passed, ${failed.length} failed${newly}${notRun.length ? `, ${notRunWords(notRun)}` : ''}`
-  const data = { passed, failed: failed.length, ...(notRun.length ? { notRun: notRunCount, couldNotRun: notRun.map((g) => ({ what: `couldn’t run: ${g.what}`, fix: g.fix, cases: g.cases, ...(g.skipped ? { notSent: g.skipped } : {}) })) } : {}), fixed: comparison.fixed.length, results: results.map((r, i) => ({ ...r, ...traces.get(i), ...evidence.get(i) })), workflows }
+  // What the run left out, and why; the cases whose `judged` expectations weren't graded; Agents on another model here (X1).
+  const skipped = skippedCases(project.root, { ...(agent ? { agents: [agent] } : {}), ...(file ? { file } : {}), regression })
+  const flaky = results.filter((r) => r.repeat?.flaky)
+  const ungraded = results.filter((r) => r.judgedNotGraded)
+  const models = modelSubstitutions(project, state.credentials.organizationId, results.map((r) => r.agent))
+  for (const line of models) ctx.output.note(`  note: ${line}`)
+  if (ungraded.length) ctx.output.note(`  ${ungraded.length} case${ungraded.length === 1 ? '’s' : 's’'} judged expectations weren't graded: ${ungraded[0]!.judgedNotGraded}`)
+  if (against && baseline) {
+    ctx.output.note(`  ${comparisonWords(against, baseline)}`)
+    for (const r of against.newlyFailing) ctx.output.note(`    newly failing: ${r.agent} · ${r.name}`)
+    for (const r of against.fixed) ctx.output.note(`    fixed: ${r.agent} · ${r.name}`)
+  }
+  const summary = `${passed} passed${flaky.length ? ` (${flaky.filter((r) => r.passed).length} flaky)` : ''}, ${failed.length} failed${model ? ` on ${model}` : ''}${model ? '' : newly}${notRun.length ? `, ${notRunWords(notRun)}` : ''}${repeat && repeat > 1 ? `; each case run ${repeat} times` : ''}${skippedWords(skipped.filter((s) => !/other Agents/.test(s.reason))) ? `; ${skippedWords(skipped.filter((s) => !/other Agents/.test(s.reason)))}` : ''}`
+  // `--transcripts`: each case's whole conversation, turn by turn, as `conversation get` reads it (N7).
+  const link = flagBool(ctx, 'transcripts') ? runtimeLink(project) : null
+  const transcripts = typeof link === 'object' && link ? await Promise.all(results.map((r) => (r.conversationId ? conversationTranscript(link, r.conversationId).catch(() => null) : Promise.resolve(null)))) : []
+  const data = { passed, failed: failed.length, ...(model ? { model, ...(swap ? { onModel: swap.swapped, ownModel: swap.unchanged } : {}) } : {}), ...(kept ? { run: kept.id } : {}), ...(against && baseline ? { baseline: { run: baseline.id, model: baseline.model, newlyFailing: against.newlyFailing.map((r) => `${r.agent} · ${r.name}`), fixed: against.fixed.map((r) => `${r.agent} · ${r.name}`), stillFailing: against.stillFailing.map((r) => `${r.agent} · ${r.name}`) } } : {}), ...(repeat && repeat > 1 ? { repeat, passRate: passRate ?? DEFAULT_PASS_RATE, flaky: flaky.map((r) => `${r.agent} · ${r.name}`) } : {}), ...(skipped.length ? { skipped } : {}), ...(models.length ? { modelSubstitutions: models } : {}), ...(ungraded.length ? { judgedNotGraded: ungraded.map((r) => `${r.agent} · ${r.name}`) } : {}), ...(notRun.length ? { notRun: notRunCount, couldNotRun: notRun.map((g) => ({ what: `couldn’t run: ${g.what}`, fix: g.fix, cases: g.cases, ...(g.skipped ? { notSent: g.skipped } : {}) })) } : {}), fixed: comparison.fixed.length, results: results.map((r, i) => ({ ...r, ...traces.get(i), ...evidence.get(i), ...(transcripts[i] ? { transcript: transcripts[i]!.turns } : {}) })), workflows }
   if (failed.length || notRun.length) {
     // Only cases that couldn't run: the run did not pass, and the cause is the provider's or the runtime's, not the Agent's.
     const onlyNotRun = !failed.length
@@ -662,14 +769,24 @@ export const localTest: Command = {
     noun: 'local',
     verb: 'test',
     args: [],
-    flags: { agent: 'string', workflow: 'string', file: 'string', live: 'boolean', regression: 'boolean', concurrency: 'string' },
-    flagHelp: { file: 'run only this case file, by its path from the project root: agents/<slug>/evals/<name>.yaml or workflows/tests/<slug>.yaml' },
+    flags: { agent: 'string', workflow: 'string', file: 'string', live: 'boolean', regression: 'boolean', concurrency: 'string', transcripts: 'boolean', repeat: 'string', 'pass-rate': 'string', model: 'string', baseline: 'string' },
+    flagHelp: {
+      model: 'run the Agents’ cases on this catalog model: each Agent’s draft is put on it for the run and back after',
+      baseline: 'compare with a kept run: last, last-own (the newest on the Agents’ own models), last-<model>, or a run id',
+      file: 'run only this case file, by its path from the project root: agents/<slug>/evals/<name>.yaml or workflows/tests/<slug>.yaml',
+      transcripts: 'with --json, each case’s whole conversation: every turn, tool call, procedure and reply check',
+      repeat: 'run each Agent case N times (1 to 10) and report its pass rate; one that passes some runs is flaky',
+      'pass-rate': 'with --repeat, the share of runs a flaky case must pass (default 0.8, or 80%)',
+    },
     summary: 'Run the project\'s Agent test cases and workflow tests against the local runtime',
     details: [
       '`--file` runs one case file, by its path from the project root: an Agent\'s (agents/<slug>/evals/<name>.yaml) or a workflow\'s (workflows/tests/<slug>.yaml), the same file MCP `test_run` takes. A path that names no case file is refused.',
+      '`--repeat N` runs each Agent case N times and reports how many runs passed. A case that passes some runs and fails others is flaky: it passes when it passes at least `--pass-rate` of its runs (default 80%), and fails below that. Scenario cases run once.',
+      '`--model <slug>` compares models: the cases run with each Agent in scope on that catalog model, its draft swapped for the run and put back after (the files never change), and the run doesn\'t count as the Agents\' last run. Every run is kept under .frontera/local/test-runs/ with its model; `--baseline last-own` (or `last`, `last-<model>`, a run id) says which cases this run newly fails, fixed or still fails against it.',
+      'A case\'s `judged` expectations are graded on the local runtime by the expectation judge, on the model `frontera local model-default <model> --for tests` chose, once its other checks pass. When the runtime has no grading model it can use, the case says so and is graded on the rest.',
       'A workflow test runs the workflow for real on the local runtime: a governed Action one of its steps submits (an action step, or a Function step\'s code) is applied and changes the runtime\'s records when the Action runs here; one whose effect would reach another system is switched off here. The writes stay; `frontera local check` rolls back its own tests\' writes, and `frontera local snapshot save` / `restore` do it by hand. The workspace is never touched.',
     ],
-    examples: ['frontera local test', 'frontera local test --agent claims-triage', 'frontera local test --workflow claim-intake', 'frontera local test --file agents/claims-triage/evals/refunds.yaml', 'frontera local test --live', 'frontera local test --regression', 'frontera local test --concurrency 1'],
+    examples: ['frontera local test', 'frontera local test --agent claims-triage', 'frontera local test --agent claims-triage --repeat 5', 'frontera local test --model claude-haiku-5-5 --baseline last-own', 'frontera local test --workflow claim-intake', 'frontera local test --file agents/claims-triage/evals/refunds.yaml', 'frontera local test --live', 'frontera local test --regression', 'frontera local test --concurrency 1'],
     offline: true,
   },
   run: test,
@@ -701,6 +818,7 @@ export const localCommands: readonly Command[] = [
   localInit,
   localStart,
   localStop,
+  localRestart,
   localStatus,
   localLogs,
   localReset,
@@ -708,6 +826,10 @@ export const localCommands: readonly Command[] = [
   localUi,
   localDev,
   localTest,
+  localPublish,
+  localNew,
+  localFmt,
+  localEmbeddings,
   localCheck,
   localKeySet,
   localKeyList,

package/src/commands/local/new.ts

@@ -0,0 +1,78 @@
+import { CliError, UsageError } from '../../errors'
+import { formatProject, newAgentFiles, writeNewFiles } from '../../local/local-new'
+import { localProject } from '../../local/local-project'
+import { flagBool, flagString, type Command } from '../types'
+
+/**
+ * `frontera local new agent <slug>` (Forge improvement plan L8): a new
+ * Agent's folder from the scaffold's starter, or a copy of another Agent
+ * with `--like`. Only files are written; `frontera local dev` applies them.
+ */
+export const localNew: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'new',
+    args: [
+      { name: 'kind', required: true, description: '`agent`' },
+      { name: 'slug', required: true, description: 'The new Agent’s slug: its folder under agents/' },
+    ],
+    flags: { like: 'string', name: 'string', description: 'string', model: 'string', customer: 'boolean' },
+    flagHelp: {
+      like: 'start from another Agent’s files (instructions, bindings, behavior settings, cases), by its slug',
+      name: 'the Agent’s display name; defaults to the slug in words',
+      description: 'what the Agent does, as people see it',
+      model: 'the model it runs on, by its catalog slug (`frontera local models`)',
+      customer: 'it serves customers: write behavior settings (operating.json); an internal Agent has none',
+    },
+    summary: 'Write a new Agent’s files into the project, from the starter or a copy of another Agent',
+    details: ['Writes files only, and never over one that is there; `frontera local dev` applies them to the local runtime.'],
+    examples: ['frontera local new agent billing-help --name "Billing help"', 'frontera local new agent billing-help --like support-desk', 'frontera local new agent intake --customer --model gpt-5-mini'],
+    offline: true,
+  },
+  async run(ctx) {
+    const [kind, slug] = ctx.positional
+    if (kind !== 'agent') throw new UsageError(kind ? `\`local new\` makes an agent, not "${kind}"` : 'say what to make', 'frontera local new agent <slug>')
+    if (!slug) throw new UsageError('name the new Agent', 'frontera local new agent <slug>')
+    const project = localProject(ctx.cwd)
+    const like = flagString(ctx, 'like')
+    const files = newAgentFiles(project.root, slug, {
+      ...(like ? { like } : {}),
+      ...(flagString(ctx, 'name') ? { name: flagString(ctx, 'name') } : {}),
+      ...(flagString(ctx, 'description') ? { description: flagString(ctx, 'description') } : {}),
+      ...(flagString(ctx, 'model') ? { model: flagString(ctx, 'model') } : {}),
+      ...(flagBool(ctx, 'customer') ? { customer: true } : {}),
+    })
+    const written = writeNewFiles(project.root, files)
+    return {
+      data: { agent: slug, like: like ?? null, written },
+      text: [`Wrote agents/${slug}/${like ? ` from agents/${like}/` : ''}:`, ...written.map((f) => `  ${f}`), `Next: \`frontera local dev\` applies it; \`frontera local test --agent ${slug}\` runs its cases.`].join('\n'),
+    }
+  },
+}
+
+/** `frontera local fmt [path…]` (L8): the project's JSON and YAML in one shape. */
+export const localFmt: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'fmt',
+    args: [{ name: 'path...', required: false, description: 'Only these files or folders, from the project root' }],
+    flags: { check: 'boolean' },
+    flagHelp: { check: 'write nothing; exit 1 when a file would change (for CI)' },
+    summary: 'Write the project’s JSON and YAML files in one shape: two-space indents, a final newline, comments kept',
+    details: ['Reads agents/, workflows/, blueprint/, knowledge/, skills/, chat-apps/, themes/, datasets/, mcp/, apps/<slug>.json and frontera.yaml; an App’s own code is left alone. A file that can’t be read is named, with where, and left as it is.'],
+    examples: ['frontera local fmt', 'frontera local fmt agents/support-desk', 'frontera local fmt --check'],
+    offline: true,
+  },
+  async run(ctx) {
+    const project = localProject(ctx.cwd)
+    const check = flagBool(ctx, 'check')
+    const outcome = formatProject(project.root, { check, only: ctx.positional })
+    const lines = [
+      ...(outcome.changed.length ? [`${check ? 'Would change' : 'Formatted'} ${outcome.changed.length} file${outcome.changed.length === 1 ? '' : 's'}:`, ...outcome.changed.map((f) => `  ${f}`)] : ['Every file is already in shape.']),
+      ...(outcome.failed.length ? ['Could not read:', ...outcome.failed.map((f) => `  ${f.path}: ${f.error}`)] : []),
+    ]
+    if (outcome.failed.length) throw new CliError(`${outcome.failed.length} file${outcome.failed.length === 1 ? '' : 's'} could not be read`, { code: 'USAGE', hint: lines.join('\n'), details: outcome })
+    if (check && outcome.changed.length) throw new CliError(`${outcome.changed.length} file${outcome.changed.length === 1 ? ' is' : 's are'} not formatted`, { code: 'FAILURE', hint: `${outcome.changed.join(', ')}: run \`frontera local fmt\``, details: outcome })
+    return { data: outcome, text: lines.join('\n') }
+  },
+}

package/src/commands/local/publish.ts

@@ -0,0 +1,34 @@
+import { CliError, UsageError } from '../../errors'
+import { localProject } from '../../local/local-project'
+import { publishLocalAgent } from '../../local/local-publish'
+import { readState } from '../../local/local-state'
+import { flagString, type Command } from '../types'
+
+/**
+ * `frontera local publish <agent>`: publish the Agent's draft on this
+ * project's local runtime (Forge improvement plan L2), so a public website
+ * key, a Chat App or a channel there talks to it. It never touches a
+ * workspace.
+ */
+export const localPublish: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'publish',
+    args: [{ name: 'agent', required: true, description: 'The Agent’s slug, its folder under agents/' }],
+    flags: { notes: 'string' },
+    flagHelp: { notes: 'what the version changes, kept with it' },
+    summary: 'Publish an Agent’s draft on the local runtime (public keys, Chat Apps and channels there use the published version)',
+    details: ['The local runtime only. The workspace’s Agent is published by a person, through a change request or on the platform.'],
+    examples: ['frontera local publish support-desk', 'frontera local publish support-desk --notes "New greeting"'],
+    offline: true,
+  },
+  async run(ctx) {
+    const slug = ctx.positional[0]
+    if (!slug) throw new UsageError('name the Agent', 'frontera local publish <agent>')
+    const project = localProject(ctx.cwd)
+    const state = readState(project)
+    if (!state || state.phase !== 'ready' || !state.credentials) throw new CliError('the local runtime is not running', { code: 'LOCAL_NOT_RUNNING', hint: 'run `frontera local start` first' })
+    const done = await publishLocalAgent({ serviceUrl: `http://127.0.0.1:${state.ports.service}`, creds: state.credentials }, slug, flagString(ctx, 'notes'))
+    return { data: done, text: `Published Agent ${slug} on the local runtime. Its public keys, Chat Apps and channels there use this version; the workspace is unchanged.` }
+  },
+}

package/src/commands/local/steps.ts

@@ -0,0 +1,105 @@
+import { UsageError } from '../../errors'
+import { FRONTERA_READ_ONLY_COMMANDS } from '../../forge/permission-rules'
+import { addPersonStep, clearSettledSteps, CREDENTIAL_WORDS, CREDENTIALS, deliveryGroups, readPersonSteps, runStepChecks, settlePersonStep, type PersonStep } from '../../local/local-person-steps'
+import { runSelf } from '../../mcp/mcp-cli'
+import { localProject } from '../../local/local-project'
+import { flagBool, flagString, type Command } from '../types'
+
+/**
+ * `frontera local steps`: the steps only the person takes (Forge improvement
+ * plan N4), kept in `.frontera/sync/person-steps.json`. The coding agent adds
+ * them (here, or with the MCP tool `person_step`); Forge shows them as one
+ * delivery card with **Run in my terminal**; the person runs each one and it
+ * is marked done. Nothing here runs a step.
+ */
+
+const ACTIONS = ['list', 'add', 'done', 'dismiss', 'reopen', 'check', 'clear'] as const
+
+function stepLines(steps: PersonStep[]): string[] {
+  return steps.flatMap((s, n) => [
+    `  ${n + 1}. ${s.command ?? `${s.changes} (in the product)`}${s.check ? ' · checks itself' : ''}`,
+    `     ${s.why} Changes: ${s.changes} Needs ${CREDENTIAL_WORDS[s.credential] ?? s.credential}. (${s.id})`,
+  ])
+}
+
+export const localSteps: Command = {
+  meta: {
+    noun: 'local',
+    verb: 'steps',
+    args: [
+      { name: 'action', required: false, description: ACTIONS.join(' | ') },
+      { name: 'arg', required: false, description: 'add: the `frontera` command; done, dismiss, reopen: the step id' },
+    ],
+    flags: { why: 'string', changes: 'string', credential: 'string', delivery: 'string', all: 'boolean' },
+    summary: 'The steps only the person takes (publishing, promoting, applying, granting, setting a secret), prepared for them to run',
+    details: [
+      'A step is one `frontera` command on one line, with why it is needed (`--why`), what it changes (`--changes`) and the credential it needs (`--credential`, one of: ' + CREDENTIALS.join(', ') + '). `--delivery` groups steps into one card, in the order they were added.',
+      'A step never chains commands and never carries a secret: a value is piped in by the person (`… --from -`). Forge shows the pending steps as a delivery card, and Run in my terminal types the command into a shell without pressing Enter.',
+      'done marks a step the person ran; dismiss one that is no longer needed; clear takes the settled ones off the list. `--all` lists the settled ones too.',
+      'An applied change request adds what it left for a person (deploying a new Action, binding a dataset, a Plugin’s secrets) as steps of its delivery, Pending in workspace in Forge. check runs each such step’s read (a read-only command, `--json`) and marks the ones it proves done; Forge runs it on a timer.',
+    ],
+    examples: [
+      'frontera local steps',
+      'frontera local steps add "<command>" --why … --changes … --credential admin',
+      'frontera local steps done ps_1a2b3c4d5e',
+    ],
+    offline: true,
+  },
+  async run(ctx) {
+    const action = (ctx.positional[0] ?? 'list') as (typeof ACTIONS)[number]
+    if (!ACTIONS.includes(action)) throw new UsageError(`\`${action}\` is not a steps action`, `use one of: ${ACTIONS.join(', ')}`)
+    const project = localProject(ctx.cwd)
+    if (action === 'add') {
+      const command = ctx.positional[1]
+      if (!command) throw new UsageError('missing the command', 'frontera local steps add "frontera app promote leads" --why "…" --changes "…" --credential "workspace admin"')
+      let added
+      try {
+        added = addPersonStep(project.root, {
+          command,
+          why: flagString(ctx, 'why') ?? '',
+          changes: flagString(ctx, 'changes') ?? '',
+          credential: flagString(ctx, 'credential') ?? '',
+          delivery: flagString(ctx, 'delivery') ?? null,
+        })
+      } catch (err) {
+        throw new UsageError(`not recorded: ${(err as Error).message}`, 'a step is one `frontera` command with --why, --changes and --credential')
+      }
+      return { data: added, text: `${added.updated ? 'Updated' : 'Added'} ${added.step.id}: ${added.step.command}\nForge shows it on the project's delivery card; the person runs it.` }
+    }
+    if (action === 'done' || action === 'dismiss' || action === 'reopen') {
+      const id = ctx.positional[1]
+      if (!id) throw new UsageError('missing the step id', '`frontera local steps` lists them')
+      let step
+      try {
+        step = settlePersonStep(project.root, id, action === 'done' ? 'done' : action === 'dismiss' ? 'dismissed' : 'pending')
+      } catch (err) {
+        throw new UsageError((err as Error).message, '`frontera local steps --all` lists every step')
+      }
+      return { data: { step }, text: `${step.id}: ${step.status}` }
+    }
+    if (action === 'check') {
+      const result = await runStepChecks(project.root, async (args) => {
+        const r = await runSelf(args, { cwd: project.root, timeoutMs: 60_000 })
+        return r.ok ? r.data : null
+      }, FRONTERA_READ_ONLY_COMMANDS)
+      const lines = [
+        result.checked ? `Checked ${result.checked} step${result.checked === 1 ? '' : 's'}; ${result.done.length} done.` : 'No pending step checks itself.',
+        ...result.done.map((s) => `  ✓ ${s.changes}`),
+        ...result.problems.map((p) => `  ! ${p.id}: ${p.problem}`),
+      ]
+      return { data: result, text: lines.join('\n') }
+    }
+    if (action === 'clear') {
+      const removed = clearSettledSteps(project.root)
+      return { data: { removed }, text: removed ? `Took ${removed} settled step${removed === 1 ? '' : 's'} off the list.` : 'No settled steps to take off.' }
+    }
+    const steps = readPersonSteps(project.root)
+    const groups = deliveryGroups(steps)
+    const settled = steps.filter((s) => s.status !== 'pending')
+    const lines = groups.length
+      ? groups.flatMap((g) => [g.delivery ? `${g.delivery}:` : 'Other steps:', ...stepLines(g.steps), ''])
+      : ['No steps wait on the person.', '']
+    if (flagBool(ctx, 'all') && settled.length) lines.push('Settled:', ...settled.map((s) => `  ${s.status === 'done' ? '✓' : '–'} ${s.command ?? s.changes} (${s.id})`))
+    return { data: { pending: groups, ...(flagBool(ctx, 'all') ? { settled } : {}) }, text: lines.join('\n').trimEnd() }
+  },
+}