@runuai/host 0.1.0 → 0.2.0

package/db/migrations/0005_host_env_vars.sql

@@ -0,0 +1,5 @@
+CREATE TABLE `host_env_vars` (
+  `key` text PRIMARY KEY NOT NULL,
+  `value_enc` text NOT NULL,
+  `updated_at` integer NOT NULL DEFAULT (unixepoch() * 1000)
+);

package/db/migrations/0006_host_project_env.sql

@@ -0,0 +1,9 @@
+DROP TABLE IF EXISTS `host_env_vars`;
+--> statement-breakpoint
+CREATE TABLE `host_project_env` (
+  `project_id` text NOT NULL,
+  `key` text NOT NULL,
+  `value_enc` text NOT NULL,
+  `updated_at` integer NOT NULL DEFAULT (unixepoch() * 1000),
+  PRIMARY KEY (`project_id`, `key`)
+);

package/db/migrations/meta/_journal.json

@@ -36,6 +36,20 @@
       "when": 1779900005000,
       "tag": "0004_host_owner_name",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "6",
+      "when": 1779900006000,
+      "tag": "0005_host_env_vars",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "6",
+      "when": 1779900007000,
+      "tag": "0006_host_project_env",
+      "breakpoints": true
     }
   ]
 }

package/db/schema.ts

@@ -7,7 +7,13 @@
  */
 
 import { sql } from "drizzle-orm";
-import { blob, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import {
+  blob,
+  integer,
+  primaryKey,
+  sqliteTable,
+  text,
+} from "drizzle-orm/sqlite-core";
 
 export const hostTasks = sqliteTable("uai_host_tasks", {
   taskId: text("task_id").primaryKey(),
@@ -80,3 +86,28 @@ export const sshKeys = sqliteTable("host_ssh_keys", {
 
 export type SshKey = typeof sshKeys.$inferSelect;
 export type NewSshKey = typeof sshKeys.$inferInsert;
+
+// Per-(project, key) environment variable values, encrypted at rest with the
+// host master key (same secret-blind pattern as host_ssh_keys /
+// host_github_tokens — ADR-015). The cloud only ever sees KEY NAMES, never
+// values (values are write-only). Set by project/org members on the project
+// settings page (grouped by host); at task-up each project on the task gets ITS
+// (projectId, key) values injected under the key name. The same key name is
+// independent per project, and a project's values are independent per host.
+export const hostProjectEnv = sqliteTable(
+  "host_project_env",
+  {
+    projectId: text("project_id").notNull(),
+    key: text("key").notNull(),
+    valueEnc: text("value_enc").notNull(), // sealAesGcm output (base64 ct.nonce)
+    updatedAt: integer("updated_at", { mode: "number" })
+      .notNull()
+      .default(sql`(unixepoch() * 1000)`),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.projectId, t.key] }),
+  }),
+);
+
+export type HostProjectEnv = typeof hostProjectEnv.$inferSelect;
+export type NewHostProjectEnv = typeof hostProjectEnv.$inferInsert;

package/lib/agent.ts

@@ -27,6 +27,7 @@ import {
   removeCommandDb,
 } from "./command-db";
 import { env } from "./env";
+import { getDecryptedForProject } from "./host-env";
 import { PreviewPortRuntimesSchema } from "./preview-ports";
 import { getHostTask } from "./runtime-state";
 import { removeTaskIdentity, writeTaskIdentity } from "./ssh";
@@ -243,13 +244,29 @@ export const agent = {
     // Materialize the creator's per-user SSH key so task-up.sh clones + pushes
     // as them (ADR-029); null → task-up.sh falls back to the operator identity.
     const identityDir = writeTaskIdentity(input.task.id, input.task.ownerUserId);
+    // Per-(project, key) env var VALUES: each project on the task contributes
+    // its own decrypted values, which go straight into the child ENV (never
+    // args/logs/the compose YAML). task-up.sh already renders a `${KEY:-}`
+    // pass-through for each project's DECLARED keys, so docker interpolates the
+    // value from this child's env at up-time — mirroring CLAUDE_CODE_OAUTH_TOKEN
+    // and secret-blind end to end (ADR-015). On a key collision across projects
+    // the LEAD project (position 0) wins: iterate in DESCENDING position order
+    // so position-0's assignments are applied LAST and overwrite the rest.
+    const extraEnv: Record<string, string> = {};
+    const orderedProjects = [...input.projects].sort(
+      (a, b) => b.position - a.position,
+    );
+    for (const project of orderedProjects) {
+      Object.assign(extraEnv, getDecryptedForProject(project.id));
+    }
+    if (identityDir) extraEnv.UAI_TASK_IDENTITY_DIR = identityDir;
     try {
       return await runAgent(
         "task-up.sh",
         [input.task.id],
         TaskUpData,
         commandDbPath,
-        identityDir ? { UAI_TASK_IDENTITY_DIR: identityDir } : {},
+        extraEnv,
       );
     } finally {
       removeCommandDb(commandDbPath);

package/lib/host-env.ts

@@ -0,0 +1,106 @@
+/**
+ * Per-(project, key) environment variable store.
+ *
+ * Project/org members set KEY=VALUE pairs scoped to a (projectId, key) on this
+ * host; values are encrypted at rest with the host master key (same
+ * secret-blind pattern as host_ssh_keys / host_github_tokens — ADR-015). The
+ * cloud + UI only ever see KEY NAMES, never values (values are write-only). The
+ * same key name (e.g. DATABASE_URL) is independent per project, and a project's
+ * values are independent per host. At task-up each project on the task gets ITS
+ * (projectId, key) values injected into the task container env under the key
+ * name (see lib/agent.ts + scripts/agent/task-up.sh).
+ *
+ * `value_enc` is a single TEXT column carrying both halves of the AES-GCM
+ * sealed value as "<ct-base64>.<nonce-base64>".
+ */
+
+import { and, eq } from "drizzle-orm";
+
+import { getDb, schema } from "./db";
+import { sealAesGcm, openAesGcm } from "./secrets";
+
+/** Pack a sealed value (ct + nonce) into the single TEXT column. */
+function packValue(value: string): string {
+  const sealed = sealAesGcm(value);
+  return `${sealed.ct.toString("base64")}.${sealed.nonce.toString("base64")}`;
+}
+
+/** Reverse {@link packValue}; throws if the column is malformed. */
+function unpackValue(valueEnc: string): string {
+  const dot = valueEnc.indexOf(".");
+  if (dot === -1) throw new Error("malformed value_enc");
+  const ct = Buffer.from(valueEnc.slice(0, dot), "base64");
+  const nonce = Buffer.from(valueEnc.slice(dot + 1), "base64");
+  return openAesGcm(ct, nonce);
+}
+
+/** Set (insert or overwrite) a project env var, encrypting the value at rest. */
+export function setProjectEnvVar(
+  projectId: string,
+  key: string,
+  value: string,
+): void {
+  getDb()
+    .insert(schema.hostProjectEnv)
+    .values({ projectId, key, valueEnc: packValue(value), updatedAt: Date.now() })
+    .onConflictDoUpdate({
+      target: [schema.hostProjectEnv.projectId, schema.hostProjectEnv.key],
+      set: { valueEnc: packValue(value), updatedAt: Date.now() },
+    })
+    .run();
+}
+
+/** Remove a project env var (idempotent). */
+export function deleteProjectEnvVar(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). */
+export function listProjectEnvKeys(projectId: string): string[] {
+  return getDb()
+    .select({ key: schema.hostProjectEnv.key })
+    .from(schema.hostProjectEnv)
+    .where(eq(schema.hostProjectEnv.projectId, projectId))
+    .all()
+    .map((row) => row.key)
+    .sort();
+}
+
+/**
+ * Decrypt + return a project's env vars as KEY→VALUE. Used at task-up injection
+ * (lib/agent.ts) — the decrypted values live only on the trusted host (ADR-015)
+ * and go straight into the task container's child env, never logged. Resilient:
+ * a single value that fails to decrypt is logged + skipped rather than aborting
+ * the whole task launch.
+ */
+export function getDecryptedForProject(projectId: string): Record<string, string> {
+  const rows = getDb()
+    .select({
+      key: schema.hostProjectEnv.key,
+      valueEnc: schema.hostProjectEnv.valueEnc,
+    })
+    .from(schema.hostProjectEnv)
+    .where(eq(schema.hostProjectEnv.projectId, projectId))
+    .all();
+  const out: Record<string, string> = {};
+  for (const row of rows) {
+    try {
+      out[row.key] = unpackValue(row.valueEnc);
+    } catch (err) {
+      console.warn(
+        `[host-env] skipping ${projectId}/${row.key}: decrypt failed (${
+          err instanceof Error ? err.message : String(err)
+        })`,
+      );
+    }
+  }
+  return out;
+}

package/lib/standard-image.ts

@@ -94,9 +94,94 @@ function run(command: string, args: string[]): Promise<RunResult> {
 }
 
 /**
- * Ensure the standard image and the shared asdf data volume exist. Builds the
- * image only when `docker image inspect` fails. Best-effort: logs and returns
- * on any error so the host keeps booting.
+ * Agent CLIs that MUST exist inside the shared asdf volume. The volume mounts
+ * over /opt/asdf-data and shadows the image's baked-in shims, so a volume
+ * seeded before a CLI was added (or before a version bump) can be missing it —
+ * e.g. a stale volume with `codex` but no `claude`, which makes `claude` exit
+ * 127 in every task container. Reconciled on each host start.
+ */
+const VOLUME_AGENT_CLIS: { bin: string; pkg: string }[] = [
+  { bin: "claude", pkg: "@anthropic-ai/claude-code" },
+  { bin: "codex", pkg: "@openai/codex" },
+];
+
+/**
+ * Self-heal the shared asdf volume: ensure each agent CLI resolves inside it,
+ * installing + reshimming any that are missing. Cheap when healthy (one
+ * container that just lists absent bins); only pays the npm cost on repair.
+ * A fresh/empty volume is seeded from the image by Docker on first mount, so
+ * this is a no-op there — it only fixes pre-existing stale volumes.
+ */
+async function ensureVolumeAgentClis(): Promise<void> {
+  const bins = VOLUME_AGENT_CLIS.map((c) => c.bin).join(" ");
+  // Sentinel-prefixed output so login-shell init noise can't be misread as a
+  // missing bin.
+  const check = await run("docker", [
+    "run",
+    "--rm",
+    "-v",
+    `${ASDF_DATA_VOLUME}:/opt/asdf-data`,
+    STANDARD_IMAGE_TAG,
+    "bash",
+    "-lc",
+    `for b in ${bins}; do command -v "$b" >/dev/null 2>&1 || echo "UAI_MISSING:$b"; done`,
+  ]);
+  if (check.code !== 0) {
+    console.warn(
+      `[host-agent] could not check agent CLIs in ${ASDF_DATA_VOLUME} (exit ` +
+        `${check.code ?? "spawn"}); continuing. ${check.stderr.trim()}`,
+    );
+    return;
+  }
+  const missing = check.stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.startsWith("UAI_MISSING:"))
+    .map((l) => l.slice("UAI_MISSING:".length));
+  if (missing.length === 0) return;
+
+  const pkgs = VOLUME_AGENT_CLIS.filter((c) => missing.includes(c.bin))
+    .map((c) => c.pkg)
+    .join(" ");
+  console.log(
+    `[host-agent] repairing ${ASDF_DATA_VOLUME}: agent CLI(s) [${missing.join(", ")}] ` +
+      `missing from the shared volume — installing ${pkgs}`,
+  );
+  const repair = await run("docker", [
+    "run",
+    "--rm",
+    "-u",
+    "root",
+    // Run from /home/node so asdf resolves the node version from
+    // /home/node/.tool-versions. As root HOME is /root (no .tool-versions),
+    // and without a version asdf's npm shim aborts ("No version is set for
+    // command npm", exit 126). root can still write the volume from here.
+    "-w",
+    "/home/node",
+    "-v",
+    `${ASDF_DATA_VOLUME}:/opt/asdf-data`,
+    STANDARD_IMAGE_TAG,
+    "bash",
+    "-lc",
+    `npm install -g ${pkgs} && asdf reshim nodejs`,
+  ]);
+  if (repair.code === 0) {
+    console.log(
+      `[host-agent] ${ASDF_DATA_VOLUME} repaired — installed [${missing.join(", ")}]`,
+    );
+  } else {
+    console.warn(
+      `[host-agent] failed to repair ${ASDF_DATA_VOLUME} (exit ${repair.code ?? "spawn"}); ` +
+        `tasks may be missing [${missing.join(", ")}].\n${repair.stderr.trim()}`,
+    );
+  }
+}
+
+/**
+ * Ensure the standard image and the shared asdf data volume exist, and that the
+ * agent CLIs are present inside the volume. Builds the image only when `docker
+ * image inspect` fails. Best-effort: logs and continues on any error so the
+ * host keeps booting.
  */
 export async function ensureStandardImage(): Promise<void> {
   // 1. Shared asdf data volume — idempotent.
@@ -111,42 +196,37 @@ export async function ensureStandardImage(): Promise<void> {
     if (vol.code === null) return;
   }
 
-  // 2. Is the image already built?
-  const inspect = await run("docker", [
-    "image",
-    "inspect",
-    STANDARD_IMAGE_TAG,
-  ]);
+  // 2. Ensure the image is built.
+  let imageReady = false;
+  const inspect = await run("docker", ["image", "inspect", STANDARD_IMAGE_TAG]);
   if (inspect.code === 0) {
     console.log(`[host-agent] standard image ${STANDARD_IMAGE_TAG} present`);
-    return;
-  }
-  if (inspect.code === null) {
+    imageReady = true;
+  } else if (inspect.code === null) {
     console.warn(
       "[host-agent] docker unavailable; skipping standard image build. " +
         "Tasks will fail until docker is running.",
     );
     return;
+  } else {
+    const context = standardImageDir();
+    console.log(
+      `[host-agent] building standard image ${STANDARD_IMAGE_TAG} from ${context}`,
+    );
+    const build = await run("docker", ["build", "-t", STANDARD_IMAGE_TAG, context]);
+    if (build.code === 0) {
+      console.log(`[host-agent] built standard image ${STANDARD_IMAGE_TAG}`);
+      imageReady = true;
+    } else {
+      console.warn(
+        `[host-agent] standard image build failed (exit ${build.code ?? "spawn"}); ` +
+          "continuing. Tasks needing the image will surface this error.\n" +
+          build.stderr.trim(),
+      );
+    }
   }
 
-  // 3. Build it.
-  const context = standardImageDir();
-  console.log(
-    `[host-agent] building standard image ${STANDARD_IMAGE_TAG} from ${context}`,
-  );
-  const build = await run("docker", [
-    "build",
-    "-t",
-    STANDARD_IMAGE_TAG,
-    context,
-  ]);
-  if (build.code === 0) {
-    console.log(`[host-agent] built standard image ${STANDARD_IMAGE_TAG}`);
-    return;
-  }
-  console.warn(
-    `[host-agent] standard image build failed (exit ${build.code ?? "spawn"}); ` +
-      "continuing. Tasks needing the image will surface this error.\n" +
-      build.stderr.trim(),
-  );
+  // 3. Reconcile the agent CLIs into the shared volume (it shadows the image's
+  //    shims, so a stale volume can be missing one — the claude-127 bug).
+  if (imageReady) await ensureVolumeAgentClis();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",

package/scripts/agent/task-up.sh

@@ -173,11 +173,41 @@ while IFS= read -r project_obj; do
     | sed 's#^origin/##' || true)
   [ -n "$project_default" ] || project_default="main"
 
-  # Create the worktree on a fresh task branch off origin/<defaultBranch>.
-  step "WORKTREE_FAILED" "git worktree add ($project_id)"
   mkdir -p "$(dirname "$worktree_target")"
-  git -C "$mirror_dir" worktree add "$worktree_target" \
-    -b "$task_branch" "origin/$project_default"
+  if git -C "$mirror_dir" rev-parse --verify --quiet \
+       "refs/remotes/origin/$project_default" >/dev/null 2>&1; then
+    # Normal case: branch the task worktree off origin/<defaultBranch>.
+    step "WORKTREE_FAILED" "git worktree add ($project_id)"
+    git -C "$mirror_dir" worktree add "$worktree_target" \
+      -b "$task_branch" "origin/$project_default"
+  else
+    # Empty / branchless remote — there's no origin/<default> to branch from.
+    # Don't fail the whole task over it (the old behaviour: "invalid reference"
+    # -> WORKTREE_FAILED -> respawn loop). Start an empty, git-initialised
+    # workspace so the task still comes up and a first commit can populate the
+    # repo. Leave a note (git-excluded so it isn't accidentally committed).
+    step "WORKTREE_FAILED" "init empty workspace ($project_id)"
+    log "warning: $repo_url has no '$project_default' branch (empty repo?); starting an empty workspace for $project_slug"
+    rm -rf "$worktree_target"
+    mkdir -p "$worktree_target"
+    git -C "$worktree_target" init -q -b "$project_default" 2>/dev/null \
+      || { git -C "$worktree_target" init -q \
+           && git -C "$worktree_target" symbolic-ref HEAD "refs/heads/$project_default"; }
+    git -C "$worktree_target" remote add origin "$repo_url" 2>/dev/null || true
+    printf '%s\n' \
+      "# Empty repository" \
+      "" \
+      "\`$repo_url\` has no commits yet, so Uai started an empty workspace on" \
+      "branch \`$project_default\`. Make your first commit and run:" \
+      "" \
+      "    git push -u origin $project_default" \
+      "" \
+      "to initialise the repository." \
+      > "$worktree_target/UAI_EMPTY_REPO.md"
+    mkdir -p "$worktree_target/.git/info" 2>/dev/null || true
+    printf '%s\n' "/UAI_EMPTY_REPO.md" \
+      >> "$worktree_target/.git/info/exclude" 2>/dev/null || true
+  fi
 
   # Tool-version seeding: only when the worktree has no checked-in
   # .tool-versions AND the project declares one. Never overwrite a file
@@ -302,6 +332,12 @@ fi
   # per-user SSH identity, not an HTTPS token (uai-init routes remotes over SSH).
   # A project may declare GH_TOKEN/GITHUB_TOKEN as an env key, so skip them here
   # rather than trust callers — this is where the rule is enforced.
+  #
+  # The decrypted per-(project, key) env VALUES live in this script's process
+  # env (injected by lib/agent.ts from the host store). The `${KEY:-}`
+  # pass-throughs below resolve to them via docker's interpolation at up-time —
+  # the value is never written into the YAML (mirrors CLAUDE_CODE_OAUTH_TOKEN),
+  # so this stays secret-blind end to end (ADR-015).
   while IFS= read -r ekey; do
     [ -n "$ekey" ] || continue
     case "$ekey" in

package/src/cli.ts

@@ -21,8 +21,9 @@ import "./load-env";
 
 import { spawn, spawnSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { hostname } from "node:os";
+import { dirname } from "node:path";
 
 import { ulid } from "ulid";
 
@@ -298,9 +299,28 @@ async function cmdSetup(rest: string[]): Promise<void> {
     return;
   }
 
-  upsertEnvLocal("UAI_HOST_ID", hostId);
-  upsertEnvLocal("UAI_HOST_TOKEN", secret);
-  upsertEnvLocal("UAI_CLOUD_URL", cloud);
+  // The host is already created on the cloud and the token is spent. If the
+  // local write fails, don't lose the secret — print it so it can be saved by
+  // hand rather than forcing the user to mint a fresh token.
+  try {
+    upsertEnvLocal("UAI_HOST_ID", hostId);
+    upsertEnvLocal("UAI_HOST_TOKEN", secret);
+    upsertEnvLocal("UAI_CLOUD_URL", cloud);
+  } catch (err) {
+    console.error(
+      red(
+        `enrolled, but could not write ${envLocalPath()}: ${err instanceof Error ? err.message : String(err)}`,
+      ),
+    );
+    console.error(
+      dim("the host exists on the cloud — save these into that file manually, then `uai-host start`:"),
+    );
+    console.error(`  UAI_HOST_ID=${hostId}`);
+    console.error(`  UAI_HOST_TOKEN=${secret}`);
+    console.error(`  UAI_CLOUD_URL=${cloud}`);
+    process.exitCode = 1;
+    return;
+  }
   console.log(green("✓ enrolled") + dim(` — config written to ${envLocalPath()}`));
   console.log("");
   console.log("Start the host:");
@@ -326,6 +346,10 @@ async function cmdPair(token: string | undefined): Promise<void> {
 
 function upsertEnvLocal(key: string, value: string): void {
   const path = envLocalPath();
+  // UAI_HOME (~/.uai on a fresh install) may not exist yet — create it before
+  // the first write, or writeFileSync ENOENTs (which on `setup` would orphan a
+  // just-redeemed host + burn the one-time token).
+  mkdirSync(dirname(path), { recursive: true });
   const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
   const kept = existing
     .split("\n")

package/src/main.ts

@@ -34,6 +34,11 @@ import {
   ensureKeyForUser as ensureSshKeyForUser,
   getPublicKey as getSshPublicKey,
 } from "../lib/ssh";
+import {
+  deleteProjectEnvVar,
+  listProjectEnvKeys,
+  setProjectEnvVar,
+} from "../lib/host-env";
 import {
   packageVersion,
   serviceLogPath,
@@ -306,6 +311,33 @@ function connect(): void {
         }
         break;
       }
+      case "env.var.list":
+      case "env.var.set":
+      case "env.var.delete": {
+        try {
+          if (frame.kind === "env.var.set") {
+            setProjectEnvVar(frame.projectId, frame.key, frame.value);
+          } else if (frame.kind === "env.var.delete") {
+            deleteProjectEnvVar(frame.projectId, frame.key);
+          }
+          // The ack carries the project's KEY NAMES only — values never cross
+          // the bridge.
+          send(socket, {
+            kind: "env.var.ack",
+            opId: frame.opId,
+            ok: true,
+            keys: listProjectEnvKeys(frame.projectId),
+          });
+        } catch (err) {
+          send(socket, {
+            kind: "env.var.ack",
+            opId: frame.opId,
+            ok: false,
+            error: err instanceof Error ? err.message : "env var op failed",
+          });
+        }
+        break;
+      }
     }
   });
 
@@ -824,6 +856,41 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
   ) {
     return { kind: frame.kind, userId: frame.userId };
   }
+  if (
+    frame.kind === "env.var.list" &&
+    typeof frame.opId === "string" &&
+    typeof frame.projectId === "string"
+  ) {
+    return { kind: "env.var.list", opId: frame.opId, projectId: frame.projectId };
+  }
+  if (
+    frame.kind === "env.var.set" &&
+    typeof frame.opId === "string" &&
+    typeof frame.projectId === "string" &&
+    typeof frame.key === "string" &&
+    typeof frame.value === "string"
+  ) {
+    return {
+      kind: "env.var.set",
+      opId: frame.opId,
+      projectId: frame.projectId,
+      key: frame.key,
+      value: frame.value,
+    };
+  }
+  if (
+    frame.kind === "env.var.delete" &&
+    typeof frame.opId === "string" &&
+    typeof frame.projectId === "string" &&
+    typeof frame.key === "string"
+  ) {
+    return {
+      kind: "env.var.delete",
+      opId: frame.opId,
+      projectId: frame.projectId,
+      key: frame.key,
+    };
+  }
   console.warn("[host-agent] dropping unknown frame");
   return null;
 }

package/src/protocol.ts

@@ -323,7 +323,21 @@ export type CloudToHost =
   // without creating, `ensure` creates-if-absent, `delete` removes.
   | { kind: "ssh.key.get"; userId: string }
   | { kind: "ssh.key.ensure"; userId: string }
-  | { kind: "ssh.key.delete"; userId: string };
+  | { kind: "ssh.key.delete"; userId: string }
+  // Per-(project, key) env var lifecycle. Values are encrypted + stored on the
+  // host scoped to a projectId; only KEY NAMES ever cross the bridge
+  // (env.var.ack) — the value on `env.var.set` is write-only (never echoed
+  // back). `opId` correlates request↔ack; the ack's `keys` are that project's
+  // keys.
+  | { kind: "env.var.list"; opId: string; projectId: string }
+  | {
+      kind: "env.var.set";
+      opId: string;
+      projectId: string;
+      key: string;
+      value: string;
+    }
+  | { kind: "env.var.delete"; opId: string; projectId: string; key: string };
 
 export type HostToCloud =
   | { kind: "auth"; token: string; hostId: string }
@@ -352,7 +366,12 @@ export type HostToCloud =
   // Ack for ssh.key.get / ssh.key.ensure / ssh.key.delete (ADR-029). publicKey
   // is null when the user has no key (after delete, or a get-miss).
   | { kind: "ssh.key.ack"; userId: string; ok: true; publicKey: string | null }
-  | { kind: "ssh.key.ack"; userId: string; ok: false; error: string };
+  | { kind: "ssh.key.ack"; userId: string; ok: false; error: string }
+  // Ack for env.var.list / env.var.set / env.var.delete. Returns the project's
+  // KEY NAMES only — values never cross the bridge (secret-blind, ADR-015).
+  // `opId` correlates to the request.
+  | { kind: "env.var.ack"; opId: string; ok: true; keys: string[] }
+  | { kind: "env.var.ack"; opId: string; ok: false; error: string };
 
 export type HostEvent =
   | {