@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/commands/workflow/push.ts

@@ -1,8 +1,11 @@
 import { readFile } from 'node:fs/promises'
+import { isAbsolute, join, relative, resolve } from 'node:path'
 import { parse as parseYaml } from 'yaml'
 
 import { WorkflowApi, type LineageEdge } from '../../api/workflow-api'
 import { CliError, UsageError } from '../../errors'
+import { localDirectory, resolveTarget } from '../../local/local-dev-references'
+import { localRuntimeAt } from '../../local/local-runtime-target'
 import type { Command, CommandContext } from '../types'
 
 /**
@@ -107,6 +110,9 @@ export const workflowPush: Command = {
     const definition = await readDefinitionFile(requireFile(ctx))
     const client = new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const result = await client.push(slug, definition)
+    // What the service accepted but wants said (a confirm step with no one to ask, say): one line each,
+    // on stderr as `  warning: …`, which is also how `local dev` reads them from a push it runs.
+    for (const w of result.warnings ?? []) ctx.output.note(`  warning: ${w}`)
 
     const reach = describeReach(result.grants, result.lineage)
     return {
@@ -118,6 +124,39 @@ export const workflowPush: Command = {
   },
 }
 
+/**
+ * A project file's definition as the local runtime takes it: the names in it
+ * (`objectType/WorkOrder`, `objectSet/Open work orders`, `action/closeOrder`,
+ * `function/…`) become this runtime's ids, as `local dev` resolves them
+ * before a push. Null when the command does not reach the project's own
+ * local runtime, or the file is outside the project: the file is sent as
+ * written. The lines are what the resolving adapted, said as warnings.
+ */
+export async function localDefinition(ctx: CommandContext, slug: string, path: string): Promise<{ definition: unknown; lines: string[] } | null> {
+  const local = localRuntimeAt(ctx.cwd, ctx.apiUrl)
+  if (!local) return null
+  const absolute = isAbsolute(path) ? path : resolve(ctx.cwd, path)
+  const file = relative(local.project.root, absolute)
+  if (!file || file.startsWith('..') || isAbsolute(file)) return null
+  const resolved = await resolveTarget(
+    local.project,
+    { kind: 'workflow', key: `workflow:${slug}`, slug, file },
+    () => localDirectory(local.serviceUrl, local.creds),
+    local.creds.workspaceId,
+    local.creds.organizationId,
+  )
+  if (!resolved.ok) {
+    const [first, ...rest] = resolved.output.split('\n')
+    throw new CliError(`${slug}: ${(first ?? '').replace(/^error \[[A-Z_]+\]:\s*/, '')}`, {
+      code: 'UNRESOLVED_REFERENCE',
+      hint: rest.map((l) => l.trim()).filter(Boolean).join('\n  ') || 'add what it names to the project, then run `frontera local dev`',
+    })
+  }
+  const lines = resolved.output.split('\n').map((l) => l.trim()).filter(Boolean).map((l) => (/^warning:/i.test(l) ? `  ${l}` : `  warning: ${l}`))
+  const definition = resolved.file ? await readDefinitionFile(join(local.project.root, resolved.file)) : (resolved.doc ?? (await readDefinitionFile(absolute)))
+  return { definition, lines }
+}
+
 /**
  * Check a definition without writing anything.
  *
@@ -137,12 +176,19 @@ export const workflowValidate: Command = {
     ],
     flags: {},
     summary: 'Validate a definition and report its reach — writes nothing',
-    examples: ['frontera workflow validate invoice-intake workflow.yaml'],
+    details: [
+      'Inside a project whose local runtime is running (the directory is bound to it), the file is read as `frontera local dev` reads it: the names it uses (`objectType/WorkOrder`, `objectSet/Open work orders`, `action/closeOrder`, `function/nearest-technician`) become the runtime\'s ids before the check, and what that adapts is said as a warning. Elsewhere the file is sent as written.',
+      'Warnings are what the service accepts but wants said, such as a confirm step with no `onUnavailable` in a workflow no person can answer. They print on stderr as `  warning: …` and come back as `warnings` with --json.',
+    ],
+    examples: ['frontera workflow validate invoice-intake workflow.yaml', 'frontera workflow validate overdue-sweep workflows/overdue-sweep.yaml --json'],
   },
 
   async run(ctx) {
     const slug = requireSlug(ctx)
-    const definition = await readDefinitionFile(requireFile(ctx))
+    const path = requireFile(ctx)
+    const local = await localDefinition(ctx, slug, path)
+    const definition = local ? local.definition : await readDefinitionFile(path)
+    for (const line of local?.lines ?? []) ctx.output.note(line)
     const client = new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     // A dry run reports problems as DATA, not as a 400 — the service does this
     // so the Console can show them beside the draft. So the refusal arrives
@@ -161,6 +207,7 @@ export const workflowValidate: Command = {
       })
     }
 
+    for (const w of result.warnings ?? []) ctx.output.note(`  warning: ${w}`)
     const reach = describeReach(result.grants, result.lineage)
     return {
       data: result,

package/src/commands/workflow/run.ts

@@ -1,4 +1,4 @@
-import { WorkflowApi, type RunRequest, type RunTree, type RunTreeNode } from '../../api/workflow-api'
+import { WorkflowApi, type RunRequest, type RunTree, type RunTreeNode, type VersionSummary } from '../../api/workflow-api'
 import { CliError, UsageError } from '../../errors'
 import { readSecretValue } from '../../secrets'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
@@ -85,22 +85,54 @@ export async function parseInputFlag(ctx: CommandContext): Promise<Record<string
 }
 
 /**
- * `--version N`, or undefined for the live one.
+ * `--version N`, `--version draft`, or undefined for the live one.
  *
  * Rejected here rather than forwarded for the reason `promote` rejects its
  * argument: `--version abc` arriving as `NaN` comes back naming a field the
  * author never typed.
+ *
+ * `draft` (and its synonym `latest`) is the alias the MCP `workflow_run` and
+ * `frontera local test` already take: the newest version that is not retired,
+ * which `resolveVersion` looks up. Without it an author had to read the number
+ * from `workflow get` first, and that number moves on every push or apply.
  */
-export function parseVersionFlag(ctx: CommandContext): number | undefined {
+export function parseVersionFlag(ctx: CommandContext): number | 'draft' | undefined {
   const raw = flagString(ctx, 'version')
   if (raw === undefined) return undefined
+  const word = raw.trim().toLowerCase()
+  if (word === 'draft' || word === 'latest') return 'draft'
   const parsed = Number(raw)
   if (!Number.isInteger(parsed) || parsed < 1) {
-    throw new UsageError(`"${raw}" is not a version number`, 'frontera workflow get <slug> lists the versions')
+    throw new UsageError(`"${raw}" is not a version number or "draft"`, 'frontera workflow get <slug> lists the versions; `--version draft` runs the newest')
   }
   return parsed
 }
 
+/**
+ * The version number a `--version` flag names: a number as given, and `draft` as
+ * the newest version that is not retired. That is the draft just pushed, or the
+ * live version when a person promoted it (promoting retires the older drafts),
+ * the same rule as the MCP `workflow_run`'s `pickVersion`.
+ */
+export async function resolveVersion(
+  requested: number | 'draft' | undefined,
+  versions: () => Promise<VersionSummary[]>,
+  slug: string,
+): Promise<number | undefined> {
+  if (requested !== 'draft') return requested
+  const rows = await versions()
+  const newest = [...rows].sort((a, b) => b.number - a.number).find((v) => v.status !== 'retired')
+  if (!newest) {
+    throw new CliError(
+      rows.length
+        ? `workflow "${slug}" has only retired versions (${rows.map((v) => `v${v.number}`).join(', ')}), so there is no draft to run`
+        : `workflow "${slug}" has no version yet, so there is no draft to run`,
+      { code: 'NOT_FOUND', hint: `push its definition first: \`frontera workflow push ${slug} <file>\`, or in a local project \`frontera local dev --once\`` },
+    )
+  }
+  return newest.number
+}
+
 /** One line per node, nested under the run each child step started. */
 export function describeNodes(nodes: RunTreeNode[], depth = 1): string[] {
   const lines: string[] = []
@@ -108,6 +140,8 @@ export function describeNodes(nodes: RunTreeNode[], depth = 1): string[] {
     const indent = '  '.repeat(depth)
     const failed = node.status === 'failed' ? ' ✗' : ''
     lines.push(`${indent}${node.nodeId}  ${node.kind}  ${node.status}${failed}`)
+    // A failed step's error, and each input it named (`issues`): the reason, where it happened.
+    if (node.error) lines.push(...stepErrorLines(node.error, `${indent}  `))
     // A `forEach` or a `workflow` step is a run of its own, and its steps are
     // where its failure is explained — flattening them would report a failed
     // parent with no reason anywhere in the output.
@@ -116,6 +150,26 @@ export function describeNodes(nodes: RunTreeNode[], depth = 1): string[] {
   return lines
 }
 
+/**
+ * A step's recorded error as lines: `{ code, message }`, then each of its
+ * `issues` (`{ path, message }`, the input it named and the rule it broke).
+ */
+export function stepErrorLines(error: unknown, indent: string): string[] {
+  if (typeof error === 'string') return [`${indent}error ${error}`]
+  if (!error || typeof error !== 'object') return []
+  const e = error as { code?: unknown; message?: unknown; issues?: unknown }
+  const head = [typeof e.code === 'string' ? e.code : '', typeof e.message === 'string' ? e.message : ''].filter(Boolean).join(': ')
+  const issues = Array.isArray(e.issues)
+    ? e.issues.flatMap((i) => {
+        const issue = (i && typeof i === 'object' ? i : {}) as { path?: unknown; message?: unknown }
+        const message = typeof issue.message === 'string' ? issue.message : ''
+        if (!message) return []
+        return [`${indent}  · ${typeof issue.path === 'string' && issue.path ? `${issue.path}: ` : ''}${message}`]
+      })
+    : []
+  return [`${indent}error ${head || JSON.stringify(error)}`, ...issues]
+}
+
 /**
  * The subject of a bound run, as "<type> <pk>".
  *
@@ -136,7 +190,7 @@ export function describeRun(run: RunTree): string {
   if (run.subject) lines.push(`  subject ${describeSubject(run.subject)}`)
   // The error before the steps: it is the reason the reader opened this, and
   // burying it under a trail of successful steps is how it gets missed.
-  if (run.error) lines.push(`  error ${typeof run.error === 'string' ? run.error : JSON.stringify(run.error)}`)
+  if (run.error) lines.push(...stepErrorLines(run.error, '  '))
   lines.push(...describeNodes(run.nodes))
   if (run.output !== null && run.output !== undefined) lines.push(`  returned ${JSON.stringify(run.output)}`)
   return lines.join('\n')
@@ -166,13 +220,17 @@ export const workflowRun: Command = {
     verb: 'run',
     args: [{ name: 'slug', required: true, description: 'workflow slug' }],
     flags: { 'no-wait': 'boolean', input: 'string', subject: 'string', version: 'string' },
-    summary: 'Run the live version now — or a named one — and report what it did',
+    summary: 'Run the live version now — or a named one, or the newest draft — and report what it did',
+    details: [
+      '`--version <n>` runs that version. `--version draft` runs the newest version that is not retired: the draft you last pushed or applied, or the live version once a person promoted it (`latest` means the same). Without `--version`, the live version runs.',
+    ],
     examples: [
       'frontera workflow run invoice-intake',
       'frontera workflow run invoice-intake --input \'{"threshold": 500}\'',
       'frontera workflow run invoice-intake --input @input.json',
       'frontera workflow run shipment-review --subject SHP-0000001',
       'frontera workflow run invoice-intake --version 3 --no-wait',
+      'frontera workflow run invoice-intake --version draft --input @input.json',
     ],
   },
 
@@ -188,7 +246,7 @@ export const workflowRun: Command = {
     // pk and nothing else, and asking for `{"pk":"…"}` on a command line would
     // be quoting ceremony around a single value.
     if (subject) body.subject = { pk: subject }
-    const version = parseVersionFlag(ctx)
+    const version = await resolveVersion(parseVersionFlag(ctx), () => client.versions(slug), slug)
     if (version !== undefined) body.version = version
 
     const started = await client.run(slug, body)

package/src/commands/workflow/runs.ts

@@ -1,7 +1,7 @@
 import { WorkflowApi } from '../../api/workflow-api'
-import { CliError } from '../../errors'
+import { CliError, UsageError } from '../../errors'
 import { table } from '../../table'
-import type { Command } from '../types'
+import { flagString, type Command } from '../types'
 import { describeRun, describeSubject, requireRunId } from './run'
 import { requireSlug } from './push'
 
@@ -25,10 +25,11 @@ export const workflowRuns: Command = {
         description: 'one run to open, with its steps; omit to list recent runs',
       },
     ],
-    flags: {},
-    summary: 'List recent runs, newest first — or open one run and its steps',
+    flags: { only: 'string' },
+    summary: 'List recent runs, newest first — or open one run and its steps (--only live|test: live runs, or test runs)',
     examples: [
       'frontera workflow runs invoice-intake',
+      'frontera workflow runs invoice-intake --only live',
       'frontera workflow runs invoice-intake 0f2c8b1e-7a41-4c96-9d3e-52b0c4a7e118',
     ],
   },
@@ -56,11 +57,13 @@ export const workflowRuns: Command = {
       return { data: run, text: describeRun(run) }
     }
 
-    const rows = await client.runs(slug)
+    const source = flagString(ctx, 'only')
+    if (source !== undefined && source !== 'live' && source !== 'test') throw new UsageError(`--only takes live or test, not "${source}"`, `e.g. \`frontera workflow runs ${slug} --only live\``)
+    const rows = await client.runs(slug, source)
     if (rows.length === 0) {
       return {
         data: { runs: [] },
-        text: `No runs recorded for ${slug}.\n  frontera workflow run ${slug}   # to start one`,
+        text: `No ${source ? `${source} ` : ''}runs recorded for ${slug}.\n  frontera workflow run ${slug}   # to start one`,
       }
     }
 

package/src/commands/workflow/webhook-test.ts

@@ -0,0 +1,166 @@
+import { readFileSync } from 'node:fs'
+
+import { WorkflowApi, type RunSummary, type WebhookListen } from '../../api/workflow-api'
+import { CliError, UsageError } from '../../errors'
+import { flagString, type Command } from '../types'
+
+/**
+ * Send one delivery to a workflow's webhook on its DRAFT, and show what came
+ * back: the run the mapping (`$request.body`, headers, query) produced.
+ *
+ * The draft's test door (`/v1/hooks-test/…`) answers only while a Listen is
+ * armed, which was Studio's button alone, so a webhook's mapping could not be
+ * tried before a version went live. This arms it (`POST
+ * /v1/workflows/:slug/listen`: one delivery, within 120 seconds) and delivers
+ * straight away. The trigger's own auth still applies: pass what the sender
+ * would send with `--header`.
+ */
+
+/** The door to send to: the one at `path`, or the only one. */
+export function pickDoor(listen: WebhookListen, path: string | undefined, slug: string): WebhookListen['doors'][number] {
+  const doors = listen.doors
+  if (!doors.length) throw new CliError(`workflow ${slug} v${listen.version} has no webhook trigger`, { code: 'USAGE', hint: 'add a `kind: webhook` trigger to its file, or run it with `frontera workflow run`' })
+  const wanted = path?.replace(/^\/+/, '')
+  if (wanted !== undefined) {
+    const door = doors.find((d) => d.path.replace(/^\/+/, '') === wanted)
+    if (!door) throw new UsageError(`workflow ${slug} has no webhook at "${wanted}"`, `its webhooks: ${doors.map((d) => d.path || '(no path)').join(', ')}`)
+    return door
+  }
+  if (doors.length > 1) throw new UsageError(`workflow ${slug} has ${doors.length} webhooks; say which with --path`, `its webhooks: ${doors.map((d) => d.path || '(no path)').join(', ')}`)
+  return doors[0]!
+}
+
+/** The test door on the address this CLI talks to: the service names its public address, which a local runtime may not answer on. */
+export function doorUrl(test: string, apiUrl: string, query: string | undefined): string {
+  const url = new URL(test)
+  const at = new URL(url.pathname, apiUrl.replace(/\/+$/, '') + '/')
+  if (query) for (const [k, v] of new URLSearchParams(query.replace(/^\?/, ''))) at.searchParams.append(k, v)
+  return at.toString()
+}
+
+/** `Name: value`, as a sender's header. */
+export function parseHeader(raw: string | undefined): Record<string, string> {
+  if (!raw) return {}
+  const at = raw.indexOf(':')
+  if (at <= 0) throw new UsageError('--header takes `Name: value`', "e.g. --header 'X-Signature: abc123'")
+  return { [raw.slice(0, at).trim()]: raw.slice(at + 1).trim() }
+}
+
+/** `--version`: a draft's number, or `draft` (and `latest`) for the latest draft, as the MCP tool takes it. */
+export function readVersionFlag(raw: string | undefined): number | undefined {
+  if (raw === undefined || /^(draft|latest)$/i.test(raw.trim())) return undefined
+  const version = Number(raw)
+  if (!Number.isInteger(version) || version < 1) throw new UsageError('--version takes a draft’s number, or draft for the latest one', 'e.g. --version 3 or --version draft; leave it out for the latest draft')
+  return version
+}
+
+/**
+ * The run a delivery started: the id the door answered with (`respond:
+ * immediately` gives it), else the newest test run of that version since the
+ * delivery was sent. Null when none shows up within a few seconds.
+ */
+export async function findDeliveredRun(list: () => Promise<RunSummary[] | unknown>, version: number, sentAt: number, answered: unknown, tries = 6, waitMs = 500): Promise<string | null> {
+  const fromBody = answered && typeof answered === 'object' && typeof (answered as { runId?: unknown }).runId === 'string' ? (answered as { runId: string }).runId : null
+  if (fromBody) return fromBody
+  for (let attempt = 0; attempt < tries; attempt++) {
+    const page = await Promise.resolve().then(list).catch(() => null)
+    const rows = (Array.isArray(page) ? page : ((page as { items?: unknown[] } | null)?.items ?? [])) as Array<Partial<RunSummary>>
+    const mine = rows
+      .filter((r) => typeof r.id === 'string' && (r.versionNumber === undefined || r.versionNumber === null || r.versionNumber === version) && Date.parse(r.startedAt ?? '') >= sentAt)
+      .sort((a, b) => Date.parse(b.startedAt ?? '') - Date.parse(a.startedAt ?? ''))
+    if (mine[0]) return mine[0].id!
+    if (attempt < tries - 1) await new Promise((r) => setTimeout(r, waitMs))
+  }
+  return null
+}
+
+function readBody(from: string | undefined): string | undefined {
+  if (from === undefined) return undefined
+  if (from === '-') return readFileSync(0, 'utf8')
+  try {
+    return readFileSync(from, 'utf8')
+  } catch {
+    throw new UsageError(`could not read ${from}`, 'pass a JSON file with --body, or - for standard input')
+  }
+}
+
+export const workflowWebhookTest: Command = {
+  meta: {
+    noun: 'workflow',
+    verb: 'webhook-test',
+    args: [{ name: 'workflow', required: true, description: 'the workflow’s slug' }],
+    flags: { body: 'string', path: 'string', method: 'string', header: 'string', query: 'string', version: 'string' },
+    summary: 'Send one test delivery to a workflow’s webhook on its draft, and show the run it made',
+    examples: [
+      'frontera workflow webhook-test work-order-intake --body fault.json',
+      'frontera workflow webhook-test intake --path fault-reports --body -',
+      "frontera workflow webhook-test intake --body a.json --header 'X-Key: k1'",
+      'frontera workflow webhook-test intake --body a.json --version draft --json',
+    ],
+  },
+
+  async run(ctx) {
+    const slug = ctx.positional[0]
+    if (!slug) throw new UsageError('missing <workflow>', 'frontera workflow webhook-test <slug> --body payload.json')
+    const version = readVersionFlag(flagString(ctx, 'version'))
+    const body = readBody(flagString(ctx, 'body'))
+    if (body !== undefined) {
+      try {
+        JSON.parse(body)
+      } catch {
+        // A sender may post text or a form: sent as it is, said here.
+        ctx.output.note('[webhook-test] the body is not JSON: it is sent as text')
+      }
+    }
+    const headers = parseHeader(flagString(ctx, 'header'))
+
+    const api = new WorkflowApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+    const listen = await api.listen(slug, version).catch((err: unknown) => {
+      if (err instanceof CliError && /not.?found|404/i.test(`${err.code} ${err.message}`) && /listen/i.test(err.message)) {
+        throw new CliError('this platform release cannot arm a draft’s webhook from the CLI', { code: 'UNSUPPORTED', hint: 'use Listen on the workflow’s page, or update to a release that supports `frontera workflow webhook-test`' })
+      }
+      throw err
+    })
+    const door = pickDoor(listen, flagString(ctx, 'path'), slug)
+    const method = (flagString(ctx, 'method') ?? (door.methods.includes('POST') ? 'POST' : door.methods[0] ?? 'POST')).toUpperCase()
+    if (door.methods.length && !door.methods.includes(method)) throw new UsageError(`the webhook at "${door.path}" takes ${door.methods.join(', ')}, not ${method}`, `--method ${door.methods[0]}`)
+    const url = doorUrl(door.test, ctx.apiUrl, flagString(ctx, 'query'))
+    const sent = method === 'GET' || method === 'HEAD' ? undefined : body
+    // A second back, so a run the runtime stamps a moment before the delivery returns still counts.
+    const sentAt = Date.now() - 1_000
+    const res = await fetch(url, {
+      method,
+      headers: { ...(sent !== undefined ? { 'content-type': 'application/json' } : {}), ...headers },
+      ...(sent !== undefined ? { body: sent } : {}),
+    })
+    const text = await res.text()
+    let answer: unknown = text
+    try {
+      answer = text ? JSON.parse(text) : null
+    } catch {
+      // Kept as text.
+    }
+    // The run the delivery made, so `--json` shows it (a refused delivery made none).
+    const runId = res.status === 401 || res.status === 403 || res.status === 404 ? null : await findDeliveredRun(() => api.runs(slug, 'test'), listen.version, sentAt, answer)
+    const data = { workflow: slug, version: listen.version, path: door.path, method, status: res.status, response: answer, runId }
+    if (!res.ok) {
+      throw new CliError(`the webhook answered ${res.status} on the draft (v${listen.version})`, {
+        code: 'WEBHOOK_TEST_FAILED',
+        hint: res.status === 401 || res.status === 403
+          ? 'the trigger’s auth refused the delivery: pass what the sender sends with --header'
+          : res.status === 404
+            ? 'the test door did not answer: the Listen may have ended, or the path or method differs from the trigger’s'
+            : `${typeof answer === 'string' ? answer.slice(0, 300) : JSON.stringify(answer).slice(0, 300)}`,
+        details: data,
+      })
+    }
+    return {
+      data,
+      text: [
+        `${method} ${door.path ? `/${door.path.replace(/^\/+/, '')}` : '(no path)'} on workflow ${slug} v${listen.version} (draft): ${res.status}`,
+        typeof answer === 'string' ? answer : JSON.stringify(answer, null, 2),
+        runId ? `  the run: frontera workflow runs ${slug} ${runId}` : `  the run: frontera workflow runs ${slug} --only test`,
+      ].join('\n'),
+    }
+  },
+}

package/src/config.ts

@@ -4,9 +4,11 @@ import { credentialStore, type CredentialSource } from './credential-store'
 import { CliError, UsageError } from './errors'
 import { migrateLegacyConfig } from './profile-migration'
 import { configPath, type Env } from './paths'
+import { localRuntimeProfileOf } from './local/local-project'
 import { findContext } from './project-context'
 import {
   assertOriginMatches,
+  getProfile,
   isLegacyConfig,
   listProfiles,
   normalizeOrigin,
@@ -72,6 +74,25 @@ export interface CredentialDeps {
 export interface ResolveOptions {
   apiUrl?: string
   profile?: string
+  /**
+   * The command acts at organization grain. In a directory bound to a local
+   * runtime's workspace profile (`local-<project>`), the runtime's
+   * organization profile beside it (`local-<project>-org`) is selected
+   * instead: the same runtime, the key its organization commands need.
+   */
+  organization?: boolean
+}
+
+/**
+ * The organization profile `local start` registers beside a local runtime's
+ * workspace profile, when this is one and it has one.
+ */
+export function localOrganizationCompanion(profile: string, env: Env = process.env): string | null {
+  if (!profile.startsWith('local-')) return null
+  const org = `${profile}-org`.slice(0, 64)
+  if (org === profile || getProfile(profile, env)?.credentialKind !== 'workspace') return null
+  const companion = getProfile(org, env)
+  return companion?.credentialKind === 'organization' && companion.apiUrl === getProfile(profile, env)?.apiUrl ? org : null
 }
 
 /**
@@ -103,16 +124,24 @@ export function resolveProfileName(
      * question rather than an answer, and `auth use` is how it gets answered.
      */
     if (!found.trusted) {
+      // A copied or pulled project carries the machine it came from's selection. When this directory
+      // has its own local runtime, ITS profile is the one to bind: the named one belongs to another
+      // directory (another project's runtime, or another machine's).
+      const own = localRuntimeProfileOf(found.root)
+      const ownHere = own && own !== found.profile && getProfile(own, env) ? own : null
       throw new CliError(
         `${found.path} selects "${found.profile}", but this machine never bound that directory`,
         {
           code: 'PROJECT_CONTEXT_UNTRUSTED',
-          hint:
-            `if you meant to use it, run \`frontera auth use ${found.profile}\` in ${found.root} — `
-            + 'a context file committed to a repository is not proof that you chose it',
+          hint: ownHere
+            ? `this directory has its own local runtime, whose profile is ${ownHere} (\`frontera local status\` names it): run \`frontera auth use ${ownHere}\` in ${found.root}. "${found.profile}" was bound where this project came from, and would reach that runtime instead`
+            : `if you meant to use it, run \`frontera auth use ${found.profile}\` in ${found.root} — `
+              + 'a context file committed to a repository is not proof that you chose it',
         },
       )
     }
+    const companion = 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 }
   }
 
@@ -144,9 +173,18 @@ export async function resolveCredential(
   await ensureMigrated(env)
 
   const store = deps.store ?? credentialStore(env)
-  const selection = resolveProfileName(opts, deps)
-
   const explicitOrigin = opts.apiUrl ?? env.FRONTERA_API_URL
+  const envToken = env.FRONTERA_TOKEN?.trim()
+  // A raw token with its own origin uses no stored key, so a context file this machine did not
+  // bind is nothing to refuse: it only names the profile the result reports (none, here).
+  let selection: ReturnType<typeof resolveProfileName>
+  try {
+    selection = resolveProfileName(opts, deps)
+  } catch (err) {
+    if (!(envToken && explicitOrigin && err instanceof CliError && err.code === 'PROJECT_CONTEXT_UNTRUSTED')) throw err
+    selection = { profile: null, source: 'none' }
+  }
+
   const originSource: OriginSource = opts.apiUrl ? 'flag' : env.FRONTERA_API_URL ? 'environment' : 'profile'
 
   /**
@@ -155,7 +193,6 @@ export async function resolveCredential(
    * would be sent to whatever deployment the checked-out directory happens to
    * select. That is a cross-customer credential leak with no visible symptom.
    */
-  const envToken = env.FRONTERA_TOKEN?.trim()
   if (envToken) {
     if (!explicitOrigin) {
       throw new UsageError(

package/src/dev-broker.ts

@@ -1,4 +1,5 @@
 import { randomBytes } from 'node:crypto'
+import { createServer } from 'node:net'
 
 import type { BridgeInit } from '@frontera-sdk/core/bridge-protocol'
 
@@ -69,3 +70,54 @@ export function createDevSessionBroker(options: {
 
   return { endpoint: `http://127.0.0.1:${server.port}${path}`, server }
 }
+
+/** The addresses an App's port must be free on: the browser resolves `localhost` to either loopback, and a wildcard listener answers both. */
+export const LOOPBACK_ADDRESSES = ['127.0.0.1', '::1', '0.0.0.0', '::'] as const
+
+function freeOn(port: number, host: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    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')
+    })
+    server.listen({ port, host, exclusive: true, ...(host === '::' ? { ipv6Only: true } : {}) }, () => server.close(() => resolve(true)))
+  })
+}
+
+/**
+ * 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
+ * process holding the port on ::1, and `localhost` and `127.0.0.1` then
+ * served two different Apps.
+ */
+export async function isLoopbackPortFree(port: number, hosts: readonly string[] = LOOPBACK_ADDRESSES): Promise<boolean> {
+  for (const host of hosts) if (!(await freeOn(port, host))) return false
+  return true
+}
+
+/** A port the system hands out on 127.0.0.1 (`listen(0)`), closed again at once. */
+function systemPort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer()
+    server.once('error', reject)
+    server.listen({ port: 0, host: '127.0.0.1', exclusive: true }, () => {
+      const address = server.address()
+      const port = typeof address === 'object' && address ? address.port : 0
+      server.close(() => (port ? resolve(port) : reject(new Error('the system gave no port'))))
+    })
+  })
+}
+
+/**
+ * A port free on every loopback address (`isLoopbackPortFree`), for `--port 0`:
+ * the system picks it on 127.0.0.1, and one something holds on ::1 or a
+ * wildcard is passed over for the next.
+ */
+export async function freeLoopbackPort(isFree: (port: number) => Promise<boolean> = isLoopbackPortFree): Promise<number> {
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    const port = await systemPort()
+    if (await isFree(port)) return port
+  }
+  throw new Error('no port was free on every loopback address after 20 tries')
+}