@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/local/local-secret-carry.ts

@@ -0,0 +1,107 @@
+import { randomBytes } from 'node:crypto'
+
+import { POSTGRES_DB, POSTGRES_USER } from './local-env'
+
+/**
+ * The workspace secrets carried across a database restore.
+ *
+ * A restore (`frontera local snapshot restore`, `local check`'s rollback)
+ * throws away what was written since the baseline: test data. Workspace
+ * secrets are configuration, set by the person (`frontera secret set`), not
+ * by a test, so a restore keeps them as they are now unless asked to put the
+ * baseline's back (`--exact`).
+ *
+ * The rows are copied as stored, never decrypted: a value is `enc:v2`
+ * ciphertext under its workspace's data key version, and that key is a
+ * wrapped row in `workspace_deks` that only the service can unwrap. So the
+ * key versions the restored database lacks come with the secrets, and the
+ * value decrypts there exactly as before. A value under a key version the
+ * restored database holds as a different key would not decrypt: it is left
+ * as the baseline holds it and named, to be set again. Values never leave
+ * the database container as plain text, and nothing here is written to disk.
+ */
+
+export type QueryFn = (container: string, cmd: string[], input?: string) => { ok: boolean; out: string }
+
+/** What the current database holds, read before it is dropped: its workspaces, their secrets and data keys, as JSON. */
+export interface SecretsHeld {
+  json: string
+  count: number
+}
+
+export interface SecretsCarried {
+  ok: boolean
+  /** How many secrets are as they were before the restore. */
+  kept: number
+  /** Secrets whose value would not decrypt in the restored database, by name: set them again. */
+  notKept: string[]
+  /** Why nothing was carried, when it failed. */
+  problem?: string
+}
+
+const psqlArgs = (extra: string[]) => ['psql', '-U', POSTGRES_USER, '-d', POSTGRES_DB, '-v', 'ON_ERROR_STOP=1', '-q', '-At', ...extra]
+
+export const READ_SECRETS_SQL = `SELECT json_build_object(
+  'workspaces', coalesce((SELECT json_agg(id) FROM workspaces), '[]'::json),
+  'secrets', coalesce((SELECT json_agg(s) FROM workspace_secrets s), '[]'::json),
+  'deks', coalesce((SELECT json_agg(d) FROM workspace_deks d), '[]'::json))`
+
+/** The secrets and data keys as the database holds them now, or why they could not be read. */
+export function readSecrets(query: QueryFn, container: string): SecretsHeld | { problem: string } {
+  const res = query(container, psqlArgs(['-c', READ_SECRETS_SQL.replace(/\s+/g, ' ')]))
+  if (!res.ok) return { problem: 'the current secrets could not be read' }
+  try {
+    const parsed = JSON.parse(res.out) as { secrets?: unknown[] }
+    return { json: res.out, count: Array.isArray(parsed.secrets) ? parsed.secrets.length : 0 }
+  } catch {
+    return { problem: 'the current secrets could not be read' }
+  }
+}
+
+/**
+ * The SQL that puts the held secrets into the restored database, in one
+ * transaction: the data key versions it lacks are added, each workspace's
+ * secrets replaced by the held ones (a secret deleted since the baseline
+ * stays deleted), except those under a key version it holds differently.
+ * Answers one JSON line: how many were kept, and the names that weren't.
+ */
+export function carrySql(json: string, tag = `carry_${randomBytes(6).toString('hex')}`): string {
+  if (json.includes(`$${tag}$`)) throw new Error('the held secrets contain the quoting tag')
+  const q = `$${tag}$`
+  return [
+    'BEGIN;',
+    `CREATE TEMP TABLE carry ON COMMIT DROP AS SELECT ${q}${json}${q}::json AS j;`,
+    // Only workspaces both databases have: one made after the baseline is gone with it.
+    `CREATE TEMP TABLE carry_ws ON COMMIT DROP AS SELECT (value #>> '{}')::uuid AS id FROM json_array_elements((SELECT j->'workspaces' FROM carry)) WHERE (value #>> '{}')::uuid IN (SELECT id FROM workspaces);`,
+    `CREATE TEMP TABLE carry_deks ON COMMIT DROP AS SELECT * FROM json_populate_recordset(NULL::workspace_deks, (SELECT j->'deks' FROM carry)) WHERE workspace_id IN (SELECT id FROM carry_ws);`,
+    `CREATE TEMP TABLE carry_secrets ON COMMIT DROP AS SELECT * FROM json_populate_recordset(NULL::workspace_secrets, (SELECT j->'secrets' FROM carry)) WHERE workspace_id IN (SELECT id FROM carry_ws);`,
+    // A key version the restored database holds as another key: a value under it would not decrypt there.
+    `CREATE TEMP TABLE carry_skip ON COMMIT DROP AS SELECT s.workspace_id, s.name FROM carry_secrets s JOIN carry_deks c ON c.workspace_id = s.workspace_id AND s.encrypted_value LIKE 'enc:v2:dek.' || c.version || ':%' JOIN workspace_deks d ON d.workspace_id = c.workspace_id AND d.version = c.version AND d.wrapped_dek <> c.wrapped_dek;`,
+    `INSERT INTO workspace_deks SELECT c.* FROM carry_deks c WHERE NOT EXISTS (SELECT 1 FROM workspace_deks d WHERE d.workspace_id = c.workspace_id AND d.version = c.version) ON CONFLICT DO NOTHING;`,
+    `DELETE FROM workspace_secrets t WHERE t.workspace_id IN (SELECT id FROM carry_ws) AND NOT EXISTS (SELECT 1 FROM carry_skip k WHERE k.workspace_id = t.workspace_id AND k.name = t.name);`,
+    `INSERT INTO workspace_secrets SELECT s.* FROM carry_secrets s WHERE NOT EXISTS (SELECT 1 FROM carry_skip k WHERE k.workspace_id = s.workspace_id AND k.name = s.name) ON CONFLICT DO NOTHING;`,
+    `SELECT json_build_object('kept', (SELECT count(*) FROM workspace_secrets t JOIN carry_secrets s ON s.id = t.id AND s.encrypted_value = t.encrypted_value), 'notKept', coalesce((SELECT json_agg(name ORDER BY name) FROM carry_skip), '[]'::json));`,
+    'COMMIT;',
+    '',
+  ].join('\n')
+}
+
+/** Put the held secrets into the restored database (`carrySql`), and say what became of them. */
+export function carrySecrets(query: QueryFn, container: string, held: SecretsHeld): SecretsCarried {
+  let sql: string
+  try {
+    sql = carrySql(held.json)
+  } catch (err) {
+    return { ok: false, kept: 0, notKept: [], problem: (err as Error).message }
+  }
+  const res = query(container, psqlArgs(['-f', '-']), sql)
+  if (!res.ok) return { ok: false, kept: 0, notKept: [], problem: 'the restored database refused them' }
+  try {
+    const line = res.out.split('\n').map((l) => l.trim()).filter(Boolean).at(-1) ?? '{}'
+    const said = JSON.parse(line) as { kept?: number; notKept?: string[] }
+    return { ok: true, kept: Number(said.kept ?? 0), notKept: Array.isArray(said.notKept) ? said.notKept.filter((n) => typeof n === 'string') : [] }
+  } catch {
+    // Committed, but its answer could not be read: what the runtime lists says the rest.
+    return { ok: true, kept: held.count, notKept: [] }
+  }
+}

package/src/local/local-secrets.ts

@@ -55,7 +55,7 @@ export function pluginSecretName(plugin: string, field: string): string {
 
 /** The `secret:NAME` grants a Function's source names. */
 export function functionSecretNames(source: string): string[] {
-  return [...new Set([...source.matchAll(/['"`]secret:([A-Z][A-Z0-9_]*)['"`]/g)].map((m) => m[1]!))].sort()
+  return [...new Set([...source.matchAll(/['"`]secret:([A-Z][A-Z0-9_]*)['"`]/g)].map((m) => m[1]!))].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
 }
 
 /** The secrets a workflow's HTTP steps and webhook trigger name in their `auth`, at any depth. */
@@ -70,7 +70,7 @@ export function workflowSecretNames(doc: unknown): string[] {
     }
   }
   visit(doc)
-  return [...out].sort()
+  return [...out].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
 }
 
 /** A Plugin setting declared empty in its file: a header or a config key, and the local secret that fills it. */
@@ -115,27 +115,57 @@ export function needsValueLine(name: string, who: string): string {
 /** The build's lines for the secrets `names` that the local runtime has no value for. */
 export async function missingSecretLines(names: string[], who: string, serviceUrl: string, creds: LocalCredentials): Promise<string[]> {
   if (!names.length) return []
-  const have = await localSecretNames(serviceUrl, creds)
-  if (!have) return []
-  return names.filter((n) => !have.has(n)).map((n) => needsValueLine(n, who))
+  const presence = await localSecretPresence(serviceUrl, creds)
+  if (!presence) return []
+  return names.filter((n) => !hasSecretValue(presence, n)).map((n) => needsValueLine(n, who))
 }
 
-/** The secret names the local runtime holds (never their values); `null` when it could not say. */
-export async function localSecretNames(serviceUrl: string, creds: LocalCredentials): Promise<Set<string> | null> {
+/**
+ * What the local runtime holds of its secrets, never their values: each name
+ * the secrets list route lists, and those of them it says have no value
+ * (`hasValue: false` on a row; a runtime that does not say counts a listed
+ * secret as having one).
+ */
+export interface SecretPresence {
+  names: Set<string>
+  withoutValue: Set<string>
+}
+
+/** Whether the runtime has a value for `name`: listed, and not said to be without one. */
+export function hasSecretValue(presence: SecretPresence, name: string): boolean {
+  return presence.names.has(name) && !presence.withoutValue.has(name)
+}
+
+/** The secrets list route's answer, read as `SecretPresence`; `null` when it could not say. */
+export async function localSecretPresence(serviceUrl: string, creds: LocalCredentials, deps: { fetch?: (url: string | URL, init?: RequestInit) => Promise<Response> } = {}): Promise<SecretPresence | null> {
   if (!creds.workspaceKey || !creds.workspaceId) return null
   try {
-    const res = await fetch(new URL(`/v1/workspaces/${encodeURIComponent(creds.workspaceId)}/secrets`, serviceUrl), {
+    const res = await (deps.fetch ?? fetch)(new URL(`/v1/workspaces/${encodeURIComponent(creds.workspaceId)}/secrets`, serviceUrl), {
       headers: { authorization: `Bearer ${creds.workspaceKey}` },
+      signal: AbortSignal.timeout(5000),
     })
     if (!res.ok) return null
-    const body = (await res.json()) as { data?: Array<{ name?: string }> } | Array<{ name?: string }>
+    const body = (await res.json()) as { data?: Array<{ name?: string; hasValue?: unknown }> } | Array<{ name?: string; hasValue?: unknown }>
     const rows = Array.isArray(body) ? body : (body.data ?? [])
-    return new Set(rows.flatMap((r) => (typeof r.name === 'string' ? [r.name] : [])))
+    const names = new Set<string>()
+    const withoutValue = new Set<string>()
+    for (const r of rows) {
+      if (typeof r.name !== 'string') continue
+      names.add(r.name)
+      if (r.hasValue === false) withoutValue.add(r.name)
+    }
+    return { names, withoutValue }
   } catch {
     return null
   }
 }
 
+/** The secret names the local runtime holds a value for (never the values); `null` when it could not say. */
+export async function localSecretNames(serviceUrl: string, creds: LocalCredentials): Promise<Set<string> | null> {
+  const presence = await localSecretPresence(serviceUrl, creds)
+  return presence ? new Set([...presence.names].filter((n) => !presence.withoutValue.has(n))) : null
+}
+
 /**
  * A Plugin file as a push sends it: every header, key-like setting and
  * environment value empty, as the pull writes them. The platform keeps its
@@ -232,7 +262,7 @@ function sameBesideSecrets(text: string, base: string): boolean {
 
 function sortKeys(v: unknown): unknown {
   if (Array.isArray(v)) return v.map(sortKeys)
-  if (v && typeof v === 'object') return Object.fromEntries(Object.keys(v as Record<string, unknown>).sort().map((k) => [k, sortKeys((v as Record<string, unknown>)[k])]))
+  if (v && typeof v === 'object') return Object.fromEntries(Object.keys(v as Record<string, unknown>).sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0)).map((k) => [k, sortKeys((v as Record<string, unknown>)[k])]))
   return v
 }
 

package/src/local/local-seed.ts

@@ -1,6 +1,6 @@
 import { appendFileSync } from 'node:fs'
 
-import { findProvider, getKey, keylessEmbeddings, LOCAL_PROVIDERS } from './local-keys'
+import { findProvider, getKey, LOCAL_PROVIDERS, localEmbeddingsReachable } from './local-keys'
 import type { LocalCredentials } from './local-state'
 
 /**
@@ -174,11 +174,35 @@ const EMBEDDING: Array<{ provider: string; model: string }> = [
   { provider: 'openrouter', model: 'openai/text-embedding-3-small' },
 ]
 
+/**
+ * The runtime's embedding choice, when it has one its credentials can run
+ * (`/v1/config/embedding` lists only credentialed providers): one chosen
+ * before, by `local dev` to match the workspace or by its owner, is kept.
+ */
+async function credentialedEmbedding(serviceUrl: string, token: string, orgId: string): Promise<{ provider: string; model: string } | null> {
+  try {
+    const res = await call<{ data?: EmbeddingView } & EmbeddingView>(serviceUrl, '/v1/config/embedding', { token, orgId })
+    if (res.status >= 300) return null
+    const view = res.body?.data ?? res.body
+    const { provider, model } = view ?? {}
+    if (typeof provider !== 'string' || !provider || typeof model !== 'string' || !model) return null
+    return Array.isArray(view?.providers) && view.providers.some((p) => p?.id === provider) ? { provider, model } : null
+  } catch {
+    return null
+  }
+}
+
+interface EmbeddingView {
+  provider?: string | null
+  model?: string | null
+  providers?: Array<{ id?: string }>
+}
+
 /**
  * Copy the FDE's stored keys into the local organization's credentials, and
- * pick an embedding model when one is possible. Returns what was applied, for
- * the status line; failures are logged, never fatal — a runtime without a model
- * key still starts, and says so.
+ * pick an embedding model when one is possible and none that runs is chosen
+ * yet. Returns what was applied, for the status line; failures are logged,
+ * never fatal — a runtime without a model key still starts, and says so.
  */
 export async function applyModelKeys(args: { serviceUrl: string; password: string; organizationId: string; logFile: string }): Promise<string[]> {
   const applied: string[] = []
@@ -202,33 +226,56 @@ export async function applyModelKeys(args: { serviceUrl: string; password: strin
     if (res.status >= 200 && res.status < 300) applied.push(p.id)
     else log(args.logFile, `storing the ${findProvider(p.id)?.label} key answered ${res.status}: ${JSON.stringify(res.body).slice(0, 200)}`)
   }
-  let embedding = EMBEDDING.find((e) => applied.includes(e.provider))
-  if (!embedding && keylessEmbeddings()) {
-    // A placeholder OpenAI credential: the service's OpenAI client is pointed
-    // at the local embeddings (see serviceEnv), which embed without a key.
-    const res = await call(args.serviceUrl, '/v1/admin/provider-credentials/openai', {
-      method: 'PUT',
-      token,
-      orgId: args.organizationId,
-      body: { fields: { apiKey: 'local-embeddings' } },
-    })
-    if (res.status >= 200 && res.status < 300) {
-      embedding = EMBEDDING[0]
-      applied.push('local-embeddings')
-    } else log(args.logFile, `storing the local embeddings credential answered ${res.status}: ${JSON.stringify(res.body).slice(0, 200)}`)
+  // A choice that runs with this runtime's keys stays: the workspace's model (`mirrorOrgSettings`) or the owner's.
+  // The local embeddings' stand-in OpenAI credential is not a key: a real key's model replaces it when the provider takes it.
+  const kept = await credentialedEmbedding(args.serviceUrl, token, args.organizationId)
+  const standIn = !!kept && isLocalEmbeddings(kept)
+  if (kept && !standIn) {
+    log(args.logFile, `kept the embedding model ${kept.provider} / ${kept.model}`)
+    return applied
   }
-  if (embedding) {
-    const res = await call(args.serviceUrl, '/v1/config/embedding', {
-      method: 'PUT',
-      token,
-      orgId: args.organizationId,
-      body: embedding,
-    })
-    if (res.status >= 300) log(args.logFile, `setting the embedding model answered ${res.status}: ${JSON.stringify(res.body).slice(0, 200)}`)
+  const setEmbedding = async (embedding: { provider: string; model: string }) => {
+    const res = await call(args.serviceUrl, '/v1/config/embedding', { method: 'PUT', token, orgId: args.organizationId, body: embedding })
+    if (res.status < 300) return true
+    log(args.logFile, `setting the embedding model ${embedding.provider} / ${embedding.model} answered ${res.status}: ${JSON.stringify(res.body).slice(0, 300)}`)
+    return false
+  }
+  for (const embedding of EMBEDDING.filter((e) => applied.includes(e.provider))) {
+    if (await setEmbedding(embedding)) return applied
+  }
+  if (standIn) {
+    applied.push('local-embeddings')
+    return applied
+  }
+  // No key, or the provider refused the one stored (the line above says its answer): the keyless local
+  // embeddings, so knowledge bases still ingest and search here. They need the service's OpenAI client,
+  // which points at them while this computer has no OpenAI key (see serviceEnv).
+  if (!localEmbeddingsReachable()) return applied
+  const res = await call(args.serviceUrl, '/v1/admin/provider-credentials/openai', {
+    method: 'PUT',
+    token,
+    orgId: args.organizationId,
+    body: { fields: { apiKey: LOCAL_EMBEDDINGS_CREDENTIAL } },
+  })
+  if (res.status >= 300) {
+    log(args.logFile, `storing the local embeddings credential answered ${res.status}: ${JSON.stringify(res.body).slice(0, 200)}`)
+    return applied
+  }
+  if (await setEmbedding(EMBEDDING[0]!)) {
+    applied.push('local-embeddings')
+    if (applied.some((p) => p === 'openrouter')) log(args.logFile, 'embedding with the keyless local embeddings: the stored key’s embedding model was refused (see the line above)')
   }
   return applied
 }
 
+/** The placeholder OpenAI credential that sends the service's OpenAI client to the keyless local embeddings. */
+const LOCAL_EMBEDDINGS_CREDENTIAL = 'local-embeddings'
+
+/** Whether a choice is the keyless local embeddings: OpenAI's model while this computer holds no OpenAI key. */
+export function isLocalEmbeddings(embedding: { provider: string | null; model: string | null }): boolean {
+  return embedding.provider === 'openai' && localEmbeddingsReachable()
+}
+
 /**
  * Runtimes started before the echo model was removed still list it: the
  * `local` custom provider, its `local-model` catalog entry, and that model as
@@ -273,6 +320,35 @@ export const PROVIDER_MODELS: Record<string, Array<{ slug: string; modelId: stri
     { slug: 'gemini-3-8-flash', modelId: 'google/gemini-3.8-flash', name: 'Gemini 3.8 Flash' },
     { slug: 'gpt-5-6-terra', modelId: 'openai/gpt-5.6-terra', name: 'GPT-5.6 Terra' },
   ],
+  // Direct from Anthropic, beside OpenRouter's: a stored Anthropic key runs Claude without OpenRouter's
+  // credit. Their slugs name the provider, so they never take the OpenRouter models' slugs.
+  anthropic: [
+    { slug: 'anthropic-claude-haiku-5-5', modelId: 'claude-haiku-5-5', name: 'Claude Haiku 5.5 (Anthropic)' },
+    { slug: 'anthropic-claude-sonnet-5-5', modelId: 'claude-sonnet-5-5', name: 'Claude Sonnet 5.5 (Anthropic)' },
+  ],
+}
+
+/** A model the local catalog offers directly from a provider (not through OpenRouter), and that provider. */
+export interface DirectModel {
+  slug: string
+  name: string
+  provider: string
+  providerLabel: string
+}
+
+/**
+ * The first model offered directly by a provider whose key the runtime holds
+ * (`providers`: the ids the runtime applied keys for, never a key), other than
+ * the provider that refused (`refusedBy`); null when there is none. What a
+ * credit refusal suggests switching to.
+ */
+export function directModelFor(providers: readonly string[] | undefined, refusedBy?: string | null): DirectModel | null {
+  for (const [provider, models] of Object.entries(PROVIDER_MODELS)) {
+    if (provider === 'openrouter' || provider === refusedBy || !providers?.includes(provider) || !models.length) continue
+    const m = models[0]!
+    return { slug: m.slug, name: m.name.replace(/\s*\([^)]*\)$/, ''), provider, providerLabel: findProvider(provider)?.label ?? provider }
+  }
+  return null
 }
 
 /**

package/src/local/local-stand-ins.ts

@@ -34,7 +34,7 @@ import { rows } from './local-sync-remote'
  * - **Documentation** (Frontera's documentation for Agents): its stand-in
  *   `serves: "documentation"`, answering the plugin's tools from the
  *   documentation `local start` copied for the runtime's release (the same
- *   copy `frontera local docs-mcp` serves the project's coding agents). The
+ *   copy `frontera mcp` serves the project's coding agents). The
  *   Agent's documentation tools work here.
  * - **Analytics**: the workspace's analytics tools read its analytics
  *   project, which a local runtime does not have (design §8). The pull
@@ -70,7 +70,7 @@ const DOCS_TOOLS: StandInFile['tools'] = [
 
 /** The built-in Plugins these items need that get a stand-in (connections, the Documentation plugin), by install name. */
 export function connectionsNeeded(items: Array<Pick<RemoteItem, 'portability'>>): string[] {
-  return [...new Set(items.flatMap((i) => (i.portability?.needs ?? []).flatMap((n) => (n.kind === 'connection' || n.kind === 'documentation' ? [n.name] : []))))].sort()
+  return [...new Set(items.flatMap((i) => (i.portability?.needs ?? []).flatMap((n) => (n.kind === 'connection' || n.kind === 'documentation' ? [n.name] : []))))].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
 }
 
 /** Which of those are the Documentation plugin. */
@@ -80,7 +80,7 @@ export function documentationNeeded(items: Array<Pick<RemoteItem, 'portability'>
 
 /** The workspace's analytics Plugins these items use: platform-only. */
 export function analyticsNeeded(items: Array<Pick<RemoteItem, 'portability'>>): string[] {
-  return [...new Set(items.flatMap((i) => (i.portability?.needs ?? []).flatMap((n) => (n.kind === 'analytics' ? [n.name] : []))))].sort()
+  return [...new Set(items.flatMap((i) => (i.portability?.needs ?? []).flatMap((n) => (n.kind === 'analytics' ? [n.name] : []))))].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0))
 }
 
 // ── Platform-only Plugins ────────────────────────────────────────────────────

package/src/local/local-state.ts

@@ -1,6 +1,7 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
 import { join } from 'node:path'
 
+import { ignoreInFronteraDir } from '../project-context'
 import { writeFileAtomic } from '../fs-atomic'
 import type { LocalProject } from './local-project'
 
@@ -88,8 +89,8 @@ export function ensureStateDir(project: LocalProject): void {
   } catch {
     // Best effort; a filesystem without modes still works.
   }
-  const ignore = join(project.root, '.frontera', '.gitignore')
-  if (!existsSync(ignore)) writeFileAtomic(ignore, 'local/\n', 0o644)
+  // The runtime's state, and which profile this machine bound the directory to, stay out of git.
+  ignoreInFronteraDir(project.root, ['local/'])
 }
 
 export function readState(project: LocalProject): LocalState | null {
@@ -163,3 +164,43 @@ export function readApplied(project: LocalProject): LastApplied | null {
     return null
   }
 }
+
+/**
+ * An apply under way: `local dev` writes it as it starts applying what is
+ * queued and removes it when the queue is done, so Forge and Studio say
+ * "Applying…" rather than show a half-made count as if it were the result.
+ */
+export interface ApplyingNow {
+  /** When this round of applies began. */
+  since: string
+  /** How many items were queued when it began. */
+  queued: number
+  /** The `local dev` applying them: a record whose process is gone is stale. */
+  pid: number
+  /** What started it, in words: "runtime started", "files changed: agents/desk/agent.json". */
+  trigger?: string
+}
+
+function applyingPath(project: LocalProject): string {
+  return join(project.stateDir, 'applying.json')
+}
+
+/** Say an apply is under way (`entry`), or that it is done (`null`). Never throws. */
+export function recordApplying(project: LocalProject, entry: ApplyingNow | null): void {
+  try {
+    if (entry) writeFileAtomic(applyingPath(project), `${JSON.stringify(entry)}\n`, 0o644)
+    else rmSync(applyingPath(project), { force: true })
+  } catch {
+    // A missed hint must never fail an apply.
+  }
+}
+
+/** The apply under way, or null: none, or its `local dev` is gone. */
+export function readApplying(stateDir: string): ApplyingNow | null {
+  try {
+    const entry = JSON.parse(readFileSync(join(stateDir, 'applying.json'), 'utf8')) as ApplyingNow
+    return entry && typeof entry.since === 'string' && isAlive(entry.pid) ? entry : null
+  } catch {
+    return null
+  }
+}