@frontera-sdk/cli 1.52.45 → 1.52.47

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

@@ -4,8 +4,7 @@ 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 { packFunctionSource } from '../../pack'
 import { createTarGz } from '../../tar'
 import { functionEntry } from '../../local/local-dev-sync'
 import { adoptProposedLessons } from '../../local/local-lessons'
@@ -14,11 +13,12 @@ import { HISTORY_KINDS, projectAtRevision } from '../../local/local-sync-base'
 import { normalizeOrigin, unwrap } from '../../local/local-sync-client'
 import { getSyncKey, readLink, setModelMapping, type SyncLink } from '../../local/local-sync-link'
 import { itemTitle } from '../../local/local-sync-names'
-import { checkBody, markMissingModels, markRefused, type WorkspaceModel } from '../../local/local-sync-precheck'
+import { checkBody, markMissingModels, markRefused, needsAPerson, planOf, type ApplyStep, type WorkspaceModel } from '../../local/local-sync-precheck'
+import { afterApplyOf, recordAfterApply } from '../../local/local-person-steps'
 import { rows } from '../../local/local-sync-remote'
-import { evalsDetail, evalsLine, lastRender, sessionScreenshots } from '../../local/local-request-evidence'
+import { evalsDetail, evalsLine, lastRender, sessionScreenshots, standInInstalls } 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 { agentFilesProblem, caseRepeat, passRateThreshold, 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'
@@ -250,6 +250,27 @@ export function releaseItem(slug: string, deployment: string): { ref: string; fi
   return { ref: `app/${slug}`, files: { [`apps/${slug}.release.json`]: `${JSON.stringify({ deployment }, null, 2)}\n` } }
 }
 
+/**
+ * One item per Custom App (X6): `app/<slug>` holds its settings
+ * (`apps/<slug>.json`) and its release (`apps/<slug>.release.json`), so the
+ * settings pushed now and a release asked now or kept from the request go
+ * together; the first of a file wins.
+ */
+export function mergeAppItems<T extends { ref: string; files: Record<string, string> }>(items: T[]): T[] {
+  const out: T[] = []
+  const at = new Map<string, number>()
+  for (const item of items) {
+    const i = at.get(item.ref)
+    if (!item.ref.startsWith('app/') || i === undefined) {
+      if (item.ref.startsWith('app/')) at.set(item.ref, out.length)
+      out.push(item)
+      continue
+    }
+    out[i] = { ...item, ...out[i]!, files: { ...item.files, ...out[i]!.files } }
+  }
+  return out
+}
+
 /** The deployment a release item names. */
 export function releasedDeployment(item: Pick<ViewItem, 'name' | 'files'>): string | null {
   try {
@@ -314,7 +335,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}`, outsideImports(at!, resolve(root, entry))).tgz
+      ? packFunctionSource(at!, resolve(root, entry), ctx.output, `source of ${item.name}`).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 }
@@ -415,19 +436,20 @@ async function deletionUsers(project: LocalProject, link: SyncLink, items: PushI
  * with its reason and fix. A platform without the check leaves them to
  * Propose: `checked` says which.
  */
-async function precheck(api: Platform, items: PushItem[]): Promise<{ checked: boolean; refused: string[]; problem?: string }> {
+async function precheck(api: Platform, items: PushItem[], organizationKey: string | null): Promise<{ checked: boolean; refused: string[]; plan: ApplyStep[]; problem?: string }> {
   const body = checkBody(items)
-  if (!body.length) return { checked: true, refused: [] }
+  if (!body.length) return { checked: true, refused: [], plan: [] }
   try {
-    const answer = await api.call<{ checks?: unknown[] }>('POST', '/v1/change-requests/check', { items: body }, { timeoutMs: 120_000 })
-    return { checked: true, refused: markRefused(items, checksOf(answer)) }
+    // The organization key stored for the project, so the plan says whether it can make a Steward's steps.
+    const answer = await api.call<{ checks?: unknown[]; plan?: unknown }>('POST', '/v1/change-requests/check', { items: body, ...(organizationKey ? { organizationKey } : {}) }, { organizationKey, timeoutMs: 120_000 })
+    return { checked: true, refused: markRefused(items, checksOf(answer)), plan: planOf(answer) }
   } catch (err) {
     if (err instanceof CliError && (err.code === 'NOT_FOUND' || err.code === 'SYNC_CHECKS')) {
       // An older platform has no check; a refusal of the check itself names the items as the push would.
-      if (err.code === 'SYNC_CHECKS') return { checked: true, refused: markRefused(items, checksOf(err.details)) }
-      return { checked: false, refused: [] }
+      if (err.code === 'SYNC_CHECKS') return { checked: true, refused: markRefused(items, checksOf(err.details)), plan: [] }
+      return { checked: false, refused: [], plan: [] }
     }
-    return { checked: false, refused: [], problem: (err as Error).message.split('\n')[0] }
+    return { checked: false, refused: [], plan: [], problem: (err as Error).message.split('\n')[0] }
   }
 }
 
@@ -441,7 +463,7 @@ async function workspaceModels(api: Platform): Promise<WorkspaceModel[]> {
   }
 }
 
-function previewText(link: SyncLink, items: PushItem[], kept: { title: string } | null, orgNote: string | null, available: boolean, usedBy: Map<string, string[]> = new Map()): string {
+function previewText(link: SyncLink, items: PushItem[], kept: { title: string } | null, orgNote: string | null, available: boolean, usedBy: Map<string, string[]> = new Map(), person: ReturnType<typeof needsAPerson> = []): string {
   const ok = items.filter((i) => i.proposable && !i.sample)
   const samples = items.filter((i) => i.proposable && i.sample)
   const not = items.filter((i) => !i.proposable)
@@ -453,6 +475,10 @@ function previewText(link: SyncLink, items: PushItem[], kept: { title: string }
   ]
   if (samples.length) lines.push('', 'Samples from setting up the project, left out unless named:', ...samples.map((i) => `  [ ] ${KIND_WORD[i.kind]} ${i.title}`))
   if (not.length) lines.push('', 'Not proposed:', ...not.flatMap((i) => [`  [ ] ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`, ...(i.fix ? [`      Fix: ${i.fix}`] : [])]))
+  const before = person.filter((p) => !p.after)
+  const after = person.filter((p) => p.after)
+  if (before.length) lines.push('', 'Needs a person before Apply:', ...before.flatMap((p) => [`  - ${p.step}: ${p.message}`, `      Fix: ${p.fix}`]))
+  if (after.length) lines.push('', 'Left for a person after Apply:', ...after.flatMap((p) => [`  - ${p.step}: ${p.message}`, `      Then: ${p.fix}`]))
   if (orgNote) lines.push('', orgNote)
   if (!available) lines.push('', 'This platform does not take change requests yet.')
   if (ok.length && available) lines.push('', 'Propose with `frontera local sync push -t "<title>"`, or name items to propose only those.')
@@ -530,12 +556,13 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
   const documents = documentNames.length
     ? { names: new Set(documentNames), pulled: readPulledDocuments(project.root, link.workspace).bases, platform: await platformDocuments(platformFor(project, link), documentNames, remote.items) }
     : undefined
-  const all = pushCandidates({ root: project.root, plan, lock, snapshot, remote: remote.items, ...(documents ? { documents } : {}) })
+  const all = pushCandidates({ root: project.root, plan, lock, snapshot, remote: remote.items, named, ...(documents ? { documents } : {}) })
   // Before anything is sent: models only this computer has, then the workspace's own checks.
   const known = snapshot.names?.model ? new Set(Object.keys(snapshot.names.model)) : null
   const missing = known ? markMissingModels(all, known) : new Map<string, string[]>()
   const api = platformFor(project, link)
-  const checked = available ? await precheck(api, all) : { checked: false, refused: [] as string[] }
+  const checked = available ? await precheck(api, all, getSyncKey(project, 'organization')) : { checked: false, refused: [] as string[], plan: [] as ApplyStep[] }
+  const person = needsAPerson(checked.plan)
   const kept = currentRequest(readRequests(project.root, link.workspace))
   const updating = kept && isOpen(kept.state) ? kept : null
   const orgStored = !!getSyncKey(project, 'organization')
@@ -570,9 +597,12 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
           mapped: link.models ?? {},
         },
         organizationKey: { needed: needsOrganizationKey(chosen), stored: orgStored },
+        // Apply's steps in order, and the ones the project's credentials can't take (N3).
+        applyPlan: checked.plan,
+        needsPerson: person,
         fetchedAt: snapshot.fetchedAt,
       },
-      text: previewText(link, chosen, updating, orgNote, available, usedBy),
+      text: previewText(link, chosen, updating, orgNote, available, usedBy, person),
     }
   }
 
@@ -605,8 +635,9 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
 
   // 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]
+  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) && releasedDeployment(i)).map((i) => releaseItem(i.name, releasedDeployment(i)!)) : []
+  // An App's settings pushed now and its release go as one item (X6).
+  const items = mergeAppItems([...(await pushBody(going, functionBuilder(project, ctx), assetUploader(project, api))), ...releases.map(({ ref, files }) => ({ ref, files })), ...keptReleases])
   let view: View
   try {
     view = target
@@ -887,7 +918,8 @@ async function apply(ctx: CommandContext) {
   if (view.request.state === 'closed') throw new CliError(`“${view.request.title}” is closed`, { code: 'CONFLICT', hint: 'propose the changes again with `frontera local sync push -t "<title>"`' })
   const allTitles = Object.fromEntries(view.items.map((i) => [i.ref, titleOf(i, titles)]))
   const blueprint = view.items.some((i) => i.kind === 'blueprint')
-  const organizationKey = blueprint ? getSyncKey(project, 'organization') : null
+  // Sent whenever one is stored: an Agent's Blueprint grants are a Steward's too, in a request without Blueprint files (P5 A5).
+  const organizationKey = getSyncKey(project, 'organization')
   if (blueprint && !organizationKey) {
     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' })
   }
@@ -947,13 +979,18 @@ async function apply(ctx: CommandContext) {
   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))
+  // What the request left for a person: kept as the delivery's person-steps, which Forge shows as Pending in workspace (N6).
+  const pending = recordAfterApply(project.root, answer.request.title, afterApplyOf(answer.outcome))
   return {
-    data: { applied: true, outcome, request: { id: answer.request.id, title: answer.request.title, state: answer.request.state }, fetched },
+    data: { applied: true, outcome, request: { id: answer.request.id, title: answer.request.title, state: answer.request.state }, fetched, pendingInWorkspace: pending },
     text: [
       `Applied “${answer.request.title}” to ${link.workspaceName ?? link.workspace}.`,
       ...describeOutcome(outcome, allTitles),
       '',
       fetched.error ? `Could not fetch afterwards: ${fetched.error}. Run \`frontera local sync fetch\`.` : `Fetched: ${plural(fetched.adopted.length, 'item')} now match${fetched.adopted.length === 1 ? 'es' : ''} the workspace.`,
+      ...(pending.length
+        ? ['', `Pending in workspace (${pending.length}), for a person:`, ...pending.map((p) => `  - ${p.changes}${p.command ? `: \`${p.command}\`` : ''}${p.check ? ' (checks itself)' : ''}`), 'Forge lists them on the project’s home; `frontera local steps` here.']
+        : []),
     ].join('\n'),
   }
 }
@@ -1027,6 +1064,15 @@ async function evidence(ctx: CommandContext) {
   const attached: Array<{ kind: string; ref: string | null; title: string }> = []
   const skipped: string[] = []
 
+  // `--repeat N`: each gated case runs N times, and a flaky one passes at `--pass-rate` (X1).
+  let repeat: number | undefined
+  let passRate: number | undefined
+  try {
+    repeat = caseRepeat(flagString(ctx, 'repeat'))
+    passRate = passRateThreshold(flagString(ctx, 'pass-rate'))
+  } catch (err) {
+    throw new UsageError((err as Error).message, 'frontera local sync request evidence --repeat 3')
+  }
   if (want.evals) {
     const agents = view.items.filter((i) => i.kind === 'agent' && !i.deleted)
     if (agents.length) {
@@ -1038,10 +1084,10 @@ async function evidence(ctx: CommandContext) {
         // 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: () => {} }) : []
+        const results = files.length ? await runCases({ serviceUrl: runtime.serviceUrl, creds: runtime.creds, files, live: false, ...(repeat ? { repeat } : {}), ...(passRate ? { passRate } : {}), 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() })
+        const detail = evalsDetail({ files, results, baseline, runtime: `local ${runtime.state.version ?? ''}`.trim(), standIns: standInInstalls(project.root) })
         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) {

package/src/commands/local/sync.ts

@@ -1009,6 +1009,8 @@ export const localSync: Command = {
       force: 'boolean',
       reason: 'string',
       evals: 'boolean',
+      repeat: 'string',
+      'pass-rate': 'string',
       renders: 'boolean',
       screenshots: 'string',
       trace: 'string',

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

@@ -91,7 +91,8 @@ const list: Command = {
     verb: 'list',
     authLane: 'session',
     args: [],
-    flags: {},
+    // A local persona (L6): on the project's local runtime only.
+    flags: { as: 'string' },
     summary: 'List the Media Sets visible to you in a workspace',
     sessionAlternative: 'Blueprint → Media Sets',
     examples: ['frontera media list --workspace <workspaceId>', 'frontera media list --workspace <workspaceId> --json'],
@@ -187,7 +188,7 @@ const upload: Command = {
       { name: 'set', required: true, description: 'Media Set API name or id, from `frontera media list`' },
       { name: 'path...', required: true, description: 'files or directories; directories are walked, unsupported types skipped' },
     ],
-    flags: { markings: 'string', 'skip-existing': 'boolean' },
+    flags: { markings: 'string', 'skip-existing': 'boolean', as: 'string' },
     summary: 'Upload local files into a Media Set; the same path again adds a new version',
     sessionAlternative: 'Blueprint → Media Sets → Files',
     examples: [
@@ -316,6 +317,60 @@ const upload: Command = {
   },
 }
 
+/**
+ * A file staged for an Action to attach (L6): the Media Set's upload lane,
+ * which keeps the file out of the set until an Action request that carries
+ * the returned id applies. Pass the id as the Action's upload input.
+ */
+const stage: Command = {
+  meta: {
+    noun: 'media',
+    verb: 'stage',
+    authLane: 'session',
+    args: [
+      { name: 'set', required: true, description: 'the Media Set the Action attaches into: API name or id' },
+      { name: 'file', required: true, description: 'the file to stage' },
+    ],
+    flags: { markings: 'string', as: 'string' },
+    summary: 'Stage a file for an Action to attach; prints the id to pass as its upload input',
+    sessionAlternative: 'the Action\'s form, which stages the file it is given',
+    examples: [
+      'frontera media stage evidence photo.jpg --workspace <workspaceId>',
+      'frontera media stage evidence photo.jpg --as submitter',
+    ],
+  },
+  async run(ctx) {
+    const [ref, path] = ctx.positional
+    if (!ref || !path) throw new UsageError('missing <set> or <file>', 'frontera media stage <set> <file>')
+    const mime = MEDIA_MIME_BY_EXTENSION[extensionOf(path)]
+    if (!mime) throw new UsageError(`cannot stage ${path}: not a type a Media Set takes`, `the types: ${Object.keys(MEDIA_MIME_BY_EXTENSION).join(', ')}`)
+    let size: number
+    try {
+      size = statSync(path).size
+    } catch {
+      throw new UsageError(`no file at ${path}`, 'pass the path of one file')
+    }
+    if (size > MEDIA_MAX_BYTES) throw new CliError(`${path} is larger than the 50 MB Media Set limit`, { code: 'BAD_REQUEST' })
+    const client = api(ctx)
+    const setId = await resolveSet(client, ref)
+    const markings = flagString(ctx, 'markings')
+    const staged = await client.stage(setId, {
+      bytes: new Uint8Array(readFileSync(path)),
+      filename: basename(path),
+      mime,
+      logicalPath: basename(path),
+      ...(markings ? { markings } : {}),
+    })
+    return {
+      data: { set: ref, setId, upload: staged },
+      text: [
+        `staged ${basename(path)} for an Action: ${staged.mediaItemId}`,
+        '  pass it as the Action\'s upload input (`frontera action submit <apiName> --input \'{…, "<upload input>": "' + staged.mediaItemId + '"}\'`); it joins the set only when that request applies',
+      ].join('\n'),
+    }
+  },
+}
+
 const processCommand: Command = {
   meta: {
     noun: 'media',
@@ -589,4 +644,4 @@ const revoke: Command = {
   },
 }
 
-export const mediaCommands: Command[] = [list, create, upload, processCommand, status, retry, search, grant, revoke]
+export const mediaCommands: Command[] = [list, create, upload, stage, processCommand, status, retry, search, grant, revoke]

package/src/commands/registry.ts

@@ -50,10 +50,13 @@ import { loginCommand } from './login'
 import { setupCommand } from './setup'
 import { authCommands } from './auth/index-commands'
 import { kitCommands } from './kit/index-commands'
+import { conversationCommands } from './conversation/index-commands'
+import { traceCommands } from './trace/index-commands'
 import { workspaceCommands } from './workspace/index-commands'
 import { forgeCommands } from './forge/index-commands'
 import { localCommands } from './local/index-commands'
 import { localSnapshot } from './local/snapshot'
+import { localSteps } from './local/steps'
 import { mcpServe } from './mcp/serve'
 
 /**
@@ -62,6 +65,8 @@ import { mcpServe } from './mcp/serve'
  */
 export const GLOBAL_FLAGS: FlagSpec = {
   json: 'boolean',
+  // `{ ok, data, warnings }` on stdout, failures included (X10); implies --json.
+  envelope: 'boolean',
   quiet: 'boolean',
   yes: 'boolean',
   help: 'boolean',
@@ -93,10 +98,13 @@ export const COMMANDS: readonly Command[] = [
 
   ...authCommands,
   ...kitCommands,
+  ...conversationCommands,
+  ...traceCommands,
   ...workspaceCommands,
   ...forgeCommands,
   ...localCommands,
   localSnapshot,
+  localSteps,
   mcpServe,
 
   appInit,
@@ -431,9 +439,9 @@ export function renderNounHelp(noun: string): string {
 
 /** The help line every session-lane command prints — see `SESSION_LANE_HINT`. */
 export const SESSION_LANE_HELP =
-  'Needs a person’s session, not an API key. Set FRONTERA_TOKEN to your session token '
-  + 'and FRONTERA_API_URL (or pass --api-url). sk-ws- and sk-org- keys are refused with '
-  + '401 or 403; `frontera login` stores keys only.'
+  'Needs a person’s session, not an API key: sign in as yourself with '
+  + '`frontera auth login --browser` (approved in your browser, lasts 12 hours). '
+  + 'sk-ws- and sk-org- keys are refused with 401 or 403.'
 
 export function renderCommandHelp(meta: CommandMeta): string {
   const width = terminalWidth()

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

@@ -0,0 +1,56 @@
+import { UsageError } from '../../errors'
+import { getTrace, listTraces, readTrace } from '../../mcp/mcp-traces'
+import { projectRuntime } from '../conversation/local-runtime'
+import { flagBool, flagString, type Command } from '../types'
+
+/**
+ * `frontera trace get|list`: the project's local runtime's traces (Forge
+ * improvement plan N7), the reads the MCP tools `trace_get` and `trace_list`
+ * make, for a person or an agent working in the shell.
+ */
+
+export const traceGet: Command = {
+  meta: {
+    noun: 'trace',
+    verb: 'get',
+    args: [{ name: 'trace', required: true, description: 'The trace id (from a test run, `trace list` or `conversation get`)' }],
+    flags: { brief: 'boolean' },
+    flagHelp: { brief: 'the span tree without each span’s input and output' },
+    summary: 'Read one trace on the project’s local runtime: spans, tool calls, tokens, the reply check',
+    examples: ['frontera trace get 0c5e… --json'],
+    offline: true,
+  },
+  async run(ctx) {
+    const id = ctx.positional[0]
+    if (!id) throw new UsageError('missing <trace>', '`frontera trace list` lists the recent ones')
+    const link = projectRuntime(ctx.cwd)
+    const trace = await getTrace(link, id)
+    if (!trace) throw new UsageError(`no trace ${id} on the local runtime`, '`frontera trace list` lists the recent ones')
+    const read = readTrace(link, trace, { detail: !flagBool(ctx, 'brief') })
+    return { data: read, text: JSON.stringify(read, null, 2) }
+  },
+}
+
+export const traceList: Command = {
+  meta: {
+    noun: 'trace',
+    verb: 'list',
+    args: [],
+    flags: { conversation: 'string', name: 'string', errors: 'boolean', limit: 'string' },
+    flagHelp: { conversation: 'only this conversation’s turns', name: 'only traces whose name contains this, e.g. an Agent’s slug', errors: 'only traces with an error', limit: 'at most this many (default 10)' },
+    summary: 'Recent traces on the project’s local runtime, newest first',
+    examples: ['frontera trace list', 'frontera trace list --conversation 6f1c… --json'],
+    offline: true,
+  },
+  async run(ctx) {
+    const link = projectRuntime(ctx.cwd)
+    const limit = Math.min(Math.max(Number(flagString(ctx, 'limit') ?? 10) || 10, 1), 50)
+    const traces = await listTraces(link, { limit, conversationId: flagString(ctx, 'conversation'), name: flagString(ctx, 'name'), errorsOnly: flagBool(ctx, 'errors') })
+    return {
+      data: { traces },
+      text: traces.length ? traces.map((t) => `${t.id}  ${t.at}  ${t.name}${t.level !== 'DEFAULT' ? `  ${t.level}` : ''}`).join('\n') : 'No traces.',
+    }
+  },
+}
+
+export const traceCommands: readonly Command[] = [traceGet, traceList]

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

@@ -1,4 +1,5 @@
 import { BlueprintAuthoringApi } from '../../api/blueprint-authoring-api'
+import { keyReach, reachWords } from '../../key-reach'
 import { table } from '../../table'
 import type { Command } from '../types'
 
@@ -27,24 +28,30 @@ const list: Command = {
     verb: 'list',
     args: [],
     flags: {},
-    summary: 'List workspaces in this organization, with the ids --workspace takes',
+    summary: 'List workspaces in this organization, with the ids --workspace takes and, for an organization key, which it may act in',
     examples: ['frontera workspace list', 'frontera workspace list --json'],
   },
   async run(ctx) {
     const rows = await new BlueprintAuthoringApi(ctx.apiUrl, ctx.token).orgWorkspaces()
+    // An organization key acts only in the workspaces on its list: each row says whether it may (X3).
+    const reach = ctx.token.startsWith('sk-org-') && rows.length ? await keyReach(ctx.apiUrl, ctx.token, { list: async () => rows }) : null
+    const actsIn = new Map((reach ?? []).map((w) => [w.id, w.actsIn]))
 
     return {
-      data: rows,
+      data: reach ? rows.map((w) => ({ ...w, actsIn: actsIn.get(w.id ?? '') ?? false })) : rows,
       text: rows.length === 0
         ? 'No workspaces visible to this credential.\n'
           + '  This read needs an organization key (sk-org-…) carrying organization:update.'
         : // ID first: it is the value `--workspace` takes, and the reason to
           // run this at all. Name and slug are for recognising which is which.
-          table(
-            ['id', 'name', 'slug'],
-            rows.map((w) => [w.id ?? '?', w.name ?? '', w.slug ?? '']),
-            [undefined, 34, undefined],
-          ),
+          [
+            table(
+              reach ? ['id', 'name', 'slug', 'this key'] : ['id', 'name', 'slug'],
+              rows.map((w) => [w.id ?? '?', w.name ?? '', w.slug ?? '', ...(reach ? [actsIn.get(w.id ?? '') ? 'acts here' : '—'] : [])]),
+              [undefined, 34, undefined, undefined],
+            ),
+            ...(reach ? ['', `This key ${reachWords(reach)}.`] : []),
+          ].join('\n'),
     }
   },
 }

package/src/config.ts

@@ -140,7 +140,10 @@ export function resolveProfileName(
         },
       )
     }
-    const companion = opts.organization ? localOrganizationCompanion(found.profile, env) : null
+    // An organization command takes the organization profile the binding names (X3), or a local
+    // runtime's own organization profile beside its workspace profile.
+    const named = opts.organization && found.organizationProfile && found.organizationTrusted && getProfile(found.organizationProfile, env)?.credentialKind === 'organization' ? found.organizationProfile : null
+    const companion = named ?? (opts.organization ? localOrganizationCompanion(found.profile, env) : null)
     if (companion) return { profile: companion, source: 'directory', path: found.path }
     return { profile: found.profile, source: 'directory', path: found.path }
   }

package/src/dev-broker.ts

@@ -79,12 +79,26 @@ function freeOn(port: number, host: string): Promise<boolean> {
     const server = createServer()
     server.once('error', (err: NodeJS.ErrnoException) => {
       // No IPv6 on this machine: nothing can hold the port there either.
-      resolve(err.code === 'EADDRNOTAVAIL' || err.code === 'EAFNOSUPPORT')
+      if (err.code === 'EADDRNOTAVAIL' || err.code === 'EAFNOSUPPORT') return resolve(true)
+      // Bun says only "Failed to listen at ::1", with no code: free when no IPv6 port can be bound at all.
+      if (!err.code && host.includes(':')) return void ipv6Available().then((has) => resolve(!has))
+      resolve(false)
     })
     server.listen({ port, host, exclusive: true, ...(host === '::' ? { ipv6Only: true } : {}) }, () => server.close(() => resolve(true)))
   })
 }
 
+let ipv6: Promise<boolean> | null = null
+/** Whether this machine can listen on IPv6 at all: a port the system picks on ::1. */
+function ipv6Available(): Promise<boolean> {
+  ipv6 ??= new Promise((resolve) => {
+    const server = createServer()
+    server.once('error', () => resolve(false))
+    server.listen({ port: 0, host: '::1' }, () => server.close(() => resolve(true)))
+  })
+  return ipv6
+}
+
 /**
  * Whether nothing listens on `port` on either loopback, IPv4 or IPv6, nor on
  * a wildcard. Probing 127.0.0.1 alone let a dev server start beside another

package/src/device-login.ts

@@ -0,0 +1,143 @@
+import type { CredentialStore } from './credential-store'
+import { CliError } from './errors'
+
+/**
+ * A person's session for the CLI, approved in the browser (Forge improvement
+ * plan N5, RFC 8628 device authorization).
+ *
+ * Some commands act as a person (publishing a Blueprint, reviewing an
+ * Action, granting) and refuse every API key. Before, the only way to run
+ * them from a terminal was a session token copied out of the browser's
+ * developer tools. Now `frontera auth login --browser` asks the platform for
+ * a code, the person approves it on `/auth/device` while signed in, and the
+ * CLI keeps the session it receives in the keychain, beside the profile's
+ * key, for those commands only. The platform makes it short-lived (12 hours)
+ * and `frontera auth logout` revokes it.
+ */
+
+/** The client id the platform accepts device codes for. */
+export const DEVICE_CLIENT_ID = 'frontera-cli'
+
+const GRANT = 'urn:ietf:params:oauth:grant-type:device_code'
+
+export interface DeviceSession {
+  token: string
+  /** ISO time the platform said it stops working. */
+  expiresAt: string
+  apiUrl: string
+  email?: string
+}
+
+export interface DeviceCode {
+  deviceCode: string
+  userCode: string
+  verificationUri: string
+  verificationUriComplete: string
+  intervalMs: number
+  expiresAt: number
+}
+
+/** The store slot a profile's session lives in, beside its key. */
+export function sessionSlot(profile: string): string {
+  return `${profile}#session`
+}
+
+type Fetch = (url: string, init: RequestInit) => Promise<Response>
+
+const authUrl = (apiUrl: string, path: string) => `${apiUrl.replace(/\/+$/, '')}/api/auth${path}`
+
+async function post(fetchFn: Fetch, url: string, body: unknown, bearer?: string): Promise<{ status: number; data: Record<string, unknown> }> {
+  const res = await fetchFn(url, { method: 'POST', headers: { 'content-type': 'application/json', ...(bearer ? { authorization: `Bearer ${bearer}` } : {}) }, body: JSON.stringify(body) })
+  const data = (await res.json().catch(() => ({}))) as Record<string, unknown>
+  return { status: res.status, data }
+}
+
+/** Ask the platform for a code. A platform without device authorization answers 404. */
+export async function requestDeviceCode(apiUrl: string, fetchFn: Fetch = fetch, now = Date.now()): Promise<DeviceCode> {
+  const { status, data } = await post(fetchFn, authUrl(apiUrl, '/device/code'), { client_id: DEVICE_CLIENT_ID })
+  if (status === 404) throw new CliError('this platform does not offer browser sign-in for the CLI yet', { code: 'DEVICE_LOGIN_UNAVAILABLE', hint: 'ask your administrator to update the platform; until then, do this step in the product' })
+  if (status >= 400 || typeof data.device_code !== 'string' || typeof data.user_code !== 'string') {
+    throw new CliError(`the platform refused a sign-in code: ${String(data.error_description ?? data.error ?? status)}`, { code: 'DEVICE_LOGIN_REFUSED', hint: 'check the profile points at your deployment (`frontera auth current`), then try again' })
+  }
+  const uri = String(data.verification_uri ?? '/auth/device')
+  const absolute = /^https?:\/\//.test(uri) ? uri : new URL(uri, apiUrl).toString()
+  return {
+    deviceCode: data.device_code,
+    userCode: data.user_code,
+    verificationUri: absolute,
+    verificationUriComplete: typeof data.verification_uri_complete === 'string' && /^https?:\/\//.test(data.verification_uri_complete) ? data.verification_uri_complete : `${absolute}?user_code=${encodeURIComponent(data.user_code)}`,
+    intervalMs: Math.max(1, Number(data.interval) || 5) * 1000,
+    expiresAt: now + (Number(data.expires_in) || 600) * 1000,
+  }
+}
+
+/**
+ * Poll until the person approves, denies or the code expires. The platform
+ * answers `authorization_pending` until then and `slow_down` when polled too
+ * often, which adds five seconds as the RFC says.
+ */
+export async function awaitDeviceSession(
+  apiUrl: string,
+  code: DeviceCode,
+  deps: { fetch?: Fetch; sleep?: (ms: number) => Promise<void>; now?: () => number } = {},
+): Promise<DeviceSession> {
+  const fetchFn = deps.fetch ?? fetch
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)))
+  const now = deps.now ?? Date.now
+  let interval = code.intervalMs
+  while (now() < code.expiresAt) {
+    await sleep(interval)
+    const { data } = await post(fetchFn, authUrl(apiUrl, '/device/token'), { grant_type: GRANT, device_code: code.deviceCode, client_id: DEVICE_CLIENT_ID })
+    if (typeof data.access_token === 'string') {
+      return { token: data.access_token, expiresAt: new Date(now() + (Number(data.expires_in) || 0) * 1000).toISOString(), apiUrl }
+    }
+    if (data.error === 'authorization_pending') continue
+    if (data.error === 'slow_down') {
+      interval += 5000
+      continue
+    }
+    if (data.error === 'access_denied') throw new CliError('the sign-in was denied in the browser', { code: 'DEVICE_LOGIN_DENIED', hint: 'run `frontera auth login --browser` again to start over' })
+    if (data.error === 'expired_token') break
+    throw new CliError(`the sign-in failed: ${String(data.error_description ?? data.error ?? 'no answer')}`, { code: 'DEVICE_LOGIN_FAILED', hint: 'run `frontera auth login --browser` again' })
+  }
+  throw new CliError('the sign-in code expired before it was approved', { code: 'DEVICE_LOGIN_EXPIRED', hint: 'run `frontera auth login --browser` again' })
+}
+
+/** Who the session is, for the line the CLI prints; null when the platform doesn't say. */
+export async function sessionEmail(apiUrl: string, token: string, fetchFn: Fetch = fetch): Promise<string | null> {
+  const res = await fetchFn(authUrl(apiUrl, '/get-session'), { method: 'GET', headers: { authorization: `Bearer ${token}` } }).catch(() => null)
+  const data = res ? ((await res.json().catch(() => null)) as { user?: { email?: string } } | null) : null
+  return data?.user?.email ?? null
+}
+
+export async function saveDeviceSession(store: CredentialStore, profile: string, session: DeviceSession): Promise<void> {
+  await store.set(sessionSlot(profile), JSON.stringify(session))
+}
+
+/** The profile's session when it is for this origin and still good for a minute; null otherwise. */
+export async function readDeviceSession(store: CredentialStore, profile: string, apiUrl: string, now = Date.now()): Promise<DeviceSession | null> {
+  const raw = await store.get(sessionSlot(profile)).catch(() => null)
+  if (!raw) return null
+  try {
+    const session = JSON.parse(raw) as DeviceSession
+    if (typeof session.token !== 'string' || session.apiUrl.replace(/\/+$/, '') !== apiUrl.replace(/\/+$/, '')) return null
+    if (Date.parse(session.expiresAt) - now < 60_000) return null
+    return session
+  } catch {
+    return null
+  }
+}
+
+/** Revoke the session on the platform (best effort) and forget it here. */
+export async function forgetDeviceSession(store: CredentialStore, profile: string, fetchFn: Fetch = fetch): Promise<boolean> {
+  const raw = await store.get(sessionSlot(profile)).catch(() => null)
+  if (!raw) return false
+  try {
+    const session = JSON.parse(raw) as DeviceSession
+    await post(fetchFn, authUrl(session.apiUrl, '/revoke-session'), { token: session.token }, session.token).catch(() => null)
+  } catch {
+    // Not a session this CLI wrote; it is forgotten all the same.
+  }
+  await store.delete(sessionSlot(profile))
+  return true
+}