@treeseed/sdk 0.4.13 → 0.5.0

package/dist/operations/services/config-runtime.js

@@ -1,8 +1,8 @@
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { dirname, resolve } from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import {
   getTreeseedEnvironmentSuggestedValues,
@@ -16,7 +16,6 @@ import {
   createPersistentDeployTarget,
   ensureGeneratedWranglerConfig,
   loadDeployState,
-  markManagedServicesInitialized,
   markDeploymentInitialized,
   provisionCloudflareResources,
   syncCloudflareSecrets,
@@ -24,18 +23,38 @@ import {
 } from "./deploy.js";
 import { maybeResolveGitHubRepositorySlug } from "./github-automation.js";
 import { validateRailwayDeployPrerequisites } from "./railway-deploy.js";
-import { loadCliDeployConfig, resolveWranglerBin, withProcessCwd } from "./runtime-tools.js";
+import { loadCliDeployConfig, packageScriptPath, resolveWranglerBin, withProcessCwd } from "./runtime-tools.js";
+import {
+  assertTreeseedKeyAgentResponse,
+  getTreeseedKeyAgentPaths,
+  readWrappedMachineKeyFile,
+  replaceWrappedMachineKey,
+  rotateWrappedMachineKeyPassphrase,
+  TREESEED_KEY_AGENT_IDLE_TIMEOUT_MS,
+  TREESEED_MACHINE_KEY_PASSPHRASE_ENV,
+  TreeseedKeyAgentError,
+  unwrapMachineKey
+} from "./key-agent.js";
+import { TREESEED_MACHINE_KEY_PASSPHRASE_ENV as TREESEED_MACHINE_KEY_PASSPHRASE_ENV2, TreeseedKeyAgentError as TreeseedKeyAgentError2 } from "./key-agent.js";
 const MACHINE_CONFIG_RELATIVE_PATH = ".treeseed/config/machine.yaml";
+const LEGACY_ENVIRONMENT_ALIASES = {
+  RAILWAY_API_KEY: "RAILWAY_API_TOKEN"
+};
 const MACHINE_KEY_HOME_RELATIVE_PATH = ".treeseed/config/machine.key";
 const LEGACY_MACHINE_KEY_RELATIVE_PATH = ".treeseed/config/machine.key";
 const REMOTE_AUTH_RELATIVE_PATH = ".treeseed/config/remote-auth.json";
 const TEMPLATE_CATALOG_CACHE_RELATIVE_PATH = "treeseed/cache/template-catalog.json";
 const TENANT_ENVIRONMENT_OVERLAY_PATH = "src/env.yaml";
 const CLOUDFLARE_ACCOUNT_ID_PLACEHOLDER = "replace-with-cloudflare-account-id";
+const TREESEED_KEY_AGENT_AUTOPROMPT_ENV = "TREESEED_KEY_AGENT_AUTOPROMPT";
 const DEFAULT_TREESEED_API_BASE_URL = "https://api.treeseed.ai";
 const DEFAULT_TEMPLATE_CATALOG_URL = "https://api.treeseed.ai/search/templates";
 const TREESEED_TEMPLATE_CATALOG_URL_ENV = "TREESEED_TEMPLATE_CATALOG_URL";
 const TREESEED_API_BASE_URL_ENV = "TREESEED_API_BASE_URL";
+const CLI_CHECK_TIMEOUT_MS = 5e3;
+const DEPRECATED_LOCAL_ENV_FILES = [".env.local", ".dev.vars"];
+const warnedDeprecatedLocalEnvRoots = /* @__PURE__ */ new Set();
+const inlineTreeseedSecretSessions = /* @__PURE__ */ new Map();
 function createDefaultRemoteHost() {
   return {
     id: "official",
@@ -71,9 +90,7 @@ function createDefaultServiceSettings() {
       projectId: "",
       projectName: "",
       apiServiceId: "",
-      apiServiceName: "",
-      agentsServiceId: "",
-      agentsServiceName: ""
+      apiServiceName: ""
     }
   };
 }
@@ -85,30 +102,26 @@ function normalizeServiceSettings(value) {
       projectId: typeof railway.projectId === "string" ? railway.projectId : "",
       projectName: typeof railway.projectName === "string" ? railway.projectName : "",
       apiServiceId: typeof railway.apiServiceId === "string" ? railway.apiServiceId : "",
-      apiServiceName: typeof railway.apiServiceName === "string" ? railway.apiServiceName : "",
-      agentsServiceId: typeof railway.agentsServiceId === "string" ? railway.agentsServiceId : "",
-      agentsServiceName: typeof railway.agentsServiceName === "string" ? railway.agentsServiceName : ""
+      apiServiceName: typeof railway.apiServiceName === "string" ? railway.apiServiceName : ""
     }
   };
 }
 function ensureParent(filePath) {
   mkdirSync(dirname(filePath), { recursive: true });
 }
-function parseEnvFile(contents) {
-  return contents.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith("#")).reduce((acc, line) => {
-    const separatorIndex = line.indexOf("=");
-    if (separatorIndex === -1) {
-      return acc;
-    }
-    acc[line.slice(0, separatorIndex).trim()] = line.slice(separatorIndex + 1);
-    return acc;
-  }, {});
+function listDeprecatedTreeseedLocalEnvFiles(tenantRoot) {
+  return DEPRECATED_LOCAL_ENV_FILES.map((fileName) => resolve(tenantRoot, fileName)).filter((filePath) => existsSync(filePath));
 }
-function readEnvFileIfPresent(filePath) {
-  if (!existsSync(filePath)) {
-    return {};
+function warnDeprecatedTreeseedLocalEnvFiles(tenantRoot, write = (line) => console.warn(line)) {
+  const existing = listDeprecatedTreeseedLocalEnvFiles(tenantRoot);
+  if (existing.length === 0 || warnedDeprecatedLocalEnvRoots.has(tenantRoot)) {
+    return existing;
   }
-  return parseEnvFile(readFileSync(filePath, "utf8"));
+  warnedDeprecatedLocalEnvRoots.add(tenantRoot);
+  write(
+    `Treeseed ignores deprecated local env files: ${existing.map((filePath) => filePath.replace(`${tenantRoot}/`, "")).join(", ")}. Delete them and rely on .treeseed/config/machine.yaml plus Treeseed-launched commands.`
+  );
+  return existing;
 }
 function maskValue(value) {
   if (!value) {
@@ -133,14 +146,12 @@ function syncManagedServiceSettingsFromDeployConfig(tenantRoot) {
   const config = loadTreeseedMachineConfig(tenantRoot);
   const deployConfig = loadTenantDeployConfig(tenantRoot);
   const railway = config.settings.services.railway;
-  railway.projectId = deployConfig.services?.api?.railway?.projectId ?? deployConfig.services?.agents?.railway?.projectId ?? railway.projectId;
-  railway.projectName = deployConfig.services?.api?.railway?.projectName ?? deployConfig.services?.agents?.railway?.projectName ?? railway.projectName;
+  railway.projectId = deployConfig.services?.api?.railway?.projectId ?? railway.projectId;
+  railway.projectName = deployConfig.services?.api?.railway?.projectName ?? railway.projectName;
   railway.apiServiceId = deployConfig.services?.api?.railway?.serviceId ?? railway.apiServiceId;
   railway.apiServiceName = deployConfig.services?.api?.railway?.serviceName ?? railway.apiServiceName;
-  railway.agentsServiceId = deployConfig.services?.agents?.railway?.serviceId ?? railway.agentsServiceId;
-  railway.agentsServiceName = deployConfig.services?.agents?.railway?.serviceName ?? railway.agentsServiceName;
   const remote = normalizeRemoteSettings(config.settings.remote);
-  const defaultHostBaseUrl = deployConfig.services?.api?.environments?.prod?.baseUrl ?? deployConfig.services?.api?.publicBaseUrl ?? remote.hosts[0]?.baseUrl ?? DEFAULT_TREESEED_API_BASE_URL;
+  const defaultHostBaseUrl = process.env[TREESEED_API_BASE_URL_ENV] ?? deployConfig.services?.api?.environments?.prod?.baseUrl ?? deployConfig.services?.api?.publicBaseUrl ?? remote.hosts[0]?.baseUrl ?? DEFAULT_TREESEED_API_BASE_URL;
   const officialHost = remote.hosts.find((entry) => entry.id === "official");
   if (officialHost) {
     officialHost.baseUrl = defaultHostBaseUrl.replace(/\/$/u, "");
@@ -190,6 +201,448 @@ function getTreeseedMachineConfigPaths(tenantRoot) {
     legacyKeyPath: resolve(tenantRoot, LEGACY_MACHINE_KEY_RELATIVE_PATH)
   };
 }
+function keyAgentScriptPath() {
+  return packageScriptPath("key-agent.ts");
+}
+function keyAgentRunTsPath() {
+  return packageScriptPath("run-ts.mjs");
+}
+function keyAgentScriptCwd() {
+  return dirname(dirname(keyAgentRunTsPath()));
+}
+function sleepMs(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/gu, `'\\''`)}'`;
+}
+function keyAgentAutoPromptEnabled() {
+  const value = String(process.env[TREESEED_KEY_AGENT_AUTOPROMPT_ENV] ?? "").trim().toLowerCase();
+  if (value === "0" || value === "false" || value === "off") {
+    return false;
+  }
+  return process.stdin.isTTY && process.stdout.isTTY;
+}
+function useInlineKeyAgentTransport() {
+  return process.env.VITEST === "true" || process.env.TREESEED_KEY_AGENT_TRANSPORT === "inline";
+}
+function withTreeseedKeyAgentAutopromptDisabled(action) {
+  const previous = process.env[TREESEED_KEY_AGENT_AUTOPROMPT_ENV];
+  process.env[TREESEED_KEY_AGENT_AUTOPROMPT_ENV] = "0";
+  try {
+    return action();
+  } finally {
+    if (previous === void 0) {
+      delete process.env[TREESEED_KEY_AGENT_AUTOPROMPT_ENV];
+    } else {
+      process.env[TREESEED_KEY_AGENT_AUTOPROMPT_ENV] = previous;
+    }
+  }
+}
+function startTreeseedKeyAgentDaemon(tenantRoot) {
+  const { keyPath } = getTreeseedMachineConfigPaths(tenantRoot);
+  const { socketPath } = getTreeseedKeyAgentPaths();
+  const command = [
+    shellQuote(process.execPath),
+    shellQuote(keyAgentRunTsPath()),
+    shellQuote(keyAgentScriptPath()),
+    "serve",
+    "--key-path",
+    shellQuote(keyPath),
+    "--socket-path",
+    shellQuote(socketPath),
+    "--idle-timeout-ms",
+    shellQuote(String(TREESEED_KEY_AGENT_IDLE_TIMEOUT_MS)),
+    ">/dev/null",
+    "2>/dev/null",
+    "&"
+  ].join(" ");
+  const child = spawn("bash", ["-lc", command], {
+    cwd: keyAgentScriptCwd(),
+    stdio: "ignore"
+  });
+  child.unref();
+}
+function runTreeseedKeyAgentCommand(args, options = {}) {
+  const result = spawnSync(process.execPath, [
+    keyAgentRunTsPath(),
+    keyAgentScriptPath(),
+    ...args
+  ], {
+    cwd: keyAgentScriptCwd(),
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      ...options.env ?? {}
+    },
+    stdio: options.input !== void 0 ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"],
+    input: options.input
+  });
+  if (result.status !== 0 && (!result.stdout || result.stdout.trim().length === 0)) {
+    return {
+      ok: false,
+      code: "daemon_unavailable",
+      message: result.stderr?.trim() || "Treeseed key-agent command failed."
+    };
+  }
+  try {
+    return JSON.parse(result.stdout.trim() || "{}");
+  } catch {
+    throw new TreeseedKeyAgentError(
+      "daemon_unavailable",
+      result.stderr?.trim() || "Treeseed key-agent command returned an invalid response."
+    );
+  }
+}
+function requestTreeseedKeyAgent(tenantRoot, payload, { ensureRunning = false, env } = {}) {
+  const invoke = () => runTreeseedKeyAgentCommand([
+    "request",
+    JSON.stringify(payload)
+  ], { env });
+  let response = invoke();
+  if (response.code !== "daemon_unavailable" || !ensureRunning) {
+    return response;
+  }
+  startTreeseedKeyAgentDaemon(tenantRoot);
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    response = invoke();
+    if (response.code !== "daemon_unavailable") {
+      return response;
+    }
+    sleepMs(25);
+  }
+  return response;
+}
+function inspectTreeseedKeyAgentStatus(tenantRoot) {
+  const { keyPath } = getTreeseedMachineConfigPaths(tenantRoot);
+  const { socketPath } = getTreeseedKeyAgentPaths();
+  const wrapped = readWrappedMachineKeyFile(keyPath);
+  if (useInlineKeyAgentTransport()) {
+    const session = inlineTreeseedSecretSessions.get(keyPath) ?? { machineKey: null, lastTouchedAt: 0, idleTimeoutMs: TREESEED_KEY_AGENT_IDLE_TIMEOUT_MS };
+    const idleRemainingMs = session.machineKey ? Math.max(0, session.idleTimeoutMs - (Date.now() - session.lastTouchedAt)) : 0;
+    if (idleRemainingMs === 0) {
+      session.machineKey = null;
+    }
+    inlineTreeseedSecretSessions.set(keyPath, session);
+    return {
+      running: true,
+      unlocked: Boolean(session.machineKey) && idleRemainingMs > 0,
+      wrappedKeyPresent: wrapped.exists && Boolean(wrapped.wrapped),
+      migrationRequired: wrapped.migrationRequired,
+      keyPath,
+      socketPath,
+      idleTimeoutMs: session.idleTimeoutMs,
+      idleRemainingMs
+    };
+  }
+  const response = requestTreeseedKeyAgent(tenantRoot, {
+    command: "status",
+    keyPath,
+    socketPath,
+    idleTimeoutMs: TREESEED_KEY_AGENT_IDLE_TIMEOUT_MS
+  });
+  if (response.ok && response.status) {
+    return response.status;
+  }
+  return {
+    running: false,
+    unlocked: false,
+    wrappedKeyPresent: wrapped.exists && Boolean(wrapped.wrapped),
+    migrationRequired: wrapped.migrationRequired,
+    keyPath,
+    socketPath,
+    idleTimeoutMs: TREESEED_KEY_AGENT_IDLE_TIMEOUT_MS,
+    idleRemainingMs: 0
+  };
+}
+function unlockTreeseedSecretSessionInteractive(tenantRoot) {
+  if (useInlineKeyAgentTransport()) {
+    throw new TreeseedKeyAgentError("interactive_required", "Inline test transport does not support interactive unlock.");
+  }
+  const { keyPath } = getTreeseedMachineConfigPaths(tenantRoot);
+  const { socketPath } = getTreeseedKeyAgentPaths();
+  startTreeseedKeyAgentDaemon(tenantRoot);
+  let response = { ok: false, code: "daemon_unavailable", message: "Treeseed key agent is unavailable." };
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    response = runTreeseedKeyAgentCommand([
+      "unlock-interactive",
+      "--key-path",
+      keyPath,
+      "--socket-path",
+      socketPath,
+      "--idle-timeout-ms",
+      String(TREESEED_KEY_AGENT_IDLE_TIMEOUT_MS),
+      "--allow-migration",
+      "--create-if-missing"
+    ]);
+    if (response.code !== "daemon_unavailable") {
+      break;
+    }
+    sleepMs(25);
+  }
+  assertTreeseedKeyAgentResponse(response, "Unable to unlock the Treeseed secret session.");
+  return response.status;
+}
+function unlockTreeseedSecretSessionFromEnv(tenantRoot, options = {}) {
+  const { keyPath } = getTreeseedMachineConfigPaths(tenantRoot);
+  const { socketPath } = getTreeseedKeyAgentPaths();
+  if (useInlineKeyAgentTransport()) {
+    const passphrase = String(process.env[TREESEED_MACHINE_KEY_PASSPHRASE_ENV] ?? "").trim();
+    if (!passphrase) {
+      throw new TreeseedKeyAgentError(
+        "interactive_required",
+        `Set ${TREESEED_MACHINE_KEY_PASSPHRASE_ENV} before unlocking the Treeseed secret session.`
+      );
+    }
+    const wrapped = readWrappedMachineKeyFile(keyPath);
+    const machineKey = wrapped.wrapped ? unwrapMachineKey(wrapped.wrapped, passphrase) : wrapped.plaintextLegacy ? (() => {
+      if (options.allowMigration === false) {
+        throw new TreeseedKeyAgentError("wrapped_key_migration_required", "Wrap the legacy machine key before unlocking it.");
+      }
+      replaceWrappedMachineKey(keyPath, wrapped.plaintextLegacy, passphrase);
+      return wrapped.plaintextLegacy;
+    })() : (() => {
+      if (options.createIfMissing === false) {
+        throw new TreeseedKeyAgentError("wrapped_key_missing", "No wrapped Treeseed machine key exists yet.");
+      }
+      const createdKey = randomBytes(32);
+      replaceWrappedMachineKey(keyPath, createdKey, passphrase);
+      return createdKey;
+    })();
+    inlineTreeseedSecretSessions.set(keyPath, {
+      machineKey,
+      lastTouchedAt: Date.now(),
+      idleTimeoutMs: TREESEED_KEY_AGENT_IDLE_TIMEOUT_MS
+    });
+    return inspectTreeseedKeyAgentStatus(tenantRoot);
+  }
+  startTreeseedKeyAgentDaemon(tenantRoot);
+  let response = { ok: false, code: "daemon_unavailable", message: "Treeseed key agent is unavailable." };
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    response = runTreeseedKeyAgentCommand([
+      "unlock-from-env",
+      "--key-path",
+      keyPath,
+      "--socket-path",
+      socketPath,
+      "--idle-timeout-ms",
+      String(TREESEED_KEY_AGENT_IDLE_TIMEOUT_MS),
+      ...options.allowMigration === false ? [] : ["--allow-migration"],
+      ...options.createIfMissing === false ? [] : ["--create-if-missing"]
+    ]);
+    if (response.code !== "daemon_unavailable") {
+      break;
+    }
+    sleepMs(25);
+  }
+  assertTreeseedKeyAgentResponse(
+    response,
+    `Unable to unlock the Treeseed secret session from ${TREESEED_MACHINE_KEY_PASSPHRASE_ENV}.`
+  );
+  return response.status;
+}
+function unlockTreeseedSecretSessionWithPassphrase(tenantRoot, passphrase, options = {}) {
+  const normalizedPassphrase = String(passphrase ?? "").trim();
+  if (!normalizedPassphrase) {
+    throw new TreeseedKeyAgentError(
+      "interactive_required",
+      `Set ${TREESEED_MACHINE_KEY_PASSPHRASE_ENV} before unlocking the Treeseed secret session.`
+    );
+  }
+  const previousPassphrase = process.env[TREESEED_MACHINE_KEY_PASSPHRASE_ENV];
+  process.env[TREESEED_MACHINE_KEY_PASSPHRASE_ENV] = normalizedPassphrase;
+  try {
+    if (useInlineKeyAgentTransport()) {
+      return unlockTreeseedSecretSessionFromEnv(tenantRoot, options);
+    }
+    const { keyPath } = getTreeseedMachineConfigPaths(tenantRoot);
+    const { socketPath } = getTreeseedKeyAgentPaths();
+    startTreeseedKeyAgentDaemon(tenantRoot);
+    let response = { ok: false, code: "daemon_unavailable", message: "Treeseed key agent is unavailable." };
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+      response = runTreeseedKeyAgentCommand([
+        "unlock-from-env",
+        "--key-path",
+        keyPath,
+        "--socket-path",
+        socketPath,
+        "--idle-timeout-ms",
+        String(TREESEED_KEY_AGENT_IDLE_TIMEOUT_MS),
+        ...options.allowMigration === false ? [] : ["--allow-migration"],
+        ...options.createIfMissing === false ? [] : ["--create-if-missing"]
+      ], {
+        env: {
+          [TREESEED_MACHINE_KEY_PASSPHRASE_ENV]: normalizedPassphrase
+        }
+      });
+      if (response.code !== "daemon_unavailable") {
+        break;
+      }
+      sleepMs(25);
+    }
+    assertTreeseedKeyAgentResponse(
+      response,
+      `Unable to unlock the Treeseed secret session from ${TREESEED_MACHINE_KEY_PASSPHRASE_ENV}.`
+    );
+    return response.status;
+  } finally {
+    if (previousPassphrase === void 0) {
+      delete process.env[TREESEED_MACHINE_KEY_PASSPHRASE_ENV];
+    } else {
+      process.env[TREESEED_MACHINE_KEY_PASSPHRASE_ENV] = previousPassphrase;
+    }
+  }
+}
+async function ensureTreeseedSecretSessionForConfig({
+  tenantRoot,
+  interactive = false,
+  env = process.env,
+  createIfMissing = true,
+  allowMigration = true,
+  promptForPassphrase,
+  promptForNewPassphrase
+}) {
+  const status = inspectTreeseedKeyAgentStatus(tenantRoot);
+  if (status.unlocked) {
+    return {
+      status,
+      createdWrappedKey: false,
+      migratedWrappedKey: false,
+      unlockSource: "existing-session"
+    };
+  }
+  const wrappedBefore = readWrappedMachineKeyFile(status.keyPath);
+  const envPassphrase = String(env[TREESEED_MACHINE_KEY_PASSPHRASE_ENV] ?? "").trim();
+  let unlockSource = "existing-session";
+  let nextStatus;
+  if (envPassphrase) {
+    nextStatus = unlockTreeseedSecretSessionWithPassphrase(tenantRoot, envPassphrase, {
+      createIfMissing,
+      allowMigration
+    });
+    unlockSource = "env";
+  } else if (interactive && status.migrationRequired) {
+    if (!promptForNewPassphrase) {
+      throw new TreeseedKeyAgentError("interactive_required", "A passphrase prompt is required to migrate the Treeseed machine key.");
+    }
+    nextStatus = unlockTreeseedSecretSessionWithPassphrase(tenantRoot, await promptForNewPassphrase(), {
+      createIfMissing: false,
+      allowMigration: true
+    });
+    unlockSource = "interactive";
+  } else if (interactive && !status.wrappedKeyPresent) {
+    if (!promptForNewPassphrase) {
+      throw new TreeseedKeyAgentError("interactive_required", "A passphrase prompt is required to create the Treeseed machine key.");
+    }
+    nextStatus = unlockTreeseedSecretSessionWithPassphrase(tenantRoot, await promptForNewPassphrase(), {
+      createIfMissing: true,
+      allowMigration: false
+    });
+    unlockSource = "interactive";
+  } else if (interactive) {
+    if (!promptForPassphrase) {
+      throw new TreeseedKeyAgentError("interactive_required", "A passphrase prompt is required to unlock the Treeseed machine key.");
+    }
+    nextStatus = unlockTreeseedSecretSessionWithPassphrase(tenantRoot, await promptForPassphrase(), {
+      createIfMissing: false,
+      allowMigration: false
+    });
+    unlockSource = "interactive";
+  } else if (status.migrationRequired) {
+    throw new TreeseedKeyAgentError(
+      "wrapped_key_migration_required",
+      `Set ${TREESEED_MACHINE_KEY_PASSPHRASE_ENV} before running treeseed config non-interactively so Treeseed can wrap the legacy machine key.`,
+      { keyPath: status.keyPath }
+    );
+  } else if (!status.wrappedKeyPresent) {
+    throw new TreeseedKeyAgentError(
+      "wrapped_key_missing",
+      `Set ${TREESEED_MACHINE_KEY_PASSPHRASE_ENV} before running treeseed config non-interactively so Treeseed can create the wrapped machine key.`,
+      { keyPath: status.keyPath }
+    );
+  } else {
+    throw new TreeseedKeyAgentError(
+      "locked",
+      `Set ${TREESEED_MACHINE_KEY_PASSPHRASE_ENV} before running treeseed config non-interactively so Treeseed can unlock the wrapped machine key.`,
+      { keyPath: status.keyPath }
+    );
+  }
+  const wrappedAfter = readWrappedMachineKeyFile(status.keyPath);
+  return {
+    status: nextStatus,
+    createdWrappedKey: !wrappedBefore.wrapped && Boolean(wrappedAfter.wrapped) && !wrappedBefore.migrationRequired,
+    migratedWrappedKey: wrappedBefore.migrationRequired && Boolean(wrappedAfter.wrapped),
+    unlockSource
+  };
+}
+function lockTreeseedSecretSession(tenantRoot) {
+  const { keyPath } = getTreeseedMachineConfigPaths(tenantRoot);
+  if (useInlineKeyAgentTransport()) {
+    inlineTreeseedSecretSessions.set(keyPath, {
+      machineKey: null,
+      lastTouchedAt: 0,
+      idleTimeoutMs: TREESEED_KEY_AGENT_IDLE_TIMEOUT_MS
+    });
+    return inspectTreeseedKeyAgentStatus(tenantRoot);
+  }
+  const status = inspectTreeseedKeyAgentStatus(tenantRoot);
+  if (!status.running) {
+    return status;
+  }
+  const response = requestTreeseedKeyAgent(tenantRoot, {
+    command: "lock",
+    keyPath: status.keyPath,
+    socketPath: status.socketPath,
+    idleTimeoutMs: status.idleTimeoutMs
+  });
+  assertTreeseedKeyAgentResponse(response, "Unable to lock the Treeseed secret session.");
+  return response.status;
+}
+function resolveUnlockedMachineKey(tenantRoot) {
+  const status = inspectTreeseedKeyAgentStatus(tenantRoot);
+  if (!status.unlocked) {
+    const envPassphrase = String(process.env[TREESEED_MACHINE_KEY_PASSPHRASE_ENV] ?? "").trim();
+    if (envPassphrase) {
+      unlockTreeseedSecretSessionFromEnv(tenantRoot);
+    } else if (keyAgentAutoPromptEnabled()) {
+      unlockTreeseedSecretSessionInteractive(tenantRoot);
+    } else if (status.migrationRequired) {
+      throw new TreeseedKeyAgentError(
+        "wrapped_key_migration_required",
+        "The Treeseed machine key is still stored in the legacy plaintext format. Run `treeseed secrets:migrate-key` or unlock it from an interactive session first.",
+        { keyPath: status.keyPath }
+      );
+    } else if (!status.wrappedKeyPresent) {
+      throw new TreeseedKeyAgentError(
+        "wrapped_key_missing",
+        `No wrapped Treeseed machine key exists yet. Run \`treeseed config\` or \`treeseed secrets:unlock\` from an interactive shell, or set ${TREESEED_MACHINE_KEY_PASSPHRASE_ENV} for the startup unlock path.`,
+        { keyPath: status.keyPath }
+      );
+    } else {
+      throw new TreeseedKeyAgentError(
+        "locked",
+        `Treeseed secrets are locked. Run \`treeseed secrets:unlock\`, unlock from an interactive session, or set ${TREESEED_MACHINE_KEY_PASSPHRASE_ENV} for the startup unlock path before using secret-backed commands.`,
+        { keyPath: status.keyPath }
+      );
+    }
+  }
+  if (useInlineKeyAgentTransport()) {
+    const session = inlineTreeseedSecretSessions.get(status.keyPath);
+    if (!session?.machineKey) {
+      throw new TreeseedKeyAgentError("locked", "Treeseed secrets are locked.");
+    }
+    session.lastTouchedAt = Date.now();
+    return session.machineKey;
+  }
+  const response = requestTreeseedKeyAgent(tenantRoot, {
+    command: "get-machine-key",
+    keyPath: status.keyPath,
+    socketPath: status.socketPath,
+    idleTimeoutMs: status.idleTimeoutMs
+  });
+  assertTreeseedKeyAgentResponse(response, "Unable to resolve the Treeseed machine key from the local key agent.");
+  return Buffer.from(String(response.machineKey ?? ""), "base64");
+}
 function getTreeseedRemoteAuthPaths(tenantRoot) {
   return {
     authPath: getTreeseedMachineConfigPaths(tenantRoot).authPath
@@ -232,30 +685,16 @@ function createDefaultTreeseedMachineConfig({ tenantRoot, deployConfig, tenantCo
     )
   };
 }
-function readMachineKey(keyPath) {
-  if (existsSync(keyPath)) {
-    return Buffer.from(readFileSync(keyPath, "utf8").trim(), "base64");
-  }
-  return null;
-}
-function writeMachineKey(keyPath, key) {
-  ensureParent(keyPath);
-  writeFileSync(keyPath, `${key.toString("base64")}
-`, { mode: 384 });
-}
-function ensureHomeMachineKey(tenantRoot) {
-  const { keyPath } = getTreeseedMachineConfigPaths(tenantRoot);
-  const existing = readMachineKey(keyPath);
-  if (existing) {
-    return existing;
-  }
-  const key = randomBytes(32);
-  writeMachineKey(keyPath, key);
-  return key;
-}
 function loadLegacyMachineKey(tenantRoot) {
   const { legacyKeyPath } = getTreeseedMachineConfigPaths(tenantRoot);
-  return readMachineKey(legacyKeyPath);
+  if (!existsSync(legacyKeyPath)) {
+    return null;
+  }
+  try {
+    return Buffer.from(readFileSync(legacyKeyPath, "utf8").trim(), "base64");
+  } catch {
+    return null;
+  }
 }
 function createDefaultRemoteAuthState() {
   return {
@@ -386,21 +825,8 @@ function reencryptTreeseedEncryptedState(tenantRoot, oldKey, newKey) {
     });
   }
 }
-function ensureTreeseedMachineKeyMigrated(tenantRoot) {
-  const homeKey = ensureHomeMachineKey(tenantRoot);
-  const legacyKey = loadLegacyMachineKey(tenantRoot);
-  if (!legacyKey) {
-    return homeKey;
-  }
-  try {
-    reencryptTreeseedEncryptedState(tenantRoot, legacyKey, homeKey);
-    removeLegacyMachineKeyIfSafe(tenantRoot);
-  } catch {
-  }
-  return homeKey;
-}
 function loadMachineKey(tenantRoot) {
-  return ensureTreeseedMachineKeyMigrated(tenantRoot);
+  return resolveUnlockedMachineKey(tenantRoot);
 }
 function decryptValueWithMachineKey(tenantRoot, payload, key) {
   try {
@@ -421,13 +847,73 @@ function rotateTreeseedMachineKey(tenantRoot) {
   const oldKey = loadMachineKey(tenantRoot);
   const newKey = randomBytes(32);
   reencryptTreeseedEncryptedState(tenantRoot, oldKey, newKey);
-  writeMachineKey(keyPath, newKey);
+  const status = inspectTreeseedKeyAgentStatus(tenantRoot);
+  if (!status.unlocked) {
+    throw new TreeseedKeyAgentError("locked", "Treeseed secrets must be unlocked before rotating the machine key.", { keyPath });
+  }
+  const wrapped = readWrappedMachineKeyFile(keyPath);
+  if (!wrapped.wrapped) {
+    throw new TreeseedKeyAgentError(
+      wrapped.migrationRequired ? "wrapped_key_migration_required" : "wrapped_key_missing",
+      wrapped.migrationRequired ? "Wrap the Treeseed machine key before rotating it." : "Create and unlock the Treeseed machine key before rotating it.",
+      { keyPath }
+    );
+  }
+  const passphrase = String(process.env[TREESEED_MACHINE_KEY_PASSPHRASE_ENV] ?? "").trim();
+  if (!passphrase) {
+    throw new TreeseedKeyAgentError(
+      "interactive_required",
+      `Set ${TREESEED_MACHINE_KEY_PASSPHRASE_ENV} when rotating the machine key non-interactively, or use \`treeseed secrets:rotate-machine-key\` from an interactive shell.`,
+      { keyPath }
+    );
+  }
+  replaceWrappedMachineKey(keyPath, newKey, passphrase);
+  unlockTreeseedSecretSessionFromEnv(tenantRoot, { allowMigration: false, createIfMissing: false });
   removeLegacyMachineKeyIfSafe(tenantRoot);
   return {
     keyPath,
     rotated: true
   };
 }
+function rotateTreeseedMachineKeyPassphrase(tenantRoot, passphrase) {
+  const { keyPath } = getTreeseedMachineConfigPaths(tenantRoot);
+  const machineKey = loadMachineKey(tenantRoot);
+  rotateWrappedMachineKeyPassphrase(keyPath, machineKey, passphrase);
+  return {
+    keyPath,
+    rotated: true
+  };
+}
+function migrateTreeseedMachineKeyToWrapped(tenantRoot, passphrase) {
+  const { keyPath } = getTreeseedMachineConfigPaths(tenantRoot);
+  const wrapped = readWrappedMachineKeyFile(keyPath);
+  if (wrapped.wrapped) {
+    return {
+      keyPath,
+      migrated: false,
+      alreadyWrapped: true
+    };
+  }
+  if (wrapped.plaintextLegacy) {
+    replaceWrappedMachineKey(keyPath, wrapped.plaintextLegacy, passphrase);
+  } else {
+    const legacyKey = loadLegacyMachineKey(tenantRoot);
+    if (!legacyKey) {
+      throw new TreeseedKeyAgentError(
+        "wrapped_key_missing",
+        "No existing machine key was found to migrate.",
+        { keyPath }
+      );
+    }
+    replaceWrappedMachineKey(keyPath, legacyKey, passphrase);
+    removeLegacyMachineKeyIfSafe(tenantRoot);
+  }
+  return {
+    keyPath,
+    migrated: true,
+    alreadyWrapped: false
+  };
+}
 function loadTreeseedRemoteAuthState(tenantRoot) {
   const key = loadMachineKey(tenantRoot);
   const payload = loadRemoteAuthPayload(tenantRoot);
@@ -555,6 +1041,24 @@ function writeTreeseedMachineConfig(tenantRoot, config) {
   ensureParent(configPath);
   writeFileSync(configPath, stringifyYaml(config), "utf8");
 }
+function updateTreeseedDeployConfigFeatureToggles(tenantRoot, toggles) {
+  const configPath = resolve(tenantRoot, "treeseed.site.yaml");
+  const current = parseYaml(readFileSync(configPath, "utf8")) ?? {};
+  const next = { ...current };
+  if ("smtp" in toggles) {
+    next.smtp = {
+      ...current.smtp ?? {},
+      enabled: toggles.smtp === true
+    };
+  }
+  if ("turnstile" in toggles) {
+    next.turnstile = {
+      ...current.turnstile ?? {},
+      enabled: toggles.turnstile === true
+    };
+  }
+  writeFileSync(configPath, stringifyYaml(next), "utf8");
+}
 function resolveTreeseedRemoteConfig(startRoot = process.cwd(), env = process.env) {
   const machineConfigPath = findNearestTreeseedMachineConfig(startRoot);
   const tenantRoot = machineConfigPath ? resolve(dirname(dirname(machineConfigPath)), "..") : startRoot;
@@ -570,7 +1074,7 @@ function resolveTreeseedRemoteConfig(startRoot = process.cwd(), env = process.en
     tenantConfig: void 0
   });
   const settings = normalizeRemoteSettings(machineConfig.settings?.remote);
-  const deployBaseUrl = deployConfig?.services?.api?.environments?.prod?.baseUrl ?? deployConfig?.services?.api?.publicBaseUrl ?? null;
+  const deployBaseUrl = env[TREESEED_API_BASE_URL_ENV] ?? deployConfig?.services?.api?.environments?.prod?.baseUrl ?? deployConfig?.services?.api?.publicBaseUrl ?? null;
   if (deployBaseUrl) {
     const officialHost = settings.hosts.find((entry) => entry.id === "official");
     if (officialHost) {
@@ -623,7 +1127,7 @@ function resolveTreeseedTemplateCatalogCachePath(startRoot = process.cwd()) {
 }
 function ensureTreeseedGitignoreEntries(tenantRoot) {
   const gitignorePath = resolve(tenantRoot, ".gitignore");
-  const requiredEntries = [".env.local", ".dev.vars", ".treeseed/"];
+  const requiredEntries = [".treeseed/"];
   const current = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf8") : "";
   const lines = current.split(/\r?\n/);
   let changed = false;
@@ -653,11 +1157,9 @@ function applyTreeseedSafeRepairs(tenantRoot) {
   const actions = [];
   ensureTreeseedGitignoreEntries(tenantRoot);
   actions.push({ id: "gitignore", detail: "Ensured Treeseed gitignore entries are present." });
-  const envLocalPath = resolve(tenantRoot, ".env.local");
-  const envLocalExamplePath = resolve(tenantRoot, ".env.local.example");
-  if (!existsSync(envLocalPath) && existsSync(envLocalExamplePath)) {
-    copyFileSync(envLocalExamplePath, envLocalPath);
-    actions.push({ id: "env-local", detail: "Created .env.local from .env.local.example." });
+  const deprecatedFiles = warnDeprecatedTreeseedLocalEnvFiles(tenantRoot);
+  if (deprecatedFiles.length > 0) {
+    actions.push({ id: "deprecated-local-env", detail: "Detected deprecated .env.local/.dev.vars files that Treeseed now ignores." });
   }
   const deployConfig = loadTenantDeployConfig(tenantRoot);
   const { configPath } = getTreeseedMachineConfigPaths(tenantRoot);
@@ -670,12 +1172,14 @@ function applyTreeseedSafeRepairs(tenantRoot) {
     writeTreeseedMachineConfig(tenantRoot, machineConfig2);
     actions.push({ id: "machine-config", detail: "Created the default Treeseed machine config." });
   }
-  resolveTreeseedMachineEnvironmentValues(tenantRoot, "local");
-  actions.push({ id: "machine-key", detail: "Ensured the Treeseed machine key exists." });
+  const keyStatus = inspectTreeseedKeyAgentStatus(tenantRoot);
+  if (!keyStatus.wrappedKeyPresent && !keyStatus.migrationRequired) {
+    actions.push({ id: "machine-key", detail: "Treeseed will create a wrapped machine key the first time the secret session is unlocked." });
+  } else if (keyStatus.migrationRequired) {
+    actions.push({ id: "machine-key-migration", detail: "Detected a legacy plaintext machine key that must be wrapped on the next unlock." });
+  }
   const machineConfig = loadTreeseedMachineConfig(tenantRoot);
   writeTreeseedMachineConfig(tenantRoot, machineConfig);
-  writeTreeseedLocalEnvironmentFiles(tenantRoot);
-  actions.push({ id: "local-env", detail: "Regenerated .env.local and .dev.vars from the current machine config." });
   for (const scope of TREESEED_ENVIRONMENT_SCOPES) {
     const target = createPersistentDeployTarget(scope);
     const state = loadDeployState(tenantRoot, deployConfig, { target });
@@ -695,6 +1199,70 @@ function decryptMachineEnvironmentBucket(tenantRoot, config, key, bucket) {
   }
   return values;
 }
+function readMachineBucketEntryValue(tenantRoot, key, bucket, entry) {
+  if (entry.sensitivity === "secret") {
+    const payload = bucket?.secrets?.[entry.id];
+    return typeof payload === "string" && payload.length > 0 ? decryptValueWithMachineKey(tenantRoot, payload, key) : "";
+  }
+  return typeof bucket?.values?.[entry.id] === "string" ? bucket.values[entry.id] : "";
+}
+function writeMachineBucketEntryValue(target, entry, value, key) {
+  if (entry.sensitivity === "secret") {
+    delete target.values[entry.id];
+    if (value) {
+      target.secrets[entry.id] = encryptValue(value, key);
+    } else {
+      delete target.secrets[entry.id];
+    }
+    return;
+  }
+  delete target.secrets[entry.id];
+  if (value) {
+    target.values[entry.id] = value;
+  } else {
+    delete target.values[entry.id];
+  }
+}
+function migrateLegacyScopedSharedEntries(tenantRoot, config, registryEntries, key) {
+  const notices = [];
+  let changed = false;
+  for (const entry of registryEntries) {
+    if (entry.storage !== "shared") {
+      continue;
+    }
+    const sharedValue = readMachineBucketEntryValue(tenantRoot, key, config.shared, entry);
+    if (sharedValue.length > 0) {
+      continue;
+    }
+    const scopedValues = TREESEED_ENVIRONMENT_SCOPES.map((scope) => ({
+      scope,
+      value: readMachineBucketEntryValue(tenantRoot, key, config.environments?.[scope], entry)
+    })).filter((candidate) => candidate.value.length > 0);
+    if (scopedValues.length === 0) {
+      continue;
+    }
+    const promotedFrom = (scopedValues.find((candidate) => candidate.scope === "staging") ?? scopedValues.find((candidate) => candidate.scope === "prod") ?? scopedValues[0]).scope;
+    const promotedValue = scopedValues.find((candidate) => candidate.scope === promotedFrom)?.value ?? "";
+    const hadConflicts = new Set(scopedValues.map((candidate) => candidate.value)).size > 1;
+    writeMachineBucketEntryValue(config.shared, entry, promotedValue, key);
+    for (const candidateScope of TREESEED_ENVIRONMENT_SCOPES) {
+      delete config.environments[candidateScope].values[entry.id];
+      delete config.environments[candidateScope].secrets[entry.id];
+    }
+    notices.push({
+      entryId: entry.id,
+      label: entry.label,
+      promotedFrom,
+      consolidatedScopes: scopedValues.map((candidate) => candidate.scope),
+      hadConflicts
+    });
+    changed = true;
+  }
+  if (changed) {
+    writeTreeseedMachineConfig(tenantRoot, config);
+  }
+  return notices;
+}
 function resolveEntryValueFromBuckets(entry, entryId, scope, bucketValuesByScope) {
   if (!entry) {
     return bucketValuesByScope[scope]?.[entryId] ?? bucketValuesByScope.shared?.[entryId] ?? "";
@@ -780,14 +1348,28 @@ function collectTreeseedEnvironmentContext(tenantRoot) {
   });
 }
 function collectTreeseedConfigSeedValues(tenantRoot, scope, env = process.env) {
+  warnDeprecatedTreeseedLocalEnvFiles(tenantRoot);
+  let machineValues = {};
+  try {
+    machineValues = resolveTreeseedMachineEnvironmentValues(tenantRoot, scope);
+  } catch (error) {
+    if (!(error instanceof TreeseedKeyAgentError)) {
+      throw error;
+    }
+  }
+  const normalizedEnv = { ...env };
+  for (const [legacyKey, canonicalKey] of Object.entries(LEGACY_ENVIRONMENT_ALIASES)) {
+    if ((!normalizedEnv[canonicalKey] || String(normalizedEnv[canonicalKey]).length === 0) && normalizedEnv[legacyKey]) {
+      normalizedEnv[canonicalKey] = normalizedEnv[legacyKey];
+    }
+  }
   return {
-    ...readEnvFileIfPresent(resolve(tenantRoot, ".env.local")),
-    ...readEnvFileIfPresent(resolve(tenantRoot, ".dev.vars")),
-    ...Object.fromEntries(Object.entries(env).map(([key, value]) => [key, value ?? void 0])),
-    ...resolveTreeseedMachineEnvironmentValues(tenantRoot, scope)
+    ...machineValues,
+    ...Object.fromEntries(Object.entries(normalizedEnv).map(([key, value]) => [key, value ?? void 0]))
   };
 }
 function collectTreeseedConfigSeedValueSources(tenantRoot, scope, env = process.env) {
+  warnDeprecatedTreeseedLocalEnvFiles(tenantRoot);
   const values = {};
   const sources = {};
   const merge = (source, entries) => {
@@ -799,12 +1381,29 @@ function collectTreeseedConfigSeedValueSources(tenantRoot, scope, env = process.
       sources[key] = source;
     }
   };
-  merge(".env.local", readEnvFileIfPresent(resolve(tenantRoot, ".env.local")));
-  merge(".dev.vars", readEnvFileIfPresent(resolve(tenantRoot, ".dev.vars")));
+  try {
+    merge("machine-config", resolveTreeseedMachineEnvironmentValues(tenantRoot, scope));
+  } catch (error) {
+    if (!(error instanceof TreeseedKeyAgentError)) {
+      throw error;
+    }
+  }
   merge("process.env", Object.fromEntries(Object.entries(env).map(([key, value]) => [key, value ?? void 0])));
-  merge("machine-config", resolveTreeseedMachineEnvironmentValues(tenantRoot, scope));
   return { values, sources };
 }
+function resolveTreeseedLaunchEnvironment({
+  tenantRoot,
+  scope,
+  baseEnv = process.env,
+  overrides = {}
+}) {
+  warnDeprecatedTreeseedLocalEnvFiles(tenantRoot);
+  return {
+    ...baseEnv,
+    ...resolveTreeseedMachineEnvironmentValues(tenantRoot, scope),
+    ...overrides
+  };
+}
 function formatTreeseedConfigEnvironmentReport({ tenantRoot, scope, env = process.env, revealSecrets = false }) {
   const registry = collectTreeseedEnvironmentContext(tenantRoot);
   const { values, sources } = collectTreeseedConfigSeedValueSources(tenantRoot, scope, env);
@@ -820,7 +1419,14 @@ function formatTreeseedConfigEnvironmentReport({ tenantRoot, scope, env = proces
   return lines.join("\n");
 }
 function applyTreeseedEnvironmentToProcess({ tenantRoot, scope, override = false }) {
-  const resolvedValues = resolveTreeseedMachineEnvironmentValues(tenantRoot, scope);
+  let resolvedValues = {};
+  try {
+    resolvedValues = resolveTreeseedLaunchEnvironment({ tenantRoot, scope, baseEnv: {} });
+  } catch (error) {
+    if (!(error instanceof TreeseedKeyAgentError)) {
+      throw error;
+    }
+  }
   for (const [key, value] of Object.entries(resolvedValues)) {
     const currentValue = process.env[key] ?? "";
     const shouldReplacePlaceholder = key === "CLOUDFLARE_ACCOUNT_ID" && currentValue === CLOUDFLARE_ACCOUNT_ID_PLACEHOLDER;
@@ -832,11 +1438,7 @@ function applyTreeseedEnvironmentToProcess({ tenantRoot, scope, override = false
 }
 function validateTreeseedCommandEnvironment({ tenantRoot, scope, purpose }) {
   const registry = collectTreeseedEnvironmentContext(tenantRoot);
-  const machineValues = resolveTreeseedMachineEnvironmentValues(tenantRoot, scope);
-  const values = {
-    ...machineValues,
-    ...Object.fromEntries(Object.entries(process.env).map(([key, value]) => [key, value ?? void 0]))
-  };
+  const values = resolveTreeseedLaunchEnvironment({ tenantRoot, scope });
   const validation = validateTreeseedEnvironmentValues({
     values,
     scope,
@@ -868,29 +1470,6 @@ function assertTreeseedCommandEnvironment({ tenantRoot, scope, purpose }) {
   error.details = report.validation;
   throw error;
 }
-function renderEnvEntries(entries, values) {
-  return entries.map((entry) => [entry.id, values[entry.id]]).filter(([, value]) => typeof value === "string" && value.length > 0).map(([key, value]) => `${key}=${value}`).join("\n");
-}
-function writeTreeseedLocalEnvironmentFiles(tenantRoot) {
-  const registry = collectTreeseedEnvironmentContext(tenantRoot);
-  const scope = "local";
-  const values = resolveTreeseedMachineEnvironmentValues(tenantRoot, scope);
-  const orderedEntries = listRelevantTreeseedConfigEntries(registry, scope);
-  const envEntries = orderedEntries.filter(
-    (entry) => entry.scopes.includes(scope) && entry.targets.includes("local-file")
-  );
-  const devVarsEntries = orderedEntries.filter(
-    (entry) => entry.scopes.includes(scope) && entry.targets.includes("wrangler-dev-vars")
-  );
-  writeFileSync(resolve(tenantRoot, ".env.local"), `${renderEnvEntries(envEntries, values)}
-`, "utf8");
-  writeFileSync(resolve(tenantRoot, ".dev.vars"), `${renderEnvEntries(devVarsEntries, values)}
-`, "utf8");
-  return {
-    envLocalPath: resolve(tenantRoot, ".env.local"),
-    devVarsPath: resolve(tenantRoot, ".dev.vars")
-  };
-}
 function runGh(args, { cwd, dryRun = false, input } = {}) {
   if (dryRun) {
     return { status: 0, stdout: "", stderr: "" };
@@ -933,15 +1512,18 @@ function checkCommand(command, args, { cwd, env } = {}) {
     cwd,
     stdio: "pipe",
     encoding: "utf8",
-    env: { ...process.env, ...env ?? {} }
+    env: { ...process.env, ...env ?? {} },
+    timeout: CLI_CHECK_TIMEOUT_MS
   });
+  const timedOut = result.error && "code" in result.error && result.error.code === "ETIMEDOUT";
+  const detail = timedOut ? `Command timed out after ${CLI_CHECK_TIMEOUT_MS}ms: ${command} ${args.join(" ")}` : `${result.stderr ?? ""}
+${result.stdout ?? ""}`.trim();
   return {
     ok: result.status === 0,
     status: result.status ?? 1,
     stdout: result.stdout?.trim() ?? "",
     stderr: result.stderr?.trim() ?? "",
-    detail: `${result.stderr ?? ""}
-${result.stdout ?? ""}`.trim()
+    detail
   };
 }
 function toolStatus(name, available, detail, extra = {}) {
@@ -961,6 +1543,18 @@ function ensureTreeseedActVerificationTooling({ tenantRoot = process.cwd(), inst
     attemptedInstall: false,
     installedDuringConfig: false
   });
+  const wranglerCheck = checkCommand(process.execPath, [resolveWranglerBin(), "--version"], { cwd: tenantRoot, env });
+  const wranglerCli = toolStatus(
+    "wranglerCli",
+    wranglerCheck.ok,
+    wranglerCheck.ok ? wranglerCheck.stdout.split("\n")[0] ?? "Wrangler CLI detected." : wranglerCheck.detail || "Wrangler CLI is unavailable."
+  );
+  const railwayCheck = checkCommand("railway", ["--version"], { cwd: tenantRoot, env });
+  const railwayCli = toolStatus(
+    "railwayCli",
+    railwayCheck.ok,
+    railwayCheck.ok ? railwayCheck.stdout.split("\n")[0] ?? "Railway CLI detected." : railwayCheck.detail || "Railway CLI is unavailable."
+  );
   if (githubCli.available) {
     const check = checkCommand("gh", ["act", "--version"], { cwd: tenantRoot, env });
     if (check.ok) {
@@ -1005,10 +1599,18 @@ function ensureTreeseedActVerificationTooling({ tenantRoot = process.cwd(), inst
   if (!dockerDaemon.available) {
     remediation.push("Start Docker Desktop or another local Docker daemon, then rerun `treeseed config`.");
   }
+  if (!wranglerCli.available) {
+    remediation.push("Install Wrangler or ensure the packaged Wrangler dependency is runnable, then rerun `treeseed config`.");
+  }
+  if (!railwayCli.available) {
+    remediation.push("Install Railway CLI if you plan to manage Railway services from this machine.");
+  }
   return {
     githubCli,
     ghActExtension,
     dockerDaemon,
+    wranglerCli,
+    railwayCli,
     actVerificationReady: githubCli.available && ghActExtension.available && dockerDaemon.available,
     remediation
   };
@@ -1038,7 +1640,8 @@ function checkGitHubConnection({ tenantRoot, env }) {
     cwd: tenantRoot,
     stdio: "pipe",
     encoding: "utf8",
-    env: { ...process.env, ...env }
+    env: { ...process.env, ...env },
+    timeout: CLI_CHECK_TIMEOUT_MS
   });
   if (result.status !== 0) {
     return providerConnectionResult("github", false, formatCheckOutput(result) || "GitHub API check failed.");
@@ -1059,7 +1662,8 @@ function checkCloudflareConnection({ tenantRoot, env }) {
       cwd: tenantRoot,
       stdio: "pipe",
       encoding: "utf8",
-      env: { ...process.env, ...env }
+      env: { ...process.env, ...env },
+      timeout: CLI_CHECK_TIMEOUT_MS
     });
     if (result.status !== 0) {
       return providerConnectionResult("cloudflare", false, formatCheckOutput(result) || "Cloudflare Wrangler check failed.");
@@ -1080,7 +1684,8 @@ function checkRailwayConnection({ tenantRoot, env }) {
     cwd: tenantRoot,
     stdio: "pipe",
     encoding: "utf8",
-    env: { ...process.env, ...env }
+    env: { ...process.env, ...env },
+    timeout: CLI_CHECK_TIMEOUT_MS
   });
   if (result.status !== 0) {
     return providerConnectionResult("railway", false, formatCheckOutput(result) || "Railway CLI check failed.");
@@ -1104,7 +1709,8 @@ function checkTreeseedProviderConnections({ tenantRoot, scope = "prod", env = pr
   return {
     scope,
     ok: checks.every((check) => check.ready || check.skipped),
-    checks
+    checks,
+    issues: checks.filter((check) => !check.ready && !check.skipped).map((check) => check.detail)
   };
 }
 function formatTreeseedProviderConnectionReport(report) {
@@ -1184,14 +1790,14 @@ function syncTreeseedRailwayEnvironment({ tenantRoot, scope = "prod", dryRun = f
   const registry = collectTreeseedEnvironmentContext(tenantRoot);
   const railwaySecretNames = registry.entries.filter((entry) => entry.scopes.includes(scope) && entry.targets.includes("railway-secret")).map((entry) => entry.id).filter((key) => typeof values[key] === "string" && values[key].length > 0);
   const railwayVariableNames = registry.entries.filter((entry) => entry.scopes.includes(scope) && entry.targets.includes("railway-var")).map((entry) => entry.id).filter((key) => typeof values[key] === "string" && values[key].length > 0);
-  const services = ["api", "agents", "manager", "worker", "runner", "workdayStart", "workdayReport"].map((serviceKey) => {
+  const services = ["api", "manager", "worker", "workdayStart", "workdayReport"].map((serviceKey) => {
     const service = deployConfig.services?.[serviceKey];
     if (!service || service.enabled === false || (service.provider ?? "railway") !== "railway") {
       return null;
     }
     const environment = service.environments?.[scope];
-    const fallbackServiceName = serviceKey === "api" ? config.settings.services.railway.apiServiceName : serviceKey === "agents" ? config.settings.services.railway.agentsServiceName : "";
-    const defaultRootDir = ["api", "manager", "worker", "runner", "workdayStart", "workdayReport"].includes(serviceKey) ? "." : "packages/core";
+    const fallbackServiceName = serviceKey === "api" ? config.settings.services.railway.apiServiceName : "";
+    const defaultRootDir = ["api", "manager", "worker", "workdayStart", "workdayReport"].includes(serviceKey) ? "." : "packages/core";
     return {
       service: serviceKey,
       projectName: service.railway?.projectName ?? config.settings.services.railway.projectName,
@@ -1241,39 +1847,97 @@ function initializeTreeseedPersistentEnvironment({ tenantRoot, scope = "prod", d
   };
 }
 function summarizePersistentReadiness(tenantRoot, scope, validation, connectionChecks) {
+  const validationProblems = [...validation.missing, ...validation.invalid];
+  const validationBlockers = validationProblems.map((problem) => problem.message);
+  const connectionReady = connectionChecks.every((check) => check.ready || check.skipped);
+  const connectionIssues = connectionChecks.filter((check) => !check.ready && !check.skipped).map((check) => `${check.provider}: ${check.detail}`);
+  const connectionWarnings = connectionChecks.filter((check) => check.skipped).map((check) => `${check.provider}: ${check.detail}`);
   if (scope === "local") {
     return {
       configured: validation.ok,
       provisioned: true,
-      deployable: validation.ok,
+      deployable: validation.ok && connectionReady,
+      phase: validation.ok ? "code_ready" : "config_incomplete",
+      blockers: [
+        ...validationBlockers,
+        ...connectionIssues
+      ],
+      warnings: connectionWarnings,
       checks: {
         validation: validation.ok,
-        connections: connectionChecks.every((check) => check.ready || check.skipped)
+        connections: connectionReady
+      }
+    };
+  }
+  if (!validation.ok) {
+    return {
+      configured: false,
+      provisioned: false,
+      deployable: false,
+      phase: "config_incomplete",
+      blockers: [
+        ...validationBlockers,
+        ...connectionIssues
+      ],
+      warnings: connectionWarnings,
+      checks: {
+        validation: false,
+        connections: connectionReady,
+        cloudflare: null,
+        railway: false
       }
     };
   }
   const cloudflare = verifyProvisionedCloudflareResources(tenantRoot, { scope });
   let railwayReady = true;
+  let railwayIssue = null;
   try {
     validateRailwayDeployPrerequisites(tenantRoot, scope);
-  } catch {
+  } catch (error) {
     railwayReady = false;
+    railwayIssue = error instanceof Error ? error.message : String(error);
   }
   const configured = validation.ok;
   const provisioned = cloudflare.ok && railwayReady;
-  const deployable = configured && provisioned && connectionChecks.every((check) => check.ready || check.skipped);
+  const deployable = configured && provisioned && connectionReady;
+  const blockers = [
+    ...connectionIssues,
+    ...railwayIssue ? [railwayIssue] : []
+  ];
+  if (!cloudflare.ok) {
+    blockers.push("Cloudflare foundational resources have not been fully provisioned yet.");
+  }
   return {
     configured,
     provisioned,
     deployable,
+    phase: provisioned ? "provisioned" : "config_complete",
+    blockers,
+    warnings: connectionWarnings,
     checks: {
       validation: validation.ok,
-      connections: connectionChecks.every((check) => check.ready || check.skipped),
+      connections: connectionReady,
       cloudflare: cloudflare.checks,
       railway: railwayReady
     }
   };
 }
+function formatTreeseedConfigValidationFailure(validations, scopes) {
+  const lines = ["Treeseed config validation failed."];
+  for (const scope of scopes) {
+    const validation = validations[scope];
+    if (!validation || validation.ok) {
+      continue;
+    }
+    lines.push("");
+    lines.push(`${scope}:`);
+    for (const problem of [...validation.missing, ...validation.invalid]) {
+      const targets = problem.entry.targets.length > 0 ? ` Targets: ${problem.entry.targets.join(", ")}.` : "";
+      lines.push(`- ${problem.id}: ${problem.message}${targets}`);
+    }
+  }
+  return lines.join("\n");
+}
 function colorize(value, code) {
   return `\x1B[${code}m${value}\x1B[0m`;
 }
@@ -1284,31 +1948,40 @@ function formatConfigSectionTitle(label) {
 function hasConfigValue(values, key) {
   return typeof values[key] === "string" && values[key].trim().length > 0;
 }
-function createConfigAuthStatus(values) {
-  const ghReady = hasConfigValue(values, "GH_TOKEN");
+function createConfigReadiness(values, validation) {
+  const invalidIds = /* @__PURE__ */ new Set([
+    ...(validation?.invalid ?? []).map((problem) => problem.id)
+  ]);
+  const validConfigValue = (key) => hasConfigValue(values, key) && !invalidIds.has(key);
+  const cloudflareReady = validConfigValue("CLOUDFLARE_API_TOKEN");
+  const railwayReady = validConfigValue("RAILWAY_API_TOKEN");
+  const localDevelopmentIssues = [
+    ...validation?.missing ?? [],
+    ...validation?.invalid ?? []
+  ].filter((problem) => problem.entry.group === "local-development");
   return {
-    gh: {
-      authenticated: ghReady
+    github: {
+      configured: validConfigValue("GH_TOKEN")
     },
-    wrangler: {
-      authenticated: hasConfigValue(values, "CLOUDFLARE_API_TOKEN")
+    cloudflare: {
+      configured: cloudflareReady
     },
     railway: {
-      authenticated: hasConfigValue(values, "RAILWAY_API_TOKEN")
+      configured: railwayReady
     },
-    copilot: {
-      configured: ghReady
+    localDevelopment: {
+      configured: localDevelopmentIssues.length === 0
     }
   };
 }
-const CONFIG_GROUP_ORDER = ["auth", "cloudflare", "local-development", "forms", "smtp"];
+const CONFIG_GROUP_ORDER = ["auth", "github", "cloudflare", "railway", "local-development", "forms", "smtp"];
 function configGroupRank(group) {
   const index = CONFIG_GROUP_ORDER.indexOf(group);
   return index === -1 ? CONFIG_GROUP_ORDER.length : index;
 }
 function listRelevantTreeseedConfigEntries(registry, scope) {
   return registry.entries.filter(
-    (entry) => entry.scopes.includes(scope) && (!entry.isRelevant || entry.isRelevant(registry.context, scope, "config"))
+    (entry) => entry.scopes.includes(scope) && (!entry.isRelevant || entry.isRelevant(registry.context, scope, "config") || Boolean(entry.onboardingFeature))
   ).sort((left, right) => {
     const leftRequired = isTreeseedEnvironmentEntryRequired(left, registry.context, scope, "config");
     const rightRequired = isTreeseedEnvironmentEntryRequired(right, registry.context, scope, "config");
@@ -1325,22 +1998,55 @@ function listRelevantTreeseedConfigEntries(registry, scope) {
   });
 }
 function buildConfigEntrySnapshot(scope, entry, currentValue, suggestedValue) {
+  const currentValueValid = (() => {
+    if (!currentValue || !entry.validation) {
+      return currentValue.length > 0;
+    }
+    switch (entry.validation.kind) {
+      case "string":
+      case "nonempty":
+        return currentValue.trim().length > 0 && (typeof entry.validation.minLength !== "number" || currentValue.trim().length >= entry.validation.minLength);
+      case "boolean":
+        return /^(true|false|1|0)$/i.test(currentValue);
+      case "number":
+        return Number.isFinite(Number(currentValue));
+      case "url":
+        try {
+          new URL(currentValue);
+          return true;
+        } catch {
+          return false;
+        }
+      case "email":
+        return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(currentValue);
+      case "enum":
+        return entry.validation.values.includes(currentValue);
+      default:
+        return true;
+    }
+  })();
+  const allowSuggestedDefault = !(entry.sensitivity === "secret" && entry.requirement !== "optional");
+  const effectiveValue = currentValueValid ? currentValue || (allowSuggestedDefault ? suggestedValue : "") || "" : (allowSuggestedDefault ? suggestedValue : "") || currentValue || "";
   return {
     id: entry.id,
     label: entry.label,
     group: entry.group,
+    cluster: entry.cluster ?? `${entry.group}:${entry.id}`,
+    startupProfile: entry.startupProfile ?? "advanced",
+    requirement: entry.requirement,
     description: entry.description,
     howToGet: entry.howToGet,
     sensitivity: entry.sensitivity,
     targets: [...entry.targets],
     purposes: [...entry.purposes],
     storage: entry.storage ?? "scoped",
+    validation: entry.validation,
     scope,
     sharedScopes: entry.storage === "shared" ? [...entry.scopes] : [scope],
     required: false,
     currentValue,
     suggestedValue,
-    effectiveValue: currentValue || suggestedValue || ""
+    effectiveValue
   };
 }
 function collectTreeseedConfigContext({
@@ -1364,9 +2070,6 @@ function collectTreeseedConfigContext({
       values: valuesByScope[scope]
     })])
   );
-  const authStatusByScope = Object.fromEntries(
-    scopes.map((scope) => [scope, createConfigAuthStatus(valuesByScope[scope])])
-  );
   const validationByScope = Object.fromEntries(
     scopes.map((scope) => [scope, validateTreeseedEnvironmentValues({
       values: {
@@ -1380,6 +2083,9 @@ function collectTreeseedConfigContext({
       plugins: registry.context.plugins
     })])
   );
+  const configReadinessByScope = Object.fromEntries(
+    scopes.map((scope) => [scope, createConfigReadiness(valuesByScope[scope], validationByScope[scope])])
+  );
   const entriesByScope = Object.fromEntries(
     scopes.map((scope) => [scope, listRelevantTreeseedConfigEntries(registry, scope).map((entry) => ({
       ...buildConfigEntrySnapshot(
@@ -1404,18 +2110,21 @@ function collectTreeseedConfigContext({
     entriesByScope,
     valuesByScope,
     suggestedValuesByScope,
-    authStatusByScope,
+    configReadinessByScope,
     validationByScope,
+    sharedStorageMigrations: [],
     registry
   };
 }
 function applyTreeseedConfigValues({
   tenantRoot,
   updates,
-  writeLocalFiles = true,
   applyLocalEnvironment = true
 }) {
   const registry = collectTreeseedEnvironmentContext(tenantRoot);
+  const key = loadMachineKey(tenantRoot);
+  const machineConfig = loadTreeseedMachineConfig(tenantRoot);
+  const sharedStorageMigrations = migrateLegacyScopedSharedEntries(tenantRoot, machineConfig, registry.entries, key);
   const entryById = new Map(registry.entries.map((entry) => [entry.id, entry]));
   const applied = [];
   for (const update of updates) {
@@ -1434,13 +2143,12 @@ function applyTreeseedConfigValues({
       cleared: update.value.length === 0
     });
   }
-  const envFiles = writeLocalFiles ? writeTreeseedLocalEnvironmentFiles(tenantRoot) : null;
   if (applyLocalEnvironment) {
     applyTreeseedEnvironmentToProcess({ tenantRoot, scope: "local", override: true });
   }
   return {
     updated: applied,
-    envFiles
+    sharedStorageMigrations
   };
 }
 function finalizeTreeseedConfig({
@@ -1449,7 +2157,8 @@ function finalizeTreeseedConfig({
   sync = "all",
   env = process.env,
   checkConnections = true,
-  initializePersistent = true
+  initializePersistent = true,
+  onProgress
 }) {
   const registry = collectTreeseedEnvironmentContext(tenantRoot);
   const summary = {
@@ -1460,6 +2169,12 @@ function finalizeTreeseedConfig({
     validationByScope: {},
     readinessByScope: {}
   };
+  const progress = (message) => {
+    if (typeof onProgress === "function") {
+      onProgress(message);
+    }
+  };
+  progress(`Validating configuration for ${scopes.join(", ")}...`);
   for (const scope of scopes) {
     const validation = validateTreeseedEnvironmentValues({
       values: resolveTreeseedMachineEnvironmentValues(tenantRoot, scope),
@@ -1470,22 +2185,31 @@ function finalizeTreeseedConfig({
       plugins: registry.context.plugins
     });
     summary.validationByScope[scope] = validation;
-    if (!validation.ok) {
-      const details = [...validation.missing, ...validation.invalid].map((problem) => `- ${problem.message}`).join("\n");
-      throw new Error(`Treeseed config validation failed for ${scope}:
-${details}`);
-    }
     if (checkConnections) {
+      progress(`Checking provider connectivity for ${scope}...`);
       summary.connectionChecks.push(checkTreeseedProviderConnections({ tenantRoot, scope, env }));
     }
   }
-  writeTreeseedLocalEnvironmentFiles(tenantRoot);
+  for (const scope of scopes) {
+    summary.readinessByScope[scope] = summarizePersistentReadiness(
+      tenantRoot,
+      scope,
+      summary.validationByScope[scope],
+      summary.connectionChecks.find((report) => report.scope === scope)?.checks ?? []
+    );
+  }
+  const invalidScopes = scopes.filter((scope) => summary.validationByScope[scope]?.ok !== true);
+  if (invalidScopes.length > 0) {
+    throw new Error(formatTreeseedConfigValidationFailure(summary.validationByScope, scopes));
+  }
+  progress("Syncing managed service settings from treeseed.site.yaml...");
   syncManagedServiceSettingsFromDeployConfig(tenantRoot);
   if (initializePersistent) {
     for (const scope of scopes) {
       if (scope === "local") {
         continue;
       }
+      progress(`Initializing persistent ${scope} environment resources...`);
       applyTreeseedEnvironmentToProcess({ tenantRoot, scope, override: true });
       const initialized = initializeTreeseedPersistentEnvironment({ tenantRoot, scope });
       summary.initialized.push({
@@ -1493,16 +2217,18 @@ ${details}`);
         secrets: initialized.secrets.length,
         target: initialized.summary.target
       });
-      markManagedServicesInitialized(tenantRoot, { scope });
     }
   }
   if (sync === "github" || sync === "all") {
+    progress(`Syncing GitHub environment for ${scopes.at(-1) ?? "prod"}...`);
     summary.synced.github = syncTreeseedGitHubEnvironment({ tenantRoot, scope: scopes.at(-1) ?? "prod" });
   }
   if (sync === "cloudflare" || sync === "all") {
+    progress(`Syncing Cloudflare environment for ${scopes.at(-1) ?? "prod"}...`);
     summary.synced.cloudflare = syncTreeseedCloudflareEnvironment({ tenantRoot, scope: scopes.at(-1) ?? "prod" });
   }
   if (sync === "railway" || sync === "all") {
+    progress(`Syncing Railway environment for ${scopes.at(-1) ?? "prod"}...`);
     summary.synced.railway = syncTreeseedRailwayEnvironment({ tenantRoot, scope: scopes.at(-1) ?? "prod" });
   }
   for (const scope of scopes) {
@@ -1512,11 +2238,6 @@ ${details}`);
       summary.validationByScope[scope],
       summary.connectionChecks.find((report) => report.scope === scope)?.checks ?? []
     );
-    if (scope !== "local" && summary.readinessByScope[scope].deployable !== true) {
-      throw new Error(
-        `Treeseed config readiness failed for ${scope}: configuration is not deployable.`
-      );
-    }
   }
   return summary;
 }
@@ -1548,7 +2269,9 @@ export {
   DEFAULT_TEMPLATE_CATALOG_URL,
   DEFAULT_TREESEED_API_BASE_URL,
   TREESEED_API_BASE_URL_ENV,
+  TREESEED_MACHINE_KEY_PASSPHRASE_ENV2 as TREESEED_MACHINE_KEY_PASSPHRASE_ENV,
   TREESEED_TEMPLATE_CATALOG_URL_ENV,
+  TreeseedKeyAgentError2 as TreeseedKeyAgentError,
   applyTreeseedConfigValues,
   applyTreeseedEnvironmentToProcess,
   applyTreeseedSafeRepairs,
@@ -1559,31 +2282,44 @@ export {
   collectTreeseedConfigSeedValues,
   collectTreeseedEnvironmentContext,
   collectTreeseedPrintEnvReport,
+  configGroupRank,
   createDefaultTreeseedMachineConfig,
   ensureTreeseedActVerificationTooling,
   ensureTreeseedGitignoreEntries,
+  ensureTreeseedSecretSessionForConfig,
   finalizeTreeseedConfig,
   formatTreeseedConfigEnvironmentReport,
   formatTreeseedProviderConnectionReport,
   getTreeseedMachineConfigPaths,
   getTreeseedRemoteAuthPaths,
   initializeTreeseedPersistentEnvironment,
+  inspectTreeseedKeyAgentStatus,
+  listDeprecatedTreeseedLocalEnvFiles,
   listRelevantTreeseedConfigEntries,
   loadTreeseedMachineConfig,
   loadTreeseedRemoteAuthState,
+  lockTreeseedSecretSession,
+  migrateTreeseedMachineKeyToWrapped,
+  resolveTreeseedLaunchEnvironment,
   resolveTreeseedMachineEnvironmentValues,
   resolveTreeseedRemoteConfig,
   resolveTreeseedRemoteSession,
   resolveTreeseedTemplateCatalogCachePath,
   resolveTreeseedTemplateCatalogEndpoint,
   rotateTreeseedMachineKey,
+  rotateTreeseedMachineKeyPassphrase,
   setTreeseedMachineEnvironmentValue,
   setTreeseedRemoteSession,
   syncTreeseedCloudflareEnvironment,
   syncTreeseedGitHubEnvironment,
   syncTreeseedRailwayEnvironment,
+  unlockTreeseedSecretSessionFromEnv,
+  unlockTreeseedSecretSessionInteractive,
+  unlockTreeseedSecretSessionWithPassphrase,
+  updateTreeseedDeployConfigFeatureToggles,
   validateTreeseedCommandEnvironment,
-  writeTreeseedLocalEnvironmentFiles,
+  warnDeprecatedTreeseedLocalEnvFiles,
+  withTreeseedKeyAgentAutopromptDisabled,
   writeTreeseedMachineConfig,
   writeTreeseedRemoteAuthState
 };