@frontera-sdk/cli 1.53.7 → 1.53.9

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

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 
-import { signInStep } from '../../device-login'
+import { signInCommand, signInStep } from '../../device-login'
 import { CliError, UsageError } from '../../errors'
 import { documentPath, readFolders, readPulledDocuments, recordPulledDocuments, sha256Of, type PulledDocument } from '../../local/local-knowledge-documents'
 import { assetFilename } from '../skill/bundle-commands'
@@ -13,7 +13,7 @@ import { mcpServersNotCarried } from '../../local/local-mcp-servers'
 import { localProject, type LocalProject } from '../../local/local-project'
 import { HISTORY_KINDS, projectAtRevision } from '../../local/local-sync-base'
 import { normalizeOrigin, unwrap } from '../../local/local-sync-client'
-import { getSyncKey, readLink, registerTargetProfile, setModelMapping, targetOf, type SyncLink } from '../../local/local-sync-link'
+import { getSyncKey, readLink, registerTargetProfile, setModelMapping, targetOf, targetProfileName, targetSession, type SyncLink } from '../../local/local-sync-link'
 import { itemTitle } from '../../local/local-sync-names'
 import { checkBody, markMissingModels, markRefused, needsAPerson, planOf, type ApplyStep, type WorkspaceModel } from '../../local/local-sync-precheck'
 import { afterApplyOf, recordAfterApply } from '../../local/local-person-steps'
@@ -72,9 +72,10 @@ import { fetchFor, planFor, sourceFor } from './sync'
  *   push --release desk=1.4.0  also release a Custom App: Apply promotes that deployment, last
  *
  * The request's id is kept in `.frontera/sync/requests.json` (not
- * committed). Keys come from the keychain, as for `sync fetch`; the
- * organization key goes beside the workspace key only when Apply has
- * Blueprint items.
+ * committed). The calls act as the person signed in for the project's
+ * target profile (`frontera auth login --browser --profile <target>`), or
+ * else with the project's keys from the keychain, as for `sync fetch`: the
+ * workspace key, and the organization key beside it when one is stored.
  */
 
 const ORGANIZATION_KEY_HEADER = 'x-frontera-organization-key'
@@ -91,7 +92,18 @@ const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? '' : 's'}`
 
 type RequestBody = NonNullable<RequestInit['body']>
 
+/**
+ * Who a command's change-request calls act as: the person signed in for the
+ * target, or else the project's keys. One for the whole command: a person
+ * sends no key with their session, so a Blueprint change applied by a person
+ * is that person's alone.
+ */
+type Acting =
+  | { as: 'person'; profile: string; token: string; email: string | null; organizationKeyStored: boolean }
+  | { as: 'keys'; profile: string; workspaceKey: string; organizationKey: string | null }
+
 interface Platform {
+  acting: Acting
   call<T>(method: 'GET' | 'POST' | 'PUT', path: string, body?: unknown, opts?: { organizationKey?: string | null; timeoutMs?: number }): Promise<T>
   /** A body sent as it is (a document's bytes, a multipart upload), not as JSON. */
   send<T>(method: 'POST' | 'PUT', path: string, body: RequestBody, contentType: string | null, opts?: { timeoutMs?: number }): Promise<T>
@@ -100,21 +112,24 @@ interface Platform {
 }
 
 /**
- * The change-request routes with the project's workspace key. A refusal by
- * the blocking checks keeps them (`details.checks`), so the caller can say
- * which item each names; Apply may take minutes, so it waits longer than a
- * read.
+ * The change-request routes as `acting`: a person's session names the
+ * linked workspace, a workspace key carries it. A refusal by the blocking
+ * checks keeps them (`details.checks`), so the caller can say which item
+ * each names; Apply may take minutes, so it waits longer than a read.
  */
-function platform(link: SyncLink, key: string): Platform {
+function platform(link: SyncLink, acting: Acting): Platform {
   const origin = normalizeOrigin(link.platform)
+  const credential: Record<string, string> = acting.as === 'person' ? { authorization: `Bearer ${acting.token}`, 'x-workspace-id': link.workspace } : { authorization: `Bearer ${acting.workspaceKey}` }
+  const answer = <T>(res: Response) => answerAs<T>(res, acting)
   const request = async (method: string, path: string, headers: Record<string, string>, body: RequestBody | undefined, timeoutMs: number): Promise<Response> => {
     try {
-      return await fetch(new URL(path, origin), { method, headers: { authorization: `Bearer ${key}`, accept: 'application/json', ...headers }, body, signal: AbortSignal.timeout(timeoutMs) })
+      return await fetch(new URL(path, origin), { method, headers: { ...credential, accept: 'application/json', ...headers }, body, signal: AbortSignal.timeout(timeoutMs) })
     } catch (err) {
       throw new CliError(`${origin} did not answer: ${(err as Error).message}`, { code: 'UNAVAILABLE', hint: 'check the address and your network, then run the command again' })
     }
   }
   return {
+    acting,
     async call<T>(method: 'GET' | 'POST' | 'PUT', path: string, body?: unknown, opts: { organizationKey?: string | null; timeoutMs?: number } = {}): Promise<T> {
       const res = await request(method, path, {
         ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
@@ -134,7 +149,7 @@ function platform(link: SyncLink, key: string): Platform {
 }
 
 /** A platform answer: its data, or a refusal in words (the checks it names kept in `details`). */
-async function answer<T>(res: Response): Promise<T> {
+async function answerAs<T>(res: Response, acting: Acting): Promise<T> {
   const text = await res.text().catch(() => '')
   let parsed: Record<string, unknown> | null = null
   try {
@@ -150,18 +165,153 @@ async function answer<T>(res: Response): Promise<T> {
   if (details?.code === 'GATE_FAILED' && details.gate) {
     throw new CliError(message, { code: 'SYNC_APPLY_GATED', hint: 'make the checks pass (`frontera local sync request evidence` attaches evals and renders), or a workspace admin applies with `--force --reason "<why>"`', details: { gate: details.gate } })
   }
+  if (res.status === 401 && acting.as === 'person') throw new CliError(`the platform no longer takes the browser sign-in for ${acting.profile}`, { code: 'UNAUTHORIZED', hint: `sign in again with \`${signInCommand(acting.profile)}\`` })
   if (res.status === 401) throw new CliError('the platform refused the key', { code: 'UNAUTHORIZED', hint: 'check it is a current workspace key (sk-ws-…) for this platform; `frontera local sync connect` stores a new one' })
-  if (res.status === 403) throw new CliError(message, { code: 'FORBIDDEN', hint: 'the key’s role decides what it may propose and apply; ask a workspace admin' })
+  if (res.status === 403) throw new CliError(message, { code: 'FORBIDDEN', hint: acting.as === 'keys' ? 'the key’s role decides what it may propose and apply; ask a workspace admin' : 'your role decides what you may propose and apply; ask a workspace admin' })
   if (res.status === 404) throw new CliError(message, { code: 'NOT_FOUND', hint: 'the change request is gone from the workspace; propose again with `frontera local sync push`' })
   if (res.status === 409) throw new CliError(message, { code: 'CONFLICT', hint: 'see where it stands with `frontera local sync request`' })
   if (res.status === 400 || res.status === 422) throw new CliError(message, { code: 'VALIDATION_ERROR', hint: 'see where it stands with `frontera local sync request`' })
   throw new CliError(`the platform answered ${res.status}: ${message}`, { code: 'UNAVAILABLE', hint: 'check the platform is reachable, then run the command again' })
 }
 
-function platformFor(project: LocalProject, link: SyncLink): Platform {
-  const key = getSyncKey(project, 'workspace')
-  if (!key) throw new CliError('no workspace key for this project on this machine', { code: 'SYNC_NO_KEY', hint: 'run `frontera local sync connect` to store one (keys are per machine)' })
-  return platform(link, key)
+/** The person signed in for the target when they are a member of the linked workspace, else the project's keys. */
+async function platformFor(project: LocalProject, link: SyncLink): Promise<Platform> {
+  const person = await targetSession(project, link)
+  if (!person) return keysFor(project, link)
+  const profile = targetProfileName(project, link)
+  const api = platform(link, { as: 'person', profile, token: person.token, email: person.email ?? null, organizationKeyStored: !!getSyncKey(project, 'organization') })
+  // The platform drops the workspace from a session that isn't a member's, and every change-request call then fails.
+  const me = await api.call<{ workspaceId?: string | null }>('GET', '/v1/whoami')
+  if (me.workspaceId?.toLowerCase() !== link.workspace.toLowerCase()) {
+    throw new CliError(`signed in as ${person.email ?? 'someone'} for ${profile}, who is not a member of ${link.workspaceName ?? link.workspace}`, { code: 'SYNC_NOT_A_MEMBER', hint: `sign out with \`frontera auth logout --profile ${profile}\` and sign in as a member (\`${signInCommand(profile)}\`), or ask a workspace admin to add you` })
+  }
+  return api
+}
+
+function keysFor(project: LocalProject, link: SyncLink): Platform {
+  const workspaceKey = getSyncKey(project, 'workspace')
+  if (!workspaceKey) throw new CliError('no workspace key for this project on this machine', { code: 'SYNC_NO_KEY', hint: 'run `frontera local sync connect` to store one (keys are per machine)' })
+  return platform(link, { as: 'keys', profile: targetProfileName(project, link), workspaceKey, organizationKey: getSyncKey(project, 'organization') })
+}
+
+/**
+ * A request takes pushes, evidence, close and Apply from the one who proposed
+ * it (a workspace admin aside), so a request is another's when `acting` did
+ * not propose it: `key` when the project's workspace key did and a person
+ * acts now, `person` when a person did and the keys act now. Null when it is
+ * `acting`'s, or the view does not say.
+ */
+function proposedByOther(acting: Acting, view: View): 'key' | 'person' | null {
+  const author = view.request.authorId
+  if (typeof author !== 'string') return null
+  if (acting.as === 'person') return author.startsWith('wskey:') ? 'key' : null
+  return /^(wskey|orgkey|apikey):/.test(author) ? null : 'person'
+}
+
+/** The refusal, with the way out, for a command on a request `acting` did not propose; null when it did. */
+function notProposer(acting: Acting, view: View, doing: 'apply' | 'push to' | 'close' | 'attach evidence to'): CliError | null {
+  const by = proposedByOther(acting, view)
+  const title = view.request.title
+  if (by === 'person') return new CliError(`“${title}” was proposed by a person signed in for this project’s workspace, and no one is signed in on this computer now`, { code: 'SYNC_NOT_SIGNED_IN', hint: `sign in again with \`${signInCommand(acting.profile)}\`, then run the command again` })
+  if (by !== 'key' || acting.as !== 'person') return null
+  const closeIt = 'close it (`frontera local sync request close` closes it with that key)'
+  const withKeys = doing === 'apply' && (acting.organizationKeyStored || !view.items.some((i) => i.kind === 'blueprint'))
+  return new CliError(`“${title}” was proposed with this project’s workspace key before you signed in, so it isn’t yours to ${doing}`, {
+    code: 'SYNC_PROPOSED_WITH_KEY',
+    hint: doing === 'apply'
+      ? `${closeIt}, then push the changes again as yourself (\`${pushAgain(view)}\`) and apply${withKeys ? `; or sign out (\`frontera auth logout --profile ${acting.profile}\`) to apply it with the project’s keys` : ''}`
+      : `${closeIt}, then push again to propose the changes as yourself`,
+  })
+}
+
+/** Who proposed the change request a step is for: nobody yet, the person signed in, or the project's workspace key. */
+type ProposedBy = 'nobody' | 'you' | 'key'
+
+/** The push that proposes these refs and App releases (`--release`'s value), with the title. */
+function pushCommand(title: string | null, refs: string[], releases?: string): string {
+  return ['frontera local sync push', ...refs, ...(releases ? [`--release ${releases}`] : []), `-t "${title ?? '<title>'}"`].join(' ')
+}
+
+/** The push that proposes a request's items again: a Custom App's release by `--release`, anything else by its ref. */
+function pushAgain(view: View): string {
+  const release = (i: ViewItem) => (i.kind === 'app' ? releasedDeployment(i) : null)
+  const refs = view.items.filter((i) => !release(i) || Object.keys(i.files).length > 1).map((i) => i.ref)
+  return pushCommand(view.request.title, refs, view.items.flatMap((i) => (release(i) ? [`${i.name}=${release(i)}`] : [])).join(','))
+}
+
+/**
+ * How a person signed in goes with the organization key stored instead. The
+ * keys apply only a request they proposed, so the person's own request is
+ * closed first and pushed again (`push`, the command that proposes its items);
+ * the key's is applied as it is.
+ */
+function withStoredKey(acting: Extract<Acting, { as: 'person' }>, push: string, proposed: ProposedBy): string {
+  const signOut = `sign out (\`frontera auth logout --profile ${acting.profile}\`)`
+  const apply = 'apply (`frontera local sync request apply`)'
+  if (proposed === 'key') return `${signOut}, then ${apply}`
+  const pushIt = `push${proposed === 'you' ? ' it again' : ''} (\`${push}\`) and ${apply}`
+  return proposed === 'you' ? `close it (\`frontera local sync request close\`), ${signOut}, then ${pushIt}` : `${signOut}, then ${pushIt}`
+}
+
+/** A refusal of the person's role, with the way to act with the organization key stored instead. */
+function orStoredKey(err: unknown, acting: Acting, push: string, proposed: ProposedBy): unknown {
+  if (!(err instanceof CliError) || err.code !== 'FORBIDDEN' || acting.as !== 'person' || !acting.organizationKeyStored) return err
+  return new CliError(err.message, { code: err.code, hint: `your role decides what you may propose and apply. To use the organization key stored for this project instead, ${withStoredKey(acting, push, proposed)}; or ask a workspace admin` })
+}
+
+/**
+ * Whether Apply would stop at a step of these items that a Blueprint Steward
+ * makes and the checks' principal can't. The plan's `blueprint` step stands
+ * for every Blueprint file but a saved object set, whose own step an
+ * organization admin takes too. A new Agent's grants wait until after Apply.
+ */
+function stewardStepUnmet(person: ReturnType<typeof needsAPerson>, items: Array<{ ref: string; kind: string }>): boolean {
+  return person.some((p) => (p.code === 'blueprint_needs_steward' || p.code === 'grant_needs_steward') && !p.after && items.some((i) => i.ref === p.ref || (p.ref === 'blueprint' && i.kind === 'blueprint' && !i.ref.startsWith('blueprint/object-sets/'))))
+}
+
+/**
+ * The refusal of Blueprint changes and grants the person signed in could not
+ * apply (`unmet`): with an organization key stored, the keys propose and
+ * apply them instead.
+ */
+function notSteward(acting: Acting, unmet: boolean, push: string, proposed: ProposedBy): CliError | null {
+  if (acting.as !== 'person' || !acting.organizationKeyStored || !unmet) return null
+  return new CliError(`you are signed in as ${acting.email ?? 'someone'}, who is not a Blueprint Steward, so the Blueprint changes and grants in this change request could not be applied as you`, {
+    code: 'SYNC_NOT_A_STEWARD',
+    hint: proposed === 'key'
+      ? `${withStoredKey(acting, push, proposed)}: the project’s keys proposed it, and Apply uses the organization key stored for this project`
+      : `${withStoredKey(acting, push, proposed)}: the project’s keys propose it, and Apply uses the organization key stored for this project; or ask a Blueprint Steward to sign in for this project and push it`,
+  })
+}
+
+/** The organization key a command sends beside the workspace key: none when a person acts. */
+const organizationKeyOf = (acting: Acting) => (acting.as === 'keys' ? acting.organizationKey : null)
+
+/**
+ * What Forge reads about who applies Blueprint changes: an organization key
+ * is needed only when no person is signed in, and `signIn` is the step that
+ * makes it unneeded.
+ */
+function stewardData(acting: Acting, blueprint: boolean, stored: boolean) {
+  return {
+    organizationKey: { needed: blueprint && acting.as === 'keys', stored },
+    signIn: blueprint && acting.as === 'keys' && !acting.organizationKey ? signInCommand(acting.profile) : null,
+  }
+}
+
+/**
+ * Who applies the request's Blueprint changes, in words, for the preview
+ * (`proposed` false: nothing is proposed yet), the push and the request. A
+ * request the keys propose stays the keys', so the sign-in comes before the
+ * push.
+ */
+function stewardNote(acting: Acting, proposed: boolean, push: string): string {
+  if (acting.as === 'person') return `Blueprint changes are applied as you (${acting.email ?? 'signed in'})${acting.organizationKeyStored ? `; the organization key stored for this project is not used while you’re signed in: to apply ${proposed ? 'this change request ' : ''}with it instead, ${withStoredKey(acting, push, proposed ? 'you' : 'nobody')}` : ''}.`
+  if (acting.organizationKey) return 'Blueprint changes are applied with the organization key stored for this project.'
+  const signIn = `\`${signInCommand(acting.profile)}\``
+  return proposed
+    ? `Blueprint changes are applied by a Blueprint Steward, signed in, and this change request was proposed with the project’s workspace key: to apply it as yourself, sign in (${signIn}), close it (\`frontera local sync request close\`) and push again.`
+    : `Blueprint changes are applied by a Blueprint Steward, signed in: sign in before you push, so the change request is yours to apply (${signIn}).`
 }
 
 // ── The platform's view of a request ────────────────────────────────────────
@@ -422,11 +572,11 @@ async function platformDocuments(api: Platform, names: string[], remote: Array<{
  * own in-use check before anything is proposed, so a deletion names its
  * dependents first. An older platform without the read says nothing.
  */
-async function deletionUsers(project: LocalProject, link: SyncLink, items: PushItem[]): Promise<Map<string, string[]>> {
+async function deletionUsers(api: Platform, items: PushItem[]): Promise<Map<string, string[]>> {
   const refs = items.filter((i) => i.change === 'deleted' && i.proposable && i.kind !== 'blueprint').map((i) => i.ref)
   if (!refs.length) return new Map()
   try {
-    const answer = await platformFor(project, link).call<{ items: Array<{ ref: string; usedBy: string[] }> }>('POST', '/v1/change-requests/usage', { refs })
+    const answer = await api.call<{ items: Array<{ ref: string; usedBy: string[] }> }>('POST', '/v1/change-requests/usage', { refs })
     return new Map((answer.items ?? []).filter((u) => u.usedBy.length).map((u) => [u.ref, u.usedBy]))
   } catch {
     return new Map()
@@ -535,7 +685,7 @@ export async function syncMapModel(ctx: CommandContext): Promise<{ data: unknown
     return { data: { local, workspace: null }, text: `${local} is no longer mapped: an item that names it isn’t proposed until it is mapped again.` }
   }
   if (!workspace) throw new UsageError('name the workspace model it goes as', `frontera local sync map-model ${local} <workspace model>; \`push --preview\` lists ${name}’s models`)
-  const offered = await workspaceModels(platformFor(project, link))
+  const offered = await workspaceModels(await platformFor(project, link))
   if (offered.length && !offered.some((m) => m.slug === workspace)) {
     throw new UsageError(`${name} has no chat model ${workspace}`, `choose one of: ${offered.map((m) => m.slug).slice(0, 12).join(', ')}${offered.length > 12 ? ', …' : ''}`)
   }
@@ -559,15 +709,15 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
   const documentNames = asked.includes('*') ? knowledgeHere : asked
   const notHere = documentNames.filter((n) => !knowledgeHere.includes(n))
   if (notHere.length) throw new UsageError(`no knowledge base ${notHere.join(', ')} in this project`, '--documents takes knowledge base names (knowledge/<name>), or * for every one')
+  const api = await platformFor(project, link)
   const documents = documentNames.length
-    ? { names: new Set(documentNames), pulled: readPulledDocuments(project.root, link.workspace).bases, platform: await platformDocuments(platformFor(project, link), documentNames, remote.items) }
+    ? { names: new Set(documentNames), pulled: readPulledDocuments(project.root, link.workspace).bases, platform: await platformDocuments(api, documentNames, remote.items) }
     : undefined
   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, getSyncKey(project, 'organization')) : { checked: false, refused: [] as string[], plan: [] as ApplyStep[] }
+  const checked = available ? await precheck(api, all, organizationKeyOf(api.acting)) : { 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
@@ -587,17 +737,33 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
   } else chosen = all
   // Samples from setting up the project go only when named.
   const leftSamples = named.length ? [] : chosen.filter((i) => i.proposable && i.sample)
-  const orgNote = needsOrganizationKey(chosen) ? (orgStored ? 'Blueprint changes are applied with the organization key stored for this project.' : 'Blueprint changes need the organization key to apply: connect again with `--org-key -` before applying.') : null
+  const title = flagString(ctx, 'title')?.trim()
+  // The current request still taking pushes is updated; one applied or closed (here or on the platform) is not.
+  let target = updating
+  let stop: CliError | null = null
+  if (target) {
+    const live = await api.call<View>('GET', `/v1/change-requests/${target.id}`).catch((err: CliError) => (err.code === 'NOT_FOUND' ? null : Promise.reject(err)))
+    if (!live || !isOpen(live.request.state)) {
+      if (live) recordRequest(project.root, link.workspace, live)
+      target = null
+    } else stop = notProposer(api.acting, live, 'push to')
+  }
+  // Following a refusal proposes what was asked: the items named (none: every change) and the releases.
+  const again = pushCommand(target?.title ?? title ?? null, named, flagString(ctx, 'release'))
+  stop ??= notSteward(api.acting, stewardStepUnmet(person, chosen), again, target ? 'you' : 'nobody')
+  const orgNote = needsOrganizationKey(chosen) ? stewardNote(api.acting, false, pushCommand(title ?? null, named, flagString(ctx, 'release'))) : null
 
   if (preview) {
-    const usedBy = available ? await deletionUsers(project, link, chosen) : new Map<string, string[]>()
+    const usedBy = available ? await deletionUsers(api, chosen) : new Map<string, string[]>()
     return {
       data: {
         link,
         available,
-        request: updating ? { id: updating.id, title: updating.title, state: updating.state, items: updating.refs.length, refs: updating.refs } : null,
+        request: target ? { id: target.id, title: target.title, state: target.state, items: target.refs.length, refs: target.refs } : null,
         items: chosen.map((i) => ({ ...itemJson(i), ...(usedBy.has(i.ref) ? { usedBy: usedBy.get(i.ref) } : {}) })),
         counts: { proposable: chosen.filter((i) => i.proposable && !i.sample).length, samples: leftSamples.length, blocked: chosen.filter((i) => !i.proposable).length },
+        // A push now would be refused before anything is sent: why, and the way out.
+        refused: stop ? { code: stop.code, message: stop.message, hint: stop.hint } : null,
         // Whether the workspace's checks ran before proposing; a platform without them checks at Propose.
         checked: checked.checked,
         ...(('problem' in checked && checked.problem) ? { checkProblem: checked.problem } : {}),
@@ -606,14 +772,14 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
           workspace: missing.size ? await workspaceModels(api) : [],
           mapped: link.models ?? {},
         },
-        organizationKey: { needed: needsOrganizationKey(chosen), stored: orgStored },
+        ...stewardData(api.acting, needsOrganizationKey(chosen), orgStored),
         // Apply's steps in order, and the ones the project's credentials can't take (N3).
         applyPlan: checked.plan,
         needsPerson: person,
         notCarried,
         fetchedAt: snapshot.fetchedAt,
       },
-      text: previewText(link, chosen, updating, orgNote, available, usedBy, person, mcp?.line),
+      text: previewText(link, chosen, target, stop ? `A push now would be refused: ${stop.message}; ${stop.hint}.` : orgNote, available, usedBy, person, mcp?.line),
     }
   }
 
@@ -645,17 +811,8 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
       hint: `${mcp ? `${mcp.line} For anything else, ` : ''}change an item in the project first; \`frontera local sync status\` shows where it stands`,
     })
   }
-  const title = flagString(ctx, 'title')?.trim()
   const description = flagString(ctx, 'description')
-  // The current request still taking pushes is updated; one applied or closed (here or on the platform) is not.
-  let target = updating
-  if (target) {
-    const live = await api.call<View>('GET', `/v1/change-requests/${target.id}`).catch((err: CliError) => (err.code === 'NOT_FOUND' ? null : Promise.reject(err)))
-    if (!live || !isOpen(live.request.state)) {
-      if (live) recordRequest(project.root, link.workspace, live)
-      target = null
-    }
-  }
+  if (stop) throw stop
   if (!target && !title) throw new UsageError('give the change request a title', 'frontera local sync push -t "Tighten the refund procedure"')
 
   // Custom App releases: each names a deployment that already exists. A later push keeps the releases the request has.
@@ -677,7 +834,7 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
         details: { checks },
       })
     }
-    throw err
+    throw orStoredKey(err, api.acting, again, target ? 'you' : 'nobody')
   }
   // A knowledge base's documents follow the request, one at a time (each up to the platform's limit).
   const staged = await stageDocuments(project, api, view)
@@ -695,7 +852,7 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
       releases: releases.map((r) => ({ ref: r.ref, deployment: r.deployment })),
       notProposed: notProposed.map((i) => ({ ref: i.ref, code: i.blocked, message: i.reason, ...(i.fix ? { fix: i.fix } : {}) })),
       samples: leftSamples.map((i) => i.ref),
-      organizationKey: { needed: needsOrganizationKey(view.items), stored: orgStored },
+      ...stewardData(api.acting, needsOrganizationKey(view.items), orgStored),
       notCarried,
     },
     text: [
@@ -704,7 +861,7 @@ export async function syncPush(ctx: CommandContext): Promise<{ data: unknown; te
       ...releases.map((r) => `  Custom App ${r.slug}: release ${r.deployment}${r.chosen ? ' (its newest deployment)' : ''}; Apply promotes it last`),
       ...(notProposed.length ? ['', 'Not proposed:', ...notProposed.flatMap((i) => [`  ${KIND_WORD[i.kind]} ${i.title}: ${i.reason}`, ...(i.fix ? [`    Fix: ${i.fix}`] : [])])] : []),
       ...(leftSamples.length ? ['', `Left out: ${plural(leftSamples.length, 'sample')} from setting up the project (${leftSamples.map((i) => i.title).join(', ')}); name ${leftSamples.length === 1 ? 'it' : 'them'} to propose`] : []),
-      ...(orgNote ? ['', orgNote] : []),
+      ...(needsOrganizationKey(view.items) ? ['', stewardNote(api.acting, true, pushAgain(view))] : []),
       ...(mcp ? ['', mcp.line] : []),
       '',
       'Apply it with `frontera local sync request apply`; see it with `frontera local sync request`.',
@@ -745,7 +902,7 @@ async function basesFor(project: LocalProject, link: SyncLink, view: View): Prom
     // Earlier versions the platform keeps: workflows, Functions and the Blueprint by revision.
     if (item.kind === 'agent' || !HISTORY_KINDS.includes(item.kind) || !snapshot?.capabilities.includes('item-revision')) continue
     try {
-      const source = sourceFor(project, link)
+      const source = await sourceFor(project, link)
       const asked = item.kind === 'blueprint' ? 'blueprint' : item.ref
       const answer = await source.workspace.find<{ ref: string; kind: string; revision: string; content: Record<string, unknown> }>(`/v1/sync/item?ref=${encodeURIComponent(asked)}&revision=${encodeURIComponent(item.baseRevision)}`)
       if (answer) {
@@ -835,12 +992,13 @@ function activityOf(view: View, titles: Record<string, string>) {
     })
 }
 
-async function currentView(project: LocalProject, link: SyncLink): Promise<{ view: View; titles: Record<string, string> } | null> {
+async function currentView(project: LocalProject, link: SyncLink): Promise<{ view: View; titles: Record<string, string>; api: Platform } | null> {
   const kept = currentRequest(readRequests(project.root, link.workspace))
   if (!kept) return null
-  const view = await platformFor(project, link).call<View>('GET', `/v1/change-requests/${kept.id}`)
+  const api = await platformFor(project, link)
+  const view = await api.call<View>('GET', `/v1/change-requests/${kept.id}`)
   recordRequest(project.root, link.workspace, view)
-  return { view, titles: kept.titles }
+  return { view, titles: kept.titles, api }
 }
 
 /**
@@ -903,6 +1061,8 @@ async function show(ctx: CommandContext) {
   const activity = activityOf(view, allTitles)
   const orgStored = !!getSyncKey(project, 'organization')
   const r = view.request
+  const { acting } = current.api
+  const other = isOpen(r.state) ? proposedByOther(acting, view) : null
   return {
     data: {
       request: { id: r.id, title: r.title, description: r.description, state: r.state, stateLabel: STATE_WORD[r.state] ?? r.state, createdAt: r.createdAt, updatedAt: r.updatedAt, mergedAt: r.mergedAt },
@@ -910,7 +1070,7 @@ async function show(ctx: CommandContext) {
       items,
       activity,
       checks: checks.filter((c) => !items.some((i) => i.ref === c.ref)).map((c) => ({ ref: c.ref, code: c.code, message: c.message })),
-      organizationKey: { needed: needsOrganizationKey(view.items), stored: orgStored },
+      ...stewardData(acting, needsOrganizationKey(view.items), orgStored),
       gate: view.gate ?? null,
       evidence: view.evidence ?? [],
     },
@@ -930,7 +1090,10 @@ async function show(ctx: CommandContext) {
       '',
       'Activity:',
       ...activity.map((a) => `  ${a.at.slice(0, 16).replace('T', ' ')}  ${a.text}`),
-      ...(isOpen(r.state) ? ['', 'Apply it with `frontera local sync request apply`, or close it with `request close`.'] : []),
+      ...(isOpen(r.state) && !other && needsOrganizationKey(view.items) ? ['', stewardNote(acting, true, pushAgain(view))] : []),
+      ...(other === 'key' ? ['', 'Proposed with the project’s workspace key before you signed in: close it (`frontera local sync request close`) and push again to apply it as yourself.'] : []),
+      ...(other === 'person' ? ['', `Proposed by a person signed in, and no one is signed in on this computer now: sign in again with \`${signInCommand(acting.profile)}\` to apply it.`] : []),
+      ...(isOpen(r.state) && !other ? ['', 'Apply it with `frontera local sync request apply`, or close it with `request close`.'] : []),
     ].join('\n'),
   }
 }
@@ -940,15 +1103,27 @@ async function apply(ctx: CommandContext) {
   const link = needLink(project)
   const current = await currentView(project, link)
   if (!current) throw new UsageError('no change request to apply', 'propose one with `frontera local sync push -t "<title>"`')
-  const { view, titles } = current
+  const { view, titles, api } = current
+  const { acting } = api
   if (view.request.state === 'merged') throw new CliError(`“${view.request.title}” is already applied`, { code: 'CONFLICT', hint: 'propose new changes with `frontera local sync push -t "<title>"`' })
   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 proposed: ProposedBy = proposedByOther(acting, view) === 'key' ? 'key' : 'you'
+  if (acting.as === 'person' && acting.organizationKeyStored && view.items.some((i) => i.kind === 'blueprint' || i.kind === 'agent')) {
+    // The platform refuses a person who is no Steward only once Apply runs, so ask its checks, with every item so references resolve.
+    const items = view.items.map((i) => ({ ref: i.ref, files: i.files, ...(i.baseRevision ? { baseRevision: i.baseRevision } : {}), ...(i.deleted ? { deleted: true } : {}) }))
+    const plan = await api.call<unknown>('POST', '/v1/change-requests/check', { items }, { timeoutMs: 120_000 }).then(planOf, () => [])
+    const stop = notSteward(acting, stewardStepUnmet(needsAPerson(plan), view.items), pushAgain(view), proposed)
+    if (stop) throw stop
+  }
+  const refused = notProposer(acting, view, 'apply')
+  // A workspace admin signed in may apply another's request once every item is approved: the platform decides.
+  if (refused && !(acting.as === 'person' && view.request.state === 'approved')) throw refused
   const allTitles = Object.fromEntries(view.items.map((i) => [i.ref, titleOf(i, titles)]))
   const blueprint = view.items.some((i) => i.kind === 'blueprint')
-  // 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' })
+  // With the keys, 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 = organizationKeyOf(acting)
+  if (blueprint && acting.as === 'keys' && !organizationKey) {
+    throw new CliError('this change request changes the Blueprint, which a Blueprint Steward applies as themself, and no one is signed in for this project’s workspace on this computer', { code: 'SYNC_NOT_SIGNED_IN', hint: `sign in with \`${signInCommand(acting.profile)}\`, then close this change request (\`frontera local sync request close\`) and push it again, so it is yours to apply` })
   }
   const migration = flagString(ctx, 'migration')?.trim()
   const force = flagBool(ctx, 'force')
@@ -957,7 +1132,7 @@ async function apply(ctx: CommandContext) {
   let answer: View
   try {
     // The key in the body: the platform's edge strips `x-frontera-*` headers a client sends. The header stays for an older platform.
-    answer = await platformFor(project, link).call<View>('POST', `/v1/change-requests/${view.request.id}/apply`, { ...(migration ? { migrationInstruction: migration } : {}), ...(force ? { force: { reason } } : {}), ...(organizationKey ? { organizationKey } : {}) }, { organizationKey, timeoutMs: 15 * 60_000 })
+    answer = await api.call<View>('POST', `/v1/change-requests/${view.request.id}/apply`, { ...(migration ? { migrationInstruction: migration } : {}), ...(force ? { force: { reason } } : {}), ...(organizationKey ? { organizationKey } : {}) }, { organizationKey, timeoutMs: 15 * 60_000 })
   } catch (err) {
     if (err instanceof CliError && err.code === 'SYNC_APPLY_GATED') {
       const gate = (err.details as { gate?: Gate } | undefined)?.gate
@@ -973,7 +1148,8 @@ async function apply(ctx: CommandContext) {
         details: { checks },
       })
     }
-    throw err
+    if (refused && err instanceof CliError && err.code === 'FORBIDDEN') throw refused
+    throw orStoredKey(err, acting, pushAgain(view), proposed)
   }
   const outcome = parseOutcome(answer.outcome)
   recordRequest(project.root, link.workspace, answer, { applied: { ok: outcome.ok } })
@@ -981,9 +1157,14 @@ async function apply(ctx: CommandContext) {
     // Fetch, so the project sees the workspace as it was put back. The request itself applies again as it is:
     // the platform takes each put-back item's new revision as its base.
     await fetchFor(project, link).catch(() => null)
+    // When the checks could not be read before sending, the Steward refusal comes back as the failed step.
+    const stewardFailed = /Blueprint Steward assignment required/.test(outcome.failure?.message ?? '')
+    const steward = notSteward(acting, stewardFailed, pushAgain(view), proposed)
+    // With no organization key stored, applying again fails the same way.
+    const noKey = stewardFailed ? 'ask a Blueprint Steward who is a workspace admin to approve it and apply it; or store the project’s organization key (`frontera local sync connect --workspace-key - --org-key -`), then apply again (`frontera local sync request apply`) and follow the steps it prints' : null
     throw new CliError(describeOutcome(outcome, allTitles).join('\n'), {
       code: 'SYNC_APPLY_FAILED',
-      hint: /migration instruction/i.test(outcome.failure?.message ?? '') ? 'say what to do with existing records: apply again with `--migration "<instructions>"`' : 'once what failed is fixed, apply again (`frontera local sync request apply`); a fix in the project’s files is pushed first (`frontera local sync push`)',
+      hint: steward?.hint ?? noKey ?? (/migration instruction/i.test(outcome.failure?.message ?? '') ? 'say what to do with existing records: apply again with `--migration "<instructions>"`' : 'once what failed is fixed, apply again (`frontera local sync request apply`); a fix in the project’s files is pushed first (`frontera local sync push`)'),
       details: { outcome, failed: outcome.failure ? { ref: outcome.failure.ref, title: failedName(outcome, allTitles), message: outcome.failure.message } : null },
     })
   }
@@ -1003,7 +1184,7 @@ async function apply(ctx: CommandContext) {
     fetched.error = (err as Error).message
   }
   // Documents applied are the project's copies of the workspace's now: recorded as a pull records them.
-  await recordAppliedDocuments(project, link, answer).catch(() => null)
+  await recordAppliedDocuments(project, link, api, 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).
@@ -1015,16 +1196,16 @@ async function apply(ctx: CommandContext) {
   const pending = recordAfterApply(project.root, answer.request.title, after, target ? { profile: target, target: targetOf(link) } : null)
   const signIn = target && pending.length ? await signInStep({ profile: target, apiUrl: link.platform, named: true }) : null
   return {
-    data: { applied: true, outcome, request: { id: answer.request.id, title: answer.request.title, state: answer.request.state }, fetched, pendingInWorkspace: pending },
+    data: { applied: true, as: { signedIn: acting.as === 'person', email: acting.as === 'person' ? acting.email : null, profile: acting.profile }, 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}.`,
+      `Applied “${answer.request.title}” to ${link.workspaceName ?? link.workspace}${acting.as === 'person' ? ` as ${acting.email ?? 'you'} (signed in)` : ''}.`,
       ...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)' : ''}`),
           target
-            ? `They run against ${new URL(link.platform).host} with \`--profile ${target}\` (this project's keys), not the local runtime${signIn ? `; a step a signed-in person takes needs \`${signIn}\` first` : ''}.`
+            ? `They run against ${new URL(link.platform).host} with \`--profile ${target}\` (${getSyncKey(project, 'organization') ? "this project's keys" : 'as the person signed in on it'}), not the local runtime${signIn ? `; a step a signed-in person takes needs \`${signIn}\` first` : ''}.`
             : `They name no target: the CLI could not record a profile for ${new URL(link.platform).host}${targetError ? ` (${targetError})` : ''}. Add \`--profile <a profile for that platform>\` when you run them.`,
           'Forge lists them on the project’s home; `frontera local steps` here.']
         : []),
@@ -1037,12 +1218,11 @@ async function apply(ctx: CommandContext) {
  * workspace's new copy (the newest document of that name), and each taken off
  * is forgotten, so the next push sees them as unchanged.
  */
-async function recordAppliedDocuments(project: LocalProject, link: SyncLink, view: View): Promise<void> {
+async function recordAppliedDocuments(project: LocalProject, link: SyncLink, api: Platform, view: View): Promise<void> {
   const items = view.items.filter((i) => i.kind === 'knowledge' && i.documents)
   if (!items.length) return
   const snapshot = readSnapshot(project.root)
   const remote = snapshot ? snapshotItems(project.root, snapshot) : []
-  const api = platformFor(project, link)
   for (const item of items) {
     const id = remote.find((r) => r.ref === item.ref)?.id
     if (!id) continue
@@ -1071,9 +1251,14 @@ async function close(ctx: CommandContext) {
   const link = needLink(project)
   const kept = currentRequest(readRequests(project.root, link.workspace))
   if (!kept || !isOpen(kept.state)) throw new UsageError('no open change request to close', 'see where it stands with `frontera local sync request`')
-  const view = await platformFor(project, link).call<View>('POST', `/v1/change-requests/${kept.id}/close`, {})
+  const current = (await currentView(project, link))!
+  // Closing writes nothing to the workspace, so a request the project's key proposed is closed with that key.
+  const byKey = proposedByOther(current.api.acting, current.view) === 'key'
+  const refused = byKey ? null : notProposer(current.api.acting, current.view, 'close')
+  if (refused) throw refused
+  const view = await (byKey ? keysFor(project, link) : current.api).call<View>('POST', `/v1/change-requests/${kept.id}/close`, {})
   recordRequest(project.root, link.workspace, view)
-  return { data: { closed: true, request: { id: view.request.id, title: view.request.title, state: view.request.state } }, text: `Closed “${view.request.title}”. The project’s files are unchanged; the next push opens a new change request.` }
+  return { data: { closed: true, request: { id: view.request.id, title: view.request.title, state: view.request.state } }, text: `Closed “${view.request.title}”${byKey ? ' with the project’s workspace key that proposed it' : ''}. The project’s files are unchanged; the next push opens a new change request.` }
 }
 
 /**
@@ -1089,13 +1274,14 @@ async function evidence(ctx: CommandContext) {
   const link = needLink(project)
   const current = await currentView(project, link)
   if (!current) throw new UsageError('no change request to attach evidence to', 'propose one with `frontera local sync push -t "<title>"`')
-  const { view, titles } = current
+  const { view, titles, api } = current
   if (!isOpen(view.request.state)) throw new CliError(`“${view.request.title}” is ${STATE_WORD[view.request.state] ?? view.request.state}; it takes no evidence`, { code: 'CONFLICT', hint: 'propose new changes with `frontera local sync push -t "<title>"`' })
+  const refused = notProposer(api.acting, view, 'attach evidence to')
+  if (refused) throw refused
   const session = flagString(ctx, 'screenshots') ?? process.env.FORGE_SESSION ?? null
   const trace = flagString(ctx, 'trace')
   const any = flagBool(ctx, 'evals') || flagBool(ctx, 'renders') || flagString(ctx, 'screenshots') !== undefined || trace !== undefined
   const want = { evals: any ? flagBool(ctx, 'evals') : true, renders: any ? flagBool(ctx, 'renders') : true, screenshots: any ? flagString(ctx, 'screenshots') !== undefined : !!session }
-  const api = platformFor(project, link)
   const attach = (body: Record<string, unknown>) => api.call<View>('POST', `/v1/change-requests/${view.request.id}/evidence`, body, { timeoutMs: 120_000 })
   const lines: string[] = []
   const attached: Array<{ kind: string; ref: string | null; title: string }> = []
@@ -1207,7 +1393,7 @@ async function evidenceImage(ctx: CommandContext) {
     const path = join(dir, `${id}.${ext}`)
     if (existsSync(path)) return { data: { path, mime: Object.entries(PICTURE_EXT).find(([, e]) => e === ext)![0] }, text: path }
   }
-  const { bytes, mime } = await platformFor(project, link).bytes(`/v1/change-requests/${kept.id}/evidence/${id}/content`)
+  const { bytes, mime } = await (await platformFor(project, link)).bytes(`/v1/change-requests/${kept.id}/evidence/${id}/content`)
   const ext = PICTURE_EXT[mime.split(';')[0]!.trim()]
   if (!ext) throw new CliError('the platform did not answer with a picture', { code: 'UNAVAILABLE', hint: 'run the command again' })
   mkdirSync(dir, { recursive: true })