@runuai/host 0.9.113 → 0.9.115

package/db/migrations/0021_project_env_store_ref.sql

@@ -0,0 +1,3 @@
+-- ADR-134 slice 3 (host 0.9.115): project env values mirror to the credential
+-- store on Uai-operated hosts. Null on owned hosts and before the first mirror.
+ALTER TABLE `host_project_env` ADD `store_ref` text;

package/db/migrations/meta/_journal.json

@@ -148,6 +148,13 @@
       "when": 1788900000002,
       "tag": "0020_user_credential_store_ref",
       "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "6",
+      "when": 1788900000003,
+      "tag": "0021_project_env_store_ref",
+      "breakpoints": true
     }
   ]
 }

package/db/schema.ts

@@ -183,6 +183,8 @@ export const hostProjectEnv = sqliteTable(
     updatedAt: integer("updated_at", { mode: "number" })
       .notNull()
       .default(sql`(unixepoch() * 1000)`),
+    // ADR-134 slice 3: the credential-store parameter this row mirrors to.
+    storeRef: text("store_ref"),
   },
   (t) => ({
     pk: primaryKey({ columns: [t.projectId, t.key] }),

package/lib/codex-auth.ts

@@ -53,14 +53,15 @@
  * this targets ALL running tasks — matching task-up, which copies it into every
  * container regardless of roster.
  */
-import { existsSync, watch } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { existsSync, mkdtempSync, readFileSync, rmSync, watch, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
 
 import { isNull } from "drizzle-orm";
 
 import { getDb, schema } from "./db";
 import { dockerCli } from "./docker-exec";
+import { brokeredFilesFor } from "./token-broker";
 import {
   listRunningTaskAppContainerNames,
   taskAppContainerName,
@@ -90,6 +91,8 @@ export interface CodexDeps {
   /** DB-active task containers — may include stopped ones; docker decides. */
   activeTaskContainers?: () => string[];
   fileExists?: (path: string) => boolean;
+  /** Reads the host's auth.json for brokering (tests inject; never the real one). */
+  readFile?: (path: string) => string;
 }
 
 function ownerCodexDir(): string {
@@ -176,6 +179,32 @@ async function copyCodexInto(
   for (const item of items) {
     const src = join(dir, item);
     if (!exists(src)) continue;
+    // ADR-135: the task's copy never carries the rotating refresh token — N
+    // copies racing to refresh it revoke the whole family. cp needs a real
+    // file, so write the brokered variant to a private temp file and cp that.
+    if (item === "auth.json") {
+      let brokered: string | null = null;
+      try {
+        const raw = (deps.readFile ?? ((p: string) => readFileSync(p, "utf8")))(src);
+        const out = brokeredFilesFor(
+          { kind: "codex", authKind: "config-dir", id: "default", scope: "host" },
+          { "auth.json": raw },
+        );
+        brokered = out["auth.json"] !== raw ? out["auth.json"]! : null;
+      } catch {
+        brokered = null;
+      }
+      if (brokered !== null) {
+        const tmp = join(mkdtempSync(join(tmpdir(), "uai-codex-auth-")), "auth.json");
+        writeFileSync(tmp, brokered, { mode: 0o600 });
+        try {
+          await must(["cp", tmp, `${container}:/home/node/.codex/auth.json`], "docker cp auth.json (brokered)");
+        } finally {
+          rmSync(dirname(tmp), { recursive: true, force: true });
+        }
+        continue;
+      }
+    }
     await must(["cp", src, `${container}:/home/node/.codex/`], `docker cp ${item}`);
   }
   await must(
@@ -356,3 +385,50 @@ export function stopWatchingCodexAuth(): void {
     debounceTimer = null;
   }
 }
+
+/**
+ * ADR-135: re-push the host's default Grok sign-in (`~/.grok/auth.json`,
+ * brokered) into every running task, after the owned-host loop refreshed it.
+ * Same sweep shape as the Codex reinject; only auth.json travels.
+ */
+export async function reinjectGrokRunningTasks(deps: CodexDeps = {}): Promise<void> {
+  const exists = deps.fileExists ?? existsSync;
+  const src = join(process.env.UAI_OWNER_HOME?.trim() || homedir(), ".grok", "auth.json");
+  if (!exists(src)) return;
+  const active = (deps.activeTaskContainers ?? defaultActiveTaskContainers)();
+  if (active.length === 0) return;
+  const running = await dockerRunningNames(deps.exec ?? defaultExec);
+  if (running === null) return;
+  const exec = deps.exec ?? defaultExec;
+  let brokered: string;
+  try {
+    const raw = readFileSync(src, "utf8");
+    brokered = brokeredFilesFor(
+      { kind: "grok", authKind: "config-dir", id: "default", scope: "host" },
+      { "auth.json": raw },
+    )["auth.json"]!;
+  } catch {
+    return;
+  }
+  const dir = mkdtempSync(join(tmpdir(), "uai-grok-auth-"));
+  const tmp = join(dir, "auth.json");
+  try {
+    writeFileSync(tmp, brokered, { mode: 0o600 });
+    for (const container of active.filter((c) => running.has(c))) {
+      const steps: Array<[string[], string]> = [
+        [["exec", "-u", "root", ...runtimeAuthorityDockerExecArgs(), container, "/bin/mkdir", "-p", "/home/node/.grok"], "mkdir"],
+        [["cp", tmp, `${container}:/home/node/.grok/auth.json`], "docker cp auth.json (brokered)"],
+        [["exec", "-u", "root", ...runtimeAuthorityDockerExecArgs(), container, "/bin/chown", "-R", "node:node", "/home/node/.grok"], "chown"],
+      ];
+      for (const [args, step] of steps) {
+        const res = await exec(args);
+        if (res.status !== 0) {
+          console.error(`[grok] reinject into ${container}: ${step} failed (exit ${res.status ?? "none"})`);
+          break;
+        }
+      }
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/lib/credential-store-pickup.ts

@@ -0,0 +1,135 @@
+/**
+ * Uai-operated hosts: pick up credentials the broker Lambda refreshed
+ * (ADR-135). Every 15 minutes list the engine parameters under this host's
+ * scopes — names and versions only, no decryption — and re-import whatever
+ * moved, then re-push brokered copies of that kind into running tasks. The
+ * reactive path calls `pickupNow` right after a forced refresh.
+ *
+ * Never refreshes anything: on a Uai-operated host the Lambda is the one
+ * refresher. Owned hosts never run this (no store).
+ */
+
+import { configuredCredentialStore, credentialStorePrefix } from "./credential-store";
+import {
+  applyStoredEngineAccount,
+  engineAccountHostId,
+  parseEngineAccountParameterName,
+} from "./engine-accounts";
+import { setPickupNow } from "./token-broker-local";
+
+const PICKUP_INTERVAL_MS = 15 * 60_000;
+
+let timer: ReturnType<typeof setInterval> | null = null;
+let known: Map<string, number> | null = null;
+let inflight: Promise<PickupSummary> | null = null;
+let repushHook: ((kind: string) => Promise<void>) | null = null;
+
+export interface PickupSummary {
+  skipped: boolean;
+  listed: number;
+  changed: number;
+  applied: number;
+  errors: number;
+}
+
+function log(line: string): void {
+  console.log(`[credential-pickup] ${line}`);
+}
+
+/**
+ * One pass. The first pass records the baseline (the start-up reconcile
+ * already imported current values); later passes apply changed versions.
+ */
+export async function pickupChangedCredentials(): Promise<PickupSummary> {
+  const store = configuredCredentialStore();
+  const summary: PickupSummary = { skipped: false, listed: 0, changed: 0, applied: 0, errors: 0 };
+  if (!store) return { ...summary, skipped: true };
+  const prefix = credentialStorePrefix();
+  const hostId = engineAccountHostId();
+  const paths = [`${prefix}/orgs`, ...(hostId ? [`${prefix}/hosts/${hostId}`] : [])];
+  const current = new Map<string, number>();
+  for (const path of paths) {
+    try {
+      for (const entry of await store.listVersions(path)) {
+        if (parseEngineAccountParameterName(entry.name, prefix)) current.set(entry.name, entry.version);
+      }
+    } catch (err) {
+      summary.errors++;
+      log(`listing ${path} failed: ${err instanceof Error ? err.message : String(err)}`);
+      // An incomplete listing must not look like deletions; keep the baseline.
+      return summary;
+    }
+  }
+  summary.listed = current.size;
+  if (known === null) {
+    known = current;
+    return summary;
+  }
+  const kinds = new Set<string>();
+  for (const [name, version] of current) {
+    if (known.get(name) === version) continue;
+    summary.changed++;
+    try {
+      const value = await store.get(name);
+      if (value === null) continue;
+      const applied = applyStoredEngineAccount(name, value);
+      if (applied) {
+        summary.applied++;
+        kinds.add(applied.kind);
+      }
+    } catch (err) {
+      summary.errors++;
+      log(`applying ${name} failed: ${err instanceof Error ? err.message : String(err)}`);
+      continue;
+    }
+    known.set(name, version);
+  }
+  for (const name of [...known.keys()]) if (!current.has(name)) known.delete(name);
+  for (const kind of kinds) {
+    try {
+      await repushHook?.(kind);
+    } catch (err) {
+      log(`re-push of ${kind} copies failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  if (summary.changed > 0) {
+    log(`${summary.changed} parameter(s) changed, ${summary.applied} applied, ${summary.errors} errors`);
+  }
+  return summary;
+}
+
+async function pickupSerialized(): Promise<PickupSummary> {
+  if (inflight) return inflight;
+  inflight = pickupChangedCredentials().finally(() => {
+    inflight = null;
+  });
+  return inflight;
+}
+
+/** Uai-operated hosts only: baseline now, then poll every 15 minutes. */
+export function startCredentialStorePickup(hooks: { repush: (kind: string) => Promise<void> }): void {
+  if (timer || !configuredCredentialStore()) return;
+  repushHook = hooks.repush;
+  setPickupNow(async () => {
+    await pickupSerialized();
+  });
+  void pickupSerialized().catch((err) =>
+    log(`baseline failed: ${err instanceof Error ? err.message : String(err)}`),
+  );
+  timer = setInterval(() => {
+    void pickupSerialized().catch((err) =>
+      log(`poll failed: ${err instanceof Error ? err.message : String(err)}`),
+    );
+  }, PICKUP_INTERVAL_MS);
+  timer.unref?.();
+}
+
+/** Tests. */
+export function resetCredentialStorePickup(): void {
+  if (timer) clearInterval(timer);
+  timer = null;
+  known = null;
+  inflight = null;
+  repushHook = null;
+  setPickupNow(null);
+}

package/lib/credential-store.ts

@@ -45,6 +45,9 @@ export interface CredentialStore {
   delete(name: string): Promise<void>;
   /** Every credential under `path` (recursive), decrypted. Throws on failure. */
   list(path: string): Promise<StoredParameter[]>;
+  /** Names and versions under `path` (recursive), NO decryption — the cheap
+   *  poll a Uai-operated host runs to notice a broker refresh. */
+  listVersions(path: string): Promise<Array<{ name: string; version: number }>>;
 }
 
 export interface CliResult {
@@ -235,8 +238,41 @@ export class AwsSsmCredentialStore implements CredentialStore {
     }
     return out;
   }
+
+  async listVersions(path: string): Promise<Array<{ name: string; version: number }>> {
+    if (!isParameterName(path)) throw new Error(`invalid parameter path: ${path}`);
+    const out: Array<{ name: string; version: number }> = [];
+    let nextToken: string | undefined;
+    for (let page = 0; page < 100; page++) {
+      const result = await this.run([
+        "ssm",
+        "get-parameters-by-path",
+        "--path",
+        path,
+        "--recursive",
+        "--query",
+        "{Parameters: Parameters[].{Name: Name, Version: Version}, NextToken: NextToken}",
+        ...(nextToken ? ["--next-token", nextToken] : []),
+      ]);
+      if (result.status !== 0) throw failure("get-parameters-by-path", result);
+      const parsed = JSON.parse(result.stdout) as {
+        Parameters?: Array<{ Name?: unknown; Version?: unknown }> | null;
+        NextToken?: unknown;
+      };
+      for (const p of parsed.Parameters ?? []) {
+        if (typeof p.Name === "string" && typeof p.Version === "number") {
+          out.push({ name: p.Name, version: p.Version });
+        }
+      }
+      if (typeof parsed.NextToken === "string" && parsed.NextToken) nextToken = parsed.NextToken;
+      else break;
+    }
+    return out;
+  }
 }
 
+// (listVersions lives on the class below.)
+
 // ---------------------------------------------------------------------------
 // Write queue shared by every mirrored table (engine accounts, GitHub tokens,
 // SSH keys, MCP connections). Mirrors are async and best effort: a store

package/lib/engine-accounts.ts

@@ -31,12 +31,15 @@ import {
   chmodSync,
   existsSync,
   mkdirSync,
+  mkdtempSync,
   readdirSync,
   readFileSync,
+  renameSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { eq } from "drizzle-orm";
@@ -51,6 +54,7 @@ import {
   type CredentialStore,
 } from "./credential-store";
 import { getDb, schema } from "./db";
+import { brokeredFilesFor } from "./token-broker";
 import {
   taskContainerBackend,
   taskContainerCli,
@@ -550,11 +554,88 @@ export function resetRotationState(): void {
 // dirs at session start, since task-up.sh (bash) can't read the sealed DB.
 // ---------------------------------------------------------------------------
 
+/**
+ * ADR-135: what a task receives for a config-dir account. The host dir is
+ * copied verbatim EXCEPT that a lane-owned `auth.json` gets its rotating
+ * refresh token replaced by the broker placeholder, and the broker's own
+ * sidecar never travels. Returns a private temp dir (0700) the caller copies
+ * from and must remove; null means "copy the host dir as it is".
+ */
+export function stageBrokeredAccountDir(
+  kind: string,
+  hostDir: string,
+): { dir: string; cleanup: () => void } | null {
+  let entries: string[];
+  try {
+    entries = readdirSync(hostDir);
+  } catch {
+    return null;
+  }
+  const files: Record<string, string> = {};
+  const binaries = new Map<string, Buffer>();
+  for (const name of entries) {
+    if (name === BROKER_SIDECAR_FILE) continue;
+    const path = join(hostDir, name);
+    let content: Buffer;
+    try {
+      if (!statSync(path).isFile()) continue;
+      content = readFileSync(path);
+    } catch {
+      continue;
+    }
+    if (name === "auth.json") files[name] = content.toString("utf8");
+    else binaries.set(name, content);
+  }
+  if (!("auth.json" in files)) return null;
+  const brokered = brokeredFilesFor(
+    { kind, authKind: "config-dir", id: "staging", scope: HOST_ACCOUNT_SCOPE },
+    files,
+  );
+  if (brokered === files) return null;
+  const dir = mkdtempSync(join(tmpdir(), "uai-brokered-"));
+  try {
+    chmodSync(dir, 0o700);
+    for (const [name, content] of Object.entries(brokered)) {
+      writeFileSync(join(dir, name), content, { mode: 0o600 });
+    }
+    for (const [name, content] of binaries) {
+      writeFileSync(join(dir, name), content, { mode: 0o600 });
+    }
+  } catch (err) {
+    rmSync(dir, { recursive: true, force: true });
+    throw err;
+  }
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
 async function copyDirInto(
   hostDir: string,
   containerDir: string,
   container: string,
   environment?: Pick<TaskEnvironmentHandle, "exec" | "copy">,
+  kind?: string,
+): Promise<void> {
+  // ADR-135: never hand a task the rotating refresh token.
+  const staged = kind ? stageBrokeredAccountDir(kind, hostDir) : null;
+  if (staged) {
+    try {
+      await copyDirIntoRaw(staged.dir, containerDir, container, environment);
+    } finally {
+      staged.cleanup();
+    }
+    return;
+  }
+  await copyDirIntoRaw(hostDir, containerDir, container, environment);
+}
+
+/** The broker's per-dir metadata (docs/token-broker.md); never copied. */
+export const BROKER_SIDECAR_FILE = "uai-broker.json";
+
+async function copyDirIntoRaw(
+  hostDir: string,
+  containerDir: string,
+  container: string,
+  environment?: Pick<TaskEnvironmentHandle, "exec" | "copy">,
 ): Promise<void> {
   if (environment) {
     const run = async (argv: [string, ...string[]], step: string) => {
@@ -682,6 +763,7 @@ export async function provisionEngineAccounts(
           account.configDir.containerDir,
           container,
           environment,
+          kind,
         );
         copied += 1;
       } catch (err) {
@@ -1135,6 +1217,10 @@ export function configureEngineAccountStore(opts: { hostId: string | null }): vo
   storeHostId = opts.hostId;
 }
 
+export function engineAccountHostId(): string | null {
+  return storeHostId;
+}
+
 /** Tests: wait for every queued mirror/delete to settle. */
 export async function settleEngineAccountStoreWrites(): Promise<void> {
   await settleStoreWrites();
@@ -1197,7 +1283,7 @@ function storedAccountFromRow(row: StoreRow): StoredEngineAccount {
   }
   const files: Record<string, string> = {};
   for (const entry of readdirSync(row.configDir, { withFileTypes: true })) {
-    if (!entry.isFile()) continue;
+    if (!entry.isFile() || entry.name === BROKER_SIDECAR_FILE) continue;
     const content = readFileSync(join(row.configDir, entry.name));
     if (content.byteLength > MAX_STORED_FILE_BYTES) continue;
     files[entry.name] = content.toString("utf8");
@@ -1433,3 +1519,49 @@ export async function reconcileEngineAccountsFromStore(
   }
   return result;
 }
+
+/**
+ * ADR-135 pickup: a parameter changed in the store (the broker refreshed it,
+ * or a sibling host re-mirrored it). Update the local row's material in
+ * place — config-dir files rewritten atomically, env secret re-sealed — or
+ * import the row when this host lacks it. Returns the kind touched, or null
+ * when the value is not an engine account this host should hold.
+ */
+export function applyStoredEngineAccount(
+  name: string,
+  value: string,
+  seams: Partial<AccountSeams> = {},
+): { kind: string; id: string; imported: boolean } | null {
+  const at = parseEngineAccountParameterName(name);
+  if (!at) return null;
+  if (at.scope === HOST_ACCOUNT_SCOPE && at.hostId !== storeHostId) return null;
+  const stored = parseStoredAccount(value);
+  if (stored.id !== at.id || stored.kind !== at.kind || stored.scope !== at.scope) {
+    throw new Error("payload does not describe the account its path names");
+  }
+  const row = selectRow(stored.id);
+  if (!row) {
+    importStoredAccount(stored, name, withDefaults(seams));
+    return { kind: stored.kind, id: stored.id, imported: true };
+  }
+  if (row.authKind === "env" && stored.authKind === "env") {
+    getDb()
+      .update(schema.engineAccounts)
+      .set({ secretEnc: packSecret(JSON.stringify(stored.env ?? {})), storeRef: name })
+      .where(eq(schema.engineAccounts.id, row.id))
+      .run();
+  } else if (row.authKind === "config-dir" && stored.authKind === "config-dir" && row.configDir) {
+    mkdirSync(row.configDir, { recursive: true, mode: 0o700 });
+    for (const [basename, content] of Object.entries(stored.files ?? {})) {
+      if (basename.includes("/") || basename.includes("\\") || basename === "..") continue;
+      const file = join(row.configDir, basename);
+      const tmp = `${file}.${process.pid}.tmp`;
+      writeFileSync(tmp, content, { mode: 0o600 });
+      renameSync(tmp, file);
+    }
+    if (row.storeRef !== name) setStoreRef(row.id, name);
+  } else {
+    throw new Error("stored auth kind does not match the local row");
+  }
+  return { kind: stored.kind, id: stored.id, imported: false };
+}

package/lib/env.ts

@@ -54,6 +54,9 @@ const schema = z.object({
   // Shared with the ADR-121 machine provider (read raw there); the store
   // needs it too, so surface it here for one validated read.
   UAI_AWS_REGION: z.string().min(1).optional(),
+  // ADR-135: the broker Lambda a Uai-operated host invokes for a reactive
+  // refresh (name or ARN). Unset = scheduled refreshes only.
+  UAI_TOKEN_BROKER_FUNCTION: z.string().min(1).optional(),
   NODE_ENV: z
     .enum(["development", "production", "test"])
     .default("development"),

package/lib/host-env.ts

@@ -16,6 +16,12 @@
 
 import { and, eq } from "drizzle-orm";
 
+import {
+  credentialStorePrefix,
+  isParameterPathSegment,
+  parameterName,
+  queueStoreWrite,
+} from "./credential-store";
 import { getDb, schema } from "./db";
 import { sealAesGcm, openAesGcm } from "./secrets";
 
@@ -48,11 +54,12 @@ export function setProjectEnvVar(
       set: { valueEnc: packValue(value), updatedAt: Date.now() },
     })
     .run();
+  mirrorProjectEnvToStore(projectId, key);
 }
 
 /** Remove a project env var (idempotent). */
 export function deleteProjectEnvVar(projectId: string, key: string): void {
-  getDb()
+  const result = getDb()
     .delete(schema.hostProjectEnv)
     .where(
       and(
@@ -61,6 +68,104 @@ export function deleteProjectEnvVar(projectId: string, key: string): void {
       ),
     )
     .run();
+  if (result.changes > 0) {
+    const name = projectEnvParameterName(projectId, key);
+    if (name) queueStoreWrite(`delete project env ${projectId}/${key}`, (store) => store.delete(name));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Credential store mirror (ADR-134 slice 3): `<prefix>/projects/<projectId>/env/<KEY>`.
+// The set/delete frames carry no org, and a project id is org-bound in the
+// cloud, so the project is the owner segment. Owned hosts: no-ops.
+// ---------------------------------------------------------------------------
+
+export interface StoredProjectEnv {
+  v: 1;
+  kind: "project-env";
+  projectId: string;
+  key: string;
+  value: string;
+  updatedAt: number;
+}
+
+/** Null when the project id or key cannot be a parameter path segment (a
+ *  key with a character SSM refuses is kept local and logged once). */
+export function projectEnvParameterName(projectId: string, key: string): string | null {
+  if (!isParameterPathSegment(projectId) || !isParameterPathSegment(key)) return null;
+  return parameterName(credentialStorePrefix(), "projects", projectId, "env", key);
+}
+
+/** The row as it is mirrored (value decrypted). Never logged. */
+export function projectEnvStoreValue(projectId: string, key: string): StoredProjectEnv | null {
+  const row = getDb()
+    .select()
+    .from(schema.hostProjectEnv)
+    .where(and(eq(schema.hostProjectEnv.projectId, projectId), eq(schema.hostProjectEnv.key, key)))
+    .get();
+  if (!row) return null;
+  return {
+    v: 1,
+    kind: "project-env",
+    projectId,
+    key,
+    value: unpackValue(row.valueEnc),
+    updatedAt: row.updatedAt,
+  };
+}
+
+export function setProjectEnvStoreRef(projectId: string, key: string, storeRef: string): void {
+  getDb()
+    .update(schema.hostProjectEnv)
+    .set({ storeRef })
+    .where(and(eq(schema.hostProjectEnv.projectId, projectId), eq(schema.hostProjectEnv.key, key)))
+    .run();
+}
+
+export function listProjectEnvStoreRows(): Array<{ projectId: string; key: string; storeRef: string | null }> {
+  return getDb()
+    .select({
+      projectId: schema.hostProjectEnv.projectId,
+      key: schema.hostProjectEnv.key,
+      storeRef: schema.hostProjectEnv.storeRef,
+    })
+    .from(schema.hostProjectEnv)
+    .all();
+}
+
+export function mirrorProjectEnvToStore(projectId: string, key: string): void {
+  const name = projectEnvParameterName(projectId, key);
+  if (!name) return;
+  queueStoreWrite(`mirror project env ${projectId}/${key}`, async (store) => {
+    const value = projectEnvStoreValue(projectId, key);
+    if (!value) return;
+    await store.put(name, JSON.stringify(value));
+    setProjectEnvStoreRef(projectId, key, name);
+  });
+}
+
+/** Reconcile import: a value this host lacks. Existing rows win. */
+export function importProjectEnvFromStore(value: StoredProjectEnv, storeRef: string): boolean {
+  const result = getDb()
+    .insert(schema.hostProjectEnv)
+    .values({
+      projectId: value.projectId,
+      key: value.key,
+      valueEnc: packValue(value.value),
+      updatedAt: value.updatedAt,
+      storeRef,
+    })
+    .onConflictDoNothing({ target: [schema.hostProjectEnv.projectId, schema.hostProjectEnv.key] })
+    .run();
+  return result.changes > 0;
+}
+
+/** Reconcile: the row's parameter vanished elsewhere; drop the row only. */
+export function deleteProjectEnvLocal(projectId: string, key: string): void {
+  getDb()
+    .delete(schema.hostProjectEnv)
+    .where(and(eq(schema.hostProjectEnv.projectId, projectId), eq(schema.hostProjectEnv.key, key)))
+    .run();
 }
 
 /** Sorted list of a project's env var KEY NAMES (never the values). */