@frontera-sdk/cli 1.53.5 → 1.53.7

package/src/device-login.ts

@@ -1,4 +1,4 @@
-import type { CredentialStore } from './credential-store'
+import { credentialStore, type CredentialStore } from './credential-store'
 import { CliError } from './errors'
 
 /**
@@ -128,6 +128,24 @@ export async function readDeviceSession(store: CredentialStore, profile: string,
   }
 }
 
+/** How long a stored session must still last for a printed sign-in step to be left out: the steps after it take a few minutes. */
+const SIGN_IN_STEP_MARGIN_MS = 5 * 60_000
+
+/**
+ * The sign-in step a list of next steps starts with: `frontera auth login --browser`, with
+ * `--profile` when the steps name one. Null when that profile already holds a browser
+ * session for this platform that lasts past the next few minutes, so a person who signed
+ * in is not asked again at every printed step.
+ */
+export async function signInStep(
+  at: { profile?: string; apiUrl: string; named?: boolean },
+  store: CredentialStore = credentialStore(),
+  now = Date.now(),
+): Promise<string | null> {
+  if (at.profile && (await readDeviceSession(store, at.profile, at.apiUrl, now + SIGN_IN_STEP_MARGIN_MS))) return null
+  return `frontera auth login --browser${at.named && at.profile ? ` --profile ${at.profile}` : ''}`
+}
+
 /** 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)

package/src/exit.ts

@@ -74,6 +74,8 @@ const USAGE_CODES = new Set([
   // An Action that isn't there to submit, or a submit without the key it needs.
   'ACTION_NOT_FOUND',
   'ACTION_IDEMPOTENCY_KEY_REQUIRED',
+  // `blueprint publish` without the --instruction its changes need: fixed in the command.
+  'MIGRATION_INSTRUCTION_REQUIRED',
 ])
 /**
  * Someone changed it first: re-read, then decide or submit again. Each of
@@ -115,6 +117,9 @@ const CONFLICT_CODES = new Set([
   'AUTOMATION_PUBLISH_UNCERTAIN',
   // The dataset's rows are written somewhere else now.
   'DATASET_AUTHORITY_MOVED',
+  // A release the draft's state refuses (an Action without a deployment decision, a
+  // missing column): the same publish is refused until that is cleared.
+  'RELEASE_BLOCKED',
 ])
 /**
  * Refusals the service sends under another code with a `reason` that is a

package/src/flag-help.ts

@@ -127,6 +127,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   framework: 'App scaffold to create: next (default) or react (legacy Vite)',
   port: 'loopback port to listen on — the App development server, or the Forge daemon (0: any free port)',
   'no-open': 'start local development without opening a browser window',
+  detach: 'start the App development server in its own session and return once it answers: it keeps running after this shell ends',
   'no-install': 'scaffold without running `bun install` — for an offline machine or a sandbox',
   'no-git': 'scaffold without creating a repository and an initial commit',
   'no-components': 'scaffold without fetching the baseline shadcn components',
@@ -283,7 +284,7 @@ export const FLAG_HELP: Readonly<Record<string, string>> = {
   title: 'the change request’s title; a push that opens a new one needs it',
   why: 'a person-step: why it is needed now, in a sentence',
   changes: 'a person-step: what it changes, in the workspace’s words',
-  credential: 'a person-step: who or what it needs (workspace-key, organization-key, steward, admin, second-person, person)',
+  credential: 'a person-step: who or what it needs (workspace-key, organization-key, steward, admin, second-person, person, registry-owner)',
   delivery: 'a person-step: the delivery it belongs to; steps with the same one show as one card',
   all: 'list the settled ones too',
   browser: 'sign in by approving a code in the browser, as yourself',

package/src/forge/permission-rules.ts

@@ -113,6 +113,8 @@ export const FRONTERA_PERSON_COMMANDS: readonly string[] = [
   'app rollback',
   'agent publish',
   'chat-app publish',
+  // Live in the workspace at once, its tools run as whoever connects; a change request does not carry it.
+  'mcp-server save',
   'function promote',
   'workflow promote',
   'local sync request apply',

package/src/local/local-actions.ts

@@ -21,8 +21,8 @@ import type { LocalCredentials } from './local-state'
  *   after the publish    an Action that writes only the Blueprint's records gets its write
  *                        path (an ontology edit derived from the Action), built and validated
  *                        by the organization key, then reviewed and activated by the owner's
- *                        session (the service refuses a reviewer who built it); the owner role
- *                        may then invoke it
+ *                        session (an ontology edit, so its builder may review it); the owner
+ *                        role may then invoke it
  *
  * An Action whose effect would reach another system (a transition, a command)
  * keeps its switched-off decision: it is published, workflows that name it
@@ -170,8 +170,9 @@ export async function unpublishedActions(call: Call, apiNames: string[]): Promis
  * Actions whose contract moved after their decision was taken here (an edit
  * to the Action, or to a field of its object type), which blocks the publish:
  * a decision cannot follow a new contract. The draft's validation names them.
- * On the platform the cure is authoring the Action again under a new id; on
- * the local runtime `local dev` does that itself (see `dev.ts`).
+ * On the platform a person retires the old deployment (`action retire`), then
+ * publishes and deploys again; on the local runtime `local dev` authors the
+ * Action again under a new id itself (see `dev.ts`).
  */
 export async function staleActions(call: Call, apiNames: string[]): Promise<{ stale: string[]; consumed: string[] }> {
   const validated = await call('org', 'POST', '/v1/blueprint/lifecycle/validate', {})
@@ -295,7 +296,7 @@ async function deployOne(call: Call, published: Deployable, attachment?: LocalAc
     if (findings.length) return { reason: `its write path did not validate (${findings.length} failed check${findings.length === 1 ? '' : 's'})`, findings }
     return `its write path did not validate: ${validation.status >= 300 ? message(validation) : failedChecks(report)}`
   }
-  // A different principal from the key that built it: the service insists.
+  // Review and activation take a person's session; the key only builds.
   const reviewed = await call('session', 'POST', `${ADMIN}/binding-revisions/${bindingRevisionId}/review`, { validationReportId: report.id, expectedStateGeneration: 2 })
   if (reviewed.status >= 300) return `its review was refused: ${message(reviewed)}`
   const revision = data<{ stateId?: string; stateGeneration?: number; actionDefinitionId?: string }>(await call('session', 'GET', `${ADMIN}/binding-revisions/${bindingRevisionId}`))

package/src/local/local-app-runtime.ts

@@ -1,6 +1,6 @@
 import { join } from 'node:path'
 
-import { readState } from '../project'
+import { appBinding, readState } from '../project'
 import { customAppFolders } from './local-apps'
 import type { LocalCredentials } from './local-state'
 
@@ -42,16 +42,18 @@ export function workspaceGet(serviceUrl: string, creds: Pick<LocalCredentials, '
  * holds it. Null when the runtime could not be asked; a folder the runtime
  * could not answer for is left out (the folder's record speaks for it).
  */
-export async function liveAppDeployments(root: string, get: Get | null): Promise<Map<string, LiveApp> | null> {
+export async function liveAppDeployments(root: string, get: Get | null, target: string): Promise<Map<string, LiveApp> | null> {
   if (!get) return null
   const out = new Map<string, LiveApp>()
   for (const dir of customAppFolders(root)) {
     const state = readState(join(root, dir))
     const deployment = typeof state.parentVersion === 'string' && state.parentVersion ? state.parentVersion : null
-    if (!deployment || !state.appId) continue
+    // The folder's App on this runtime (`appTarget`); an older CLI's single id otherwise.
+    const appId = appBinding(join(root, dir), target).id ?? state.appId
+    if (!deployment || !appId) continue
     const name = dir.split('/').pop()!
     try {
-      const res = await get(`/v1/platform-apps/${encodeURIComponent(state.appId)}/deployments`)
+      const res = await get(`/v1/platform-apps/${encodeURIComponent(appId)}/deployments`)
       if (res.status === 404) {
         out.set(name, { app: false, deployment: null })
         continue

package/src/local/local-blueprint-schemas.ts

@@ -113,7 +113,7 @@ const OBJECT_TYPE: JsonSchema = {
       type: 'object',
       description: 'Where the records come from: the dataset by NAME (its revision is resolved when applied), and one column per property. There is no name-match fallback.',
       properties: {
-        dataset: text('The dataset’s apiName (datasets/<apiName>.json).'),
+        dataset: text('The dataset’s apiName (datasets/<apiName>.json). Naming another dataset moves the type to it on `frontera blueprint apply` and in a change request’s Apply; each property keeps its column. A change request creates a new type bound to it, in the same release.'),
         mapping: {
           type: 'object',
           description: 'property apiName → its column, or { column, field } for a field inside a column.',
@@ -124,7 +124,7 @@ const OBJECT_TYPE: JsonSchema = {
             ],
           },
         },
-        editable: { type: 'array', items: { type: 'string' }, description: 'The properties a governed Action may write.' },
+        editable: { type: 'array', items: { type: 'string' }, description: 'The properties a governed Action may write. `frontera blueprint apply` and a change request’s Apply declare this list, for a type they create too; leave the key out to keep what the draft holds, or write [] for none.' },
       },
       required: ['dataset', 'mapping'],
     },

package/src/local/local-build-inputs.ts

@@ -1,4 +1,5 @@
 import { liveActionStates, localActionCalls, type LiveAction } from './local-actions'
+import { appTarget } from '../project'
 import { liveAppDeployments, workspaceGet, type LiveApp } from './local-app-runtime'
 import { projectBuildRows, projectBuildSummary, type BuildRow, type ProjectBuildSummary } from './local-build-summary'
 import { localSecretPresence, type SecretPresence } from './local-secrets'
@@ -26,7 +27,7 @@ export async function runtimeBuildInputs(state: LocalState | null, root?: string
   const [live, secrets, apps] = await Promise.all([
     creds.orgKey ? Promise.resolve().then(() => liveActionStates(localActionCalls(serviceUrl, creds))).catch(() => null) : Promise.resolve(null),
     localSecretPresence(serviceUrl, creds).catch(() => null),
-    root ? liveAppDeployments(root, workspaceGet(serviceUrl, creds)).catch(() => null) : Promise.resolve(null),
+    root ? liveAppDeployments(root, workspaceGet(serviceUrl, creds), appTarget(serviceUrl, creds.workspaceId)).catch(() => null) : Promise.resolve(null),
   ])
   return { live, secrets, apps }
 }

package/src/local/local-db-snapshot.ts

@@ -1,9 +1,7 @@
-import { createHash } from 'node:crypto'
 import { readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { writeFileAtomic } from '../fs-atomic'
-import { loadHashes } from './local-applied'
 import { appDeployments, appsLostByRestore, appsLostWords, markAppsLostByRestore, type AppLostByRestore } from './local-app-restore'
 import { execInContainer, queryInContainer } from './local-docker'
 import { dumpHistory, historyWords, loadHistory, type HistoryCarried } from './local-history-carry'
@@ -20,12 +18,19 @@ import { containerName } from './local-supervisor'
  * `realActions` or a `decision`) is rolled back afterwards instead of growing
  * the data on every `local check`.
  *
- * The baseline is keyed by the applied build: a digest of what `local dev`
- * recorded as applied (`applied-hashes.json`). It is taken again only when
- * that changed. A copy of the hash and build records is kept with it, so a
- * restore puts the CLI's record of what is applied back with the database:
- * anything applied after the baseline counts as not applied, and the next
- * `local dev` applies it again.
+ * Every save takes a new copy: the baseline is the database just before what
+ * is to be rolled back (`local check` saves it after its apply, right before
+ * its tests), so a restore takes away only what was written since. A copy kept
+ * from an earlier save would also take away what was written between the two,
+ * such as a person's sign-up or an App's records. A copy of the hash and build
+ * records is kept with it, so a restore puts the CLI's record of what is
+ * applied back with the database: anything applied after the baseline counts
+ * as not applied, and the next `local dev` applies it again.
+ *
+ * A check's baseline is marked from its save until its restore, so a check
+ * cut off in between (Ctrl+C, an agent's time limit, a crash), which left
+ * its tests' writes, is put right by the next check before it applies
+ * (`restoreCutOffCheck`).
  *
  * Only the platform database is copied. The managed datasets' catalog
  * database, object storage and local traces are left as they are.
@@ -52,6 +57,8 @@ import { containerName } from './local-supervisor'
  */
 
 export const BASELINE_DB = `${POSTGRES_DB}_baseline`
+/** What took a baseline: `local check`, `local snapshot save`, `local data load`, or an Agent conversation with rollback (MCP `agent_chat`). */
+export type BaselineSaver = 'check' | 'snapshot' | 'data' | 'conversation'
 /** The database psql connects to while it copies, drops and creates the platform's. */
 const MAINTENANCE_DB = 'postgres'
 
@@ -60,8 +67,6 @@ export interface BaselineRecord {
   organizationId: string
   database: string
   baseline: string
-  /** The applied build the baseline is of (`buildHash`). */
-  buildHash: string
   savedAt: string
   saveMs: number
   /** `applied-hashes.json` and `build.json` as they were when the baseline was taken; null when absent. */
@@ -74,6 +79,10 @@ export interface BaselineRecord {
    * Absent on a baseline taken before it was kept.
    */
   apps?: Record<string, string | null>
+  /** Absent on a baseline an older CLI took. */
+  savedBy?: BaselineSaver
+  /** A `local check` took it and has not restored it yet: still running, or cut off before its rollback. */
+  checkInProgress?: boolean
   restoredAt?: string
   restoreMs?: number
 }
@@ -102,8 +111,6 @@ export interface SnapshotOutcome {
   /** What happened, in a line. */
   note: string
   ms: number
-  /** save: false when the stored baseline is already of this build. */
-  took?: boolean
   /** restore: items applied after the baseline, now counted as not applied (Custom Apps deployed after it included). */
   reapply?: number
   /** restore: the Custom Apps deployed after the baseline, which the restored database does not have. */
@@ -136,26 +143,11 @@ function readText(path: string): string | null {
   }
 }
 
-/**
- * What is applied to this runtime, as one digest: the hash record, in a stable
- * order, and each Custom App's deployment. An App deployed since the baseline
- * changes it, so `local check` takes the baseline again rather than rolling the
- * App back out of the runtime after its tests.
- */
-export function buildHash(project: LocalProject, organizationId: string): string {
-  const entries = [...loadHashes(project, organizationId)].sort(([a], [b]) => a.localeCompare(b))
-  const apps = Object.entries(appDeployments(project.root)).filter(([, d]) => d).sort(([a], [b]) => a.localeCompare(b))
-  const hash = createHash('sha256').update(organizationId).update('\0').update(JSON.stringify(entries))
-  // Only when there is one, so a project without Apps keeps the digest its baseline was taken under.
-  if (apps.length) hash.update('\0apps\0').update(JSON.stringify(apps))
-  return hash.digest('hex')
-}
-
 /** The stored baseline's record, for this organization (after a reset the runtime is another one). */
 export function readBaseline(project: LocalProject, organizationId: string): BaselineRecord | null {
   try {
     const saved = JSON.parse(readFileSync(recordPath(project), 'utf8')) as Partial<BaselineRecord>
-    return saved.version === 1 && saved.organizationId === organizationId && typeof saved.buildHash === 'string' ? (saved as BaselineRecord) : null
+    return saved.version === 1 && saved.organizationId === organizationId ? (saved as BaselineRecord) : null
   } catch {
     return null
   }
@@ -225,24 +217,15 @@ function withLock<T>(project: LocalProject, run: () => Promise<T>): Promise<T> {
   return run().finally(() => rmSync(lockPath(project), { force: true }))
 }
 
-/**
- * Take the baseline of the database as it is now, unless the stored one is of
- * this build already (`force` takes it regardless).
- */
-export async function saveBaseline(project: LocalProject, organizationId: string, deps: SnapshotDeps = {}, force = false): Promise<SnapshotOutcome> {
+/** Take the baseline of the database as it is now, replacing the one before. */
+export async function saveBaseline(project: LocalProject, organizationId: string, deps: SnapshotDeps = {}, by?: BaselineSaver): Promise<SnapshotOutcome> {
   const exec = deps.exec ?? execInContainer
   const now = deps.now ?? Date.now
   const psql = psqlFor(project, exec)
-  const hash = buildHash(project, organizationId)
-  const stored = readBaseline(project, organizationId)
   const started = now()
-  if (!force && stored?.buildHash === hash && psql(exists(BASELINE_DB))) {
-    return { ok: true, took: false, ms: 0, note: `the stored baseline is of this build (taken ${stored.savedAt})` }
-  }
   return withLock(project, async () => {
-    // The copy before last is dropped first: a template is only ever this one build.
     if (!psql(`DROP DATABASE IF EXISTS ${BASELINE_DB}`)) {
-      return { ok: false, took: false, ms: now() - started, note: `couldn’t drop the previous baseline (${BASELINE_DB}); see \`frontera local logs postgres\`` }
+      return { ok: false, ms: now() - started, note: `couldn’t drop the previous baseline (${BASELINE_DB}); see \`frontera local logs postgres\`` }
     }
     psql(refuse(POSTGRES_DB, false))
     let copied = false
@@ -252,7 +235,7 @@ export async function saveBaseline(project: LocalProject, organizationId: string
       psql(refuse(POSTGRES_DB, true))
     }
     const ms = now() - started
-    if (!copied) return { ok: false, took: false, ms, note: `couldn’t copy the database to ${BASELINE_DB}: something kept a connection open; see \`frontera local logs postgres\`` }
+    if (!copied) return { ok: false, ms, note: `couldn’t copy the database to ${BASELINE_DB}: something kept a connection open; see \`frontera local logs postgres\`` }
     // Nothing connects to the baseline: it is only ever a template.
     psql(refuse(BASELINE_DB, false))
     await settle(deps)
@@ -262,15 +245,16 @@ export async function saveBaseline(project: LocalProject, organizationId: string
       organizationId,
       database: POSTGRES_DB,
       baseline: BASELINE_DB,
-      buildHash: hash,
       savedAt: new Date(now()).toISOString(),
       saveMs: ms,
       applied: readText(hashesFile(project)),
       build: readText(buildFile(project)),
       apps: appDeployments(project.root),
+      ...(by ? { savedBy: by } : {}),
+      ...(by === 'check' ? { checkInProgress: true } : {}),
     })
     const late = answering ? '' : '; the service isn’t answering since (see `frontera local logs service`)'
-    return { ok: true, took: true, ms, note: `took a baseline of the applied database (${ms} ms)${late}` }
+    return { ok: true, ms, note: `took a baseline of the database as it is now (${ms} ms)${late}` }
   })
 }
 
@@ -352,17 +336,49 @@ export async function restoreBaseline(project: LocalProject, organizationId: str
     const answering = deps.serviceAnswers ? await deps.serviceAnswers() : true
     const ms = now() - started
     // Written last: a watching `local dev` reads it to take the record above.
-    writeBaseline(project, { ...stored, restoredAt, restoreMs: ms })
+    writeBaseline(project, { ...stored, checkInProgress: undefined, restoredAt, restoreMs: ms })
     const kept = secretsWords(secrets)
     const ran = historyWords(history)
     const lostApps = appsLostWords(appsLost)
     const tail = `${reapply ? `; ${reapply} item${reapply === 1 ? '' : 's'} applied after the baseline will apply again on the next \`frontera local dev\`` : ''}${lostApps ? `; ${lostApps}` : ''}${kept ? `; ${kept}` : ''}${ran ? `; ${ran}` : ''}`
     const withSecrets = { ...(secrets ? { secrets } : {}), ...(history ? { history } : {}) }
     const counted = { reapply: reapply + appsLost.length, ...(appsLost.length ? { appsLost } : {}) }
-    if (!answering) return { ok: false, ms, ...counted, ...withSecrets, note: `restored the database (${ms} ms), but the service isn’t answering since: see \`frontera local logs service\`${tail}` }
-    return { ok: true, ms, ...counted, ...withSecrets, note: `restored the database as applied (${ms} ms)${tail}` }
+    const back = `restored the database to the baseline of ${stored.savedAt} (${ms} ms), so anything written since then is gone`
+    if (!answering) return { ok: false, ms, ...counted, ...withSecrets, note: `${back}, but the service isn’t answering since: see \`frontera local logs service\`${tail}` }
+    return { ok: true, ms, ...counted, ...withSecrets, note: `${back}${tail}` }
   })
 }
 
+/** How long after its save a cut-off check's baseline is put back by the next check: later, what was written since is more likely the person's own than a test's. */
+const CUT_OFF_RESTORE_MS = 60 * 60_000
+
+/**
+ * The baseline a `local check` cut off before its rollback took, put back:
+ * its tests' writes, and anything written since, are gone. When it was taken
+ * more than an hour ago, the data is left as it is instead and the mark
+ * cleared (`left`: when it was taken), so the next check goes on with a new
+ * baseline. Null when the last check finished (or the baseline was saved
+ * again since). The runtime lock keeps a second check from running, so a
+ * marked baseline found by a check is never a running check's.
+ */
+export async function restoreCutOffCheck(project: LocalProject, organizationId: string, deps: SnapshotDeps = {}): Promise<(SnapshotOutcome & { left?: string }) | null> {
+  const stored = readBaseline(project, organizationId)
+  if (!stored?.checkInProgress) return null
+  if ((deps.now ?? Date.now)() - Date.parse(stored.savedAt) <= CUT_OFF_RESTORE_MS) return restoreBaseline(project, organizationId, deps)
+  writeBaseline(project, { ...stored, checkInProgress: undefined })
+  return {
+    ok: true,
+    ms: 0,
+    left: stored.savedAt,
+    note: `the last \`frontera local check\` was cut off at ${stored.savedAt}, more than an hour ago, before it rolled back its tests’ writes. They are still in the data: rolling back now would also take away everything written since. \`frontera local snapshot restore\` puts that baseline back by hand until the next save of one, which a check makes before its tests`,
+  }
+}
+
+/** A check whose tests did not run after its save: nothing of theirs for a later check to put back. */
+export function endCheckBaseline(project: LocalProject, organizationId: string): void {
+  const stored = readBaseline(project, organizationId)
+  if (stored?.checkInProgress) writeBaseline(project, { ...stored, checkInProgress: undefined })
+}
+
 /** The record file's path relative to the project, which `local dev` watches for a restore. */
 export const BASELINE_RECORD = join('.frontera', 'local', 'db-baseline.json')

package/src/local/local-dev-references.ts

@@ -735,29 +735,6 @@ export function pointMediaTypesAt(project: LocalProject, blueprint: ResolvedBlue
   }
 }
 
-/**
- * The properties each object type lets a governed Action write
- * (`backing.editable`), for the types those Actions act on. `blueprint apply`
- * leaves backings to `bind`, so `local dev` declares them itself
- * (`blueprint editable`) before an Action's write path is built.
- */
-export function editableSets(dir: string, subjects: ReadonlySet<string> | null): Map<string, string[]> {
-  const out = new Map<string, string[]>()
-  const at = join(dir, 'object-types')
-  if (!existsSync(at)) return out
-  for (const name of readdirSync(at)) {
-    if (!/\.ya?ml$/.test(name) || name.startsWith('.')) continue
-    try {
-      const doc = parseYaml(readFileSync(join(at, name), 'utf8')) as { apiName?: unknown; backing?: { editable?: unknown } } | null
-      const editable = doc?.backing?.editable
-      if (typeof doc?.apiName === 'string' && (!subjects || subjects.has(doc.apiName)) && Array.isArray(editable) && editable.length) out.set(doc.apiName, editable.map(String).sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0)))
-    } catch {
-      // A file that does not parse is refused by the apply itself.
-    }
-  }
-  return out
-}
-
 /**
  * A copy of a Blueprint folder without some governed Actions, under
  * `.frontera/local/resolved/blueprint-without`: applied with `--prune`, it

package/src/local/local-docker.ts

@@ -1,5 +1,7 @@
 import { spawn, spawnSync } from 'node:child_process'
 import { openSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 
 /**
  * The container runtime, through its CLI.
@@ -67,6 +69,80 @@ export function imagePresent(image: string): boolean {
   return docker(['image', 'inspect', image, '--format', '{{.Id}}']).ok
 }
 
+/** The registry an image comes from: its first part when that names a host, else Docker Hub. */
+export function registryHost(image: string): string {
+  const first = image.split('/')[0]!
+  return image.includes('/') && /[.:]|^localhost$/.test(first) ? first : 'docker.io'
+}
+
+/** Docker Hub answers to three names, and its sign-in is kept under `https://index.docker.io/v1/`. */
+const DOCKER_HUB = new Set(['docker.io', 'index.docker.io', 'registry-1.docker.io'])
+const sameRegistry = (host: string) => (DOCKER_HUB.has(host) ? 'docker.io' : host)
+
+/**
+ * Whether Docker holds a sign-in for a registry host, read as Docker reads it:
+ * `config.json` in `$DOCKER_CONFIG` (else `~/.docker`), then the host's
+ * credential helper or the default store, asked for its `list` (addresses and
+ * user names, never a secret), else the file's own `auths`. False when none
+ * is found or it can't be read; nothing here prompts.
+ */
+export function dockerSignedIn(host: string): boolean {
+  let config: { auths?: Record<string, { auth?: string; identitytoken?: string } | null>; credHelpers?: Record<string, string>; credsStore?: string }
+  try {
+    config = JSON.parse(readFileSync(join(process.env.DOCKER_CONFIG || join(homedir(), '.docker'), 'config.json'), 'utf8'))
+  } catch {
+    return false
+  }
+  const isHost = (address: string) => sameRegistry(address.replace(/^https?:\/\//, '').split('/')[0]!) === sameRegistry(host)
+  const helper = Object.entries(config.credHelpers ?? {}).find(([address]) => isHost(address))?.[1] ?? config.credsStore
+  if (!helper) return Object.entries(config.auths ?? {}).some(([address, entry]) => isHost(address) && !!(entry?.auth || entry?.identitytoken))
+  // A name with a slash would run a program by path (`../evil` from the folder), not a helper on PATH.
+  if (!/^[A-Za-z0-9._-]+$/.test(helper)) return false
+  const listed = spawnSync(`docker-credential-${helper}`, ['list'], { input: 'unused', encoding: 'utf8', timeout: 5_000 })
+  if (listed.status !== 0) return false
+  try {
+    return Object.keys(JSON.parse(listed.stdout) as Record<string, string>).some(isHost)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Why a pull failed, decided once from its output and Docker's sign-in for
+ * the registry. `signed-out`: refused, with no sign-in Docker shows, so
+ * signing in is the fix. `no-access`: refused although Docker is signed in,
+ * so only someone who grants access can clear it. `missing`: the image or
+ * tag is not there. `other`: anything else, in the log.
+ */
+export type PullFailure = 'signed-out' | 'no-access' | 'missing' | 'other'
+
+export class PullError extends DockerError {
+  constructor(
+    readonly failure: PullFailure,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+function pullFailureMessage(failure: PullFailure, image: string, code: number | null, logFile: string): string {
+  const host = registryHost(image)
+  switch (failure) {
+    case 'signed-out':
+      return host === 'ghcr.io'
+        ? `the registry refused access to ${image}: run \`gh auth refresh -s read:packages\`, then \`gh auth token | docker login ghcr.io -u <github-user> --password-stdin\`, or run from a platform checkout without --image`
+        : `the registry refused access to ${image}: sign in with \`docker login ${host}\`, or run from a platform checkout without --image`
+    case 'no-access':
+      return host === 'ghcr.io'
+        ? `the registry refused ${image}, though Docker is signed in to ghcr.io. The GitHub account it signed in with has no read access to the organization's packages, or its sign-in no longer works. Ask an organization owner to grant that account read access, or run from a platform checkout without --image`
+        : `the registry refused ${image}, though Docker is signed in to ${host}. The account it signed in with may not pull it, or its sign-in no longer works. Ask an owner of ${host} to grant that account pull access, or run from a platform checkout without --image`
+    case 'missing':
+      return `${image} is not in the registry: check --registry and --version, or push that release there first`
+    case 'other':
+      return `docker pull ${image} failed (exit ${code}); see ${logFile}`
+  }
+}
+
 /** Pull an image, writing progress to a log file instead of the terminal. */
 export function pullImage(image: string, logFile: string): Promise<void> {
   return new Promise((resolvePromise, reject) => {
@@ -75,23 +151,21 @@ export function pullImage(image: string, logFile: string): Promise<void> {
     child.on('error', reject)
     child.on('exit', (code) => {
       if (code === 0) return resolvePromise()
-      // The private release images are the usual failure: say what grants access.
       let tail = ''
       try {
         tail = readFileSync(logFile, 'utf8').slice(-2000)
       } catch {
         // The log is a convenience; the exit code is the fact.
       }
-      const denied = /unauthorized|denied|authentication required/i.test(tail)
-      const host = image.split('/')[0]
-      const reason = denied
-        ? image.startsWith('ghcr.io/')
-          ? `the registry refused access to ${image}: run \`gh auth refresh -s read:packages\`, then \`gh auth token | docker login ghcr.io -u <github-user> --password-stdin\`, or run from a platform checkout without --image`
-          : `the registry refused access to ${image}: sign in with \`docker login ${host}\`, or run from a platform checkout without --image`
+      // The words don't tell no sign-in from a sign-in without access (ghcr.io answers `denied` to a token that no longer works); Docker's own sign-in does.
+      const failure: PullFailure = /unauthorized|denied|authentication required/i.test(tail)
+        ? dockerSignedIn(registryHost(image))
+          ? 'no-access'
+          : 'signed-out'
         : /manifest unknown|not found/i.test(tail)
-          ? `${image} is not in the registry: check --registry and --version, or push that release there first`
-          : `docker pull ${image} failed (exit ${code}); see ${logFile}`
-      reject(new DockerError(reason))
+          ? 'missing'
+          : 'other'
+      reject(new PullError(failure, pullFailureMessage(failure, image, code, logFile)))
     })
   })
 }