@runuai/host 0.9.148 → 0.9.149

package/lib/agent.ts

@@ -32,14 +32,24 @@ import { containerRuntimeStandardAssetsRoot } from "./container-runtime";
 import { getDecryptedForProject } from "./host-env";
 import { PreviewPortRuntimesSchema } from "./preview-ports";
 import { getHostTask } from "./runtime-state";
+import { activeSecretsProxy } from "./secrets-proxy/host";
+import { closeTaskUpTrustSteps, finishTaskUpTrustSteps, writeTaskUpTrustSteps } from "./secrets-proxy/task-trust";
 import { removeTaskIdentity, writeTaskIdentity } from "./ssh";
-import type { TaskDownInput, TaskLaunchInput } from "../src/protocol";
+import { taskGatewayHost } from "./mcp-gateway";
+import type { ProjectEnvMode } from "./task-environment/types";
+import { isProjectEnvSchemaObservation, type ProjectEnvSchemaObservation, type TaskDownInput, type TaskLaunchInput } from "../src/protocol";
 
 export type { TaskLaunchInput } from "../src/protocol";
 
 export interface TaskUpCredentials {
   /** Path to the task owner's private, ephemeral Git credential cache. */
   githubCredentialSocket?: string;
+  /** Fresh ADR-153 generation credential. The raw bytes are forwarded only
+   * over stdin and are never serialized into a task row, argv, or env. */
+  taskGateway?: {
+    generation: string;
+    secret: Uint8Array;
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -86,6 +96,13 @@ const TaskUpData = z.object({
   previewPorts: PreviewPortRuntimesSchema.optional(),
   /** Degraded start: uai-init failed twice; surfaced as a feed system note. */
   initWarning: z.string().optional(),
+  /** ADR-153: whether this start put the secrets proxy's CA, and its pins,
+   *  into the task. Absent from a task-up that predates them. */
+  secretsProxyTrust: z.enum(["installed", "failed", "skipped"]).optional(),
+  secretsProxyPins: z.enum(["installed", "failed", "skipped"]).optional(),
+  /** ADR-153 §4: each project's schema observation, as the runner stored it
+   *  before anything in the task started (a task machine reports its own). */
+  envSchemas: z.array(z.custom<ProjectEnvSchemaObservation>(isProjectEnvSchemaObservation)).optional(),
 });
 export type TaskUpResult = z.infer<typeof TaskUpData>;
 
@@ -303,46 +320,94 @@ export const agent = {
   async taskUp(
     input: TaskLaunchInput,
     credentials: TaskUpCredentials = {},
+    envMode: ProjectEnvMode = "baked",
   ): Promise<TaskUpResult> {
     const commandDbPath = createTaskUpCommandDb(input);
     // Materialize the creator's per-user SSH key for commit signing and the
     // explicit no-GitHub-connection transport fallback (ADR-029).
     const identityDir = writeTaskIdentity(input.task.id, input.task.ownerUserId);
-    // Per-(project, key) env values must NEVER enter task-up's host process
-    // environment. Besides ordinary app names, projects can declare names such
-    // as BASH_ENV, PATH, GIT_CONFIG_*, or UAI_*; exposing those before the host
-    // clone would let container-owned configuration influence host commands or
-    // read another credential boundary. Send one JSON object over stdin
-    // instead. task-up feeds it directly to Compose as an in-memory override,
-    // so values reach only the task container and are never written to disk.
-    // On a key collision the LEAD project (position 0) wins: iterate in
-    // descending position order so position-0 assignments apply last.
-    const projectEnv: Record<string, string> = {};
-    const orderedProjects = [...input.projects].sort(
-      (a, b) => b.position - a.position,
-    );
-    for (const project of orderedProjects) {
-      Object.assign(projectEnv, getDecryptedForProject(project.id));
-    }
-    const extraEnv: Record<string, string> = {};
-    if (identityDir) extraEnv.UAI_TASK_IDENTITY_DIR = identityDir;
-    // Only a non-secret socket path crosses into Bash. The token itself was
-    // seeded over stdin and never enters argv, env, project data, Compose, or
-    // the task container.
-    if (credentials.githubCredentialSocket) {
-      extraEnv.UAI_GITHUB_CREDENTIAL_SOCKET =
-        credentials.githubCredentialSocket;
-    }
     try {
-      return await runAgent(
-        "task-up.sh",
-        [input.task.id],
-        TaskUpData,
-        commandDbPath,
-        extraEnv,
-        JSON.stringify(projectEnv),
-      );
+      // Per-(project, key) env values must NEVER enter task-up's host process
+      // environment. Besides ordinary app names, projects can declare names such
+      // as BASH_ENV, PATH, GIT_CONFIG_*, or UAI_*; exposing those before the host
+      // clone would let container-owned configuration influence host commands or
+      // read another credential boundary. Send one JSON object over stdin
+      // instead. task-up feeds it directly to Compose as an in-memory override,
+      // so values reach only the task container and are never written to disk.
+      // On a key collision the LEAD project (position 0) wins: iterate in
+      // descending position order so position-0 assignments apply last.
+      const projectEnv: Record<string, string> = {};
+      if (envMode === "baked") {
+        const orderedProjects = [...input.projects].sort(
+          (a, b) => b.position - a.position,
+        );
+        for (const project of orderedProjects) {
+          Object.assign(projectEnv, getDecryptedForProject(project.id));
+        }
+      }
+      const extraEnv: Record<string, string> = {
+        UAI_PROJECT_ENV_MODE: envMode,
+      };
+      if (identityDir) extraEnv.UAI_TASK_IDENTITY_DIR = identityDir;
+      // Only a non-secret socket path crosses into Bash. The token itself was
+      // seeded over stdin and never enters argv, env, project data, Compose, or
+      // the task container.
+      if (credentials.githubCredentialSocket) {
+        extraEnv.UAI_GITHUB_CREDENTIAL_SOCKET =
+          credentials.githubCredentialSocket;
+      }
+      let stdinPayload: string;
+      if (envMode === "loader") {
+        const gateway = credentials.taskGateway;
+        if (!gateway || gateway.secret.byteLength !== 32) {
+          throw new Error(
+            "loader task is missing its gateway generation credential",
+          );
+        }
+        extraEnv.UAI_TASK_GATEWAY_GENERATION = gateway.generation;
+        extraEnv.UAI_TASK_GATEWAY_HOST = await taskGatewayHost();
+        // ADR-153: what task-up installs before anything runs in the task.
+        // Public material only; absent under the kill switch.
+        // The start holds the task's root writes until its result is
+        // recorded, so no older writer (a recovery, a re-pin) lands over
+        // them while uai-init runs.
+        const secretsProxy = activeSecretsProxy();
+        if (secretsProxy !== null) {
+          // task-up reports each step's outcome into it as it goes, so the
+          // task's readiness is exact even while uai-init already runs.
+          const stepsDir = await writeTaskUpTrustSteps(env.dataDir, input.task.id, secretsProxy.runtime);
+          if (stepsDir !== null) extraEnv.UAI_SECRETS_PROXY_DIR = stepsDir;
+        }
+        const secretCopy = Buffer.from(gateway.secret);
+        try {
+          stdinPayload = secretCopy.toString("base64");
+        } finally {
+          secretCopy.fill(0);
+        }
+      } else {
+        stdinPayload = JSON.stringify(projectEnv);
+      }
+      let result: TaskUpResult;
+      try {
+        result = await runAgent(
+          "task-up.sh",
+          [input.task.id],
+          TaskUpData,
+          commandDbPath,
+          extraEnv,
+          stdinPayload,
+        );
+      } catch (error) {
+        finishTaskUpTrustSteps(env.dataDir, input.task.id, null);
+        throw error;
+      }
+      // What this start actually installed. A start that did not get the CA
+      // in is retried by the trust watcher once the task runs.
+      finishTaskUpTrustSteps(env.dataDir, input.task.id, result);
+      if (result.secretsProxyTrust === "failed") activeSecretsProxy()?.runtime.requestTrustDelivery();
+      return result;
     } finally {
+      closeTaskUpTrustSteps(env.dataDir, input.task.id);
       removeCommandDb(commandDbPath);
       removeTaskIdentity(input.task.id);
     }

package/lib/agents/codex.ts

@@ -418,7 +418,15 @@ export class CodexSession implements AgentSession {
     for (const override of args.cliConfigOverrides ?? []) {
       codexArgs.push("-c", override);
     }
-    codexArgs.push("app-server");
+    // These are two independent features in Codex 0.157. Append after every
+    // user override so task env can never be frozen into an on-disk snapshot.
+    codexArgs.push(
+      "--disable",
+      "shell_snapshot",
+      "--disable",
+      "shell_snapshot_v2",
+      "app-server",
+    );
     // ADR-061: the CLI is owned by an in-container runner (durable across
     // host restarts); legacy pipes behind UAI_DURABLE_SESSIONS=0. Codex
     // re-handshakes per host process (initialize + thread/start live in this

package/lib/agents/cursor.ts

@@ -50,6 +50,13 @@ import type {
 
 const CURSOR_BIN = "/home/node/.local/bin/cursor-agent";
 
+// Cursor replays its captured sandbox environment immediately before it
+// evaluates each shell command. In loader tasks this restore hook is the last
+// step in that replay, so the command sees the current project environment
+// rather than Cursor's stale launch snapshot.
+export const CURSOR_SANDBOX_ENV_RESTORE =
+  ". /usr/local/share/uai/env-hook.sh; __uai_env_sync";
+
 // A curated slice of Cursor's ~32 models (full ids from `cursor-agent
 // --list-models`). `auto` lets Cursor pick; the rest are the frontier. The UI
 // also accepts any typed id (unverified round-trip). UPDATE as Cursor's lineup
@@ -233,8 +240,15 @@ export class CursorSession implements AgentSession {
     if (this.sessionId) argv.push("--resume", this.sessionId);
     return {
       argv: argv as [string, ...string[]],
+      projectEnvProfile: "task",
       user: "node",
-      env: { ...this.agentEnv, CURSOR_API_KEY: this.apiKey },
+      env: {
+        ...this.agentEnv,
+        CURSOR_API_KEY: this.apiKey,
+        ...(this.environment.descriptor.envMode === "loader"
+          ? { __CURSOR_SANDBOX_ENV_RESTORE: CURSOR_SANDBOX_ENV_RESTORE }
+          : {}),
+      },
       maxOutputBytes: AGENT_SESSION_OUTPUT_BUFFER_BYTES,
     };
   }

package/lib/agents/grok.ts

@@ -52,6 +52,7 @@ import type {
 } from "./types";
 
 const GROK_BIN = "/home/node/.grok/bin/grok";
+export const GROK_LOADER_LOGIN_ENV = "0";
 
 // `grok models` lists what the account can run. grok-4.5 is the current
 // default; UPDATE WHEN xAI CHANGES the lineup.
@@ -181,6 +182,7 @@ export class GrokSession implements AgentSession {
     if (this.sessionId) argv.push("-r", this.sessionId);
     return {
       argv: argv as [string, ...string[]],
+      projectEnvProfile: "task",
       user: "node",
       inheritEnv,
       env: {
@@ -193,6 +195,12 @@ export class GrokSession implements AgentSession {
         // the same reasoning as --permission-mode bypassPermissions above
         // (live 2026-09-08, first Grok agents with MCP servers).
         GROK_FOLDER_TRUST: "0",
+        // grok 1.0.5 otherwise captures a login-shell environment once and
+        // reuses that static state for LocalNonPersistent commands. Loader
+        // tasks refresh per command, so disable that stale snapshot path.
+        ...(this.environment.descriptor.envMode === "loader"
+          ? { GROK_LOGIN_ENV: GROK_LOADER_LOGIN_ENV }
+          : {}),
       },
       maxOutputBytes: AGENT_SESSION_OUTPUT_BUFFER_BYTES,
     };

package/lib/agents/kimi.ts

@@ -223,6 +223,7 @@ export class KimiSession implements AgentSession {
     if (this.sessionId) argv.push("-r", this.sessionId);
     return {
       argv: argv as [string, ...string[]],
+      projectEnvProfile: "task",
       user: "node",
       env: this.agentEnv,
       maxOutputBytes: AGENT_SESSION_OUTPUT_BUFFER_BYTES,

package/lib/agents/machine-durable.ts

@@ -59,6 +59,7 @@ async function execStep(
 ): Promise<{ exitCode: number | null; stdout: string; stderr: string }> {
   const result = await environment.exec({
     argv,
+    projectEnvProfile: "maintenance",
     ...(stdin ? { stdin } : {}),
     timeoutMs: STEP_TIMEOUT_MS,
     maxOutputBytes: STEP_OUTPUT_BYTES,
@@ -228,6 +229,7 @@ export class MachineDurableProcess implements LineTransport {
           String(this.#offset + 1),
           this.#outboxPath,
         ],
+        projectEnvProfile: "maintenance",
         maxOutputBytes: 8 * 1024 * 1024,
       });
     } catch {

package/lib/agents/opencode.ts

@@ -357,6 +357,7 @@ export class OpencodeSession implements AgentSession {
     argv.push(prompt);
     return {
       argv: argv as [string, ...string[]],
+      projectEnvProfile: "task",
       user: "node",
       env: this.agentEnv,
       maxOutputBytes: AGENT_SESSION_OUTPUT_BUFFER_BYTES,

package/lib/agents/proc.ts

@@ -7,6 +7,7 @@ import type {
   TaskEnvironmentProcess,
   TaskEnvironmentSessionRequest,
 } from "../task-environment/types";
+import { agentCliArgv } from "../agent-cli";
 
 export type LineHandler = (line: string) => void;
 export type ExitHandler = (code: number | null) => void;
@@ -168,6 +169,10 @@ export function spawnEnvironmentProcess(
   environment: TaskEnvironmentAgentSessionSurface,
   request: TaskEnvironmentSessionRequest,
 ): AgentEnvironmentProcess {
+  const launchRequest: TaskEnvironmentSessionRequest = {
+    ...request,
+    argv: agentCliArgv(environment, request.argv),
+  };
   class EnvironmentProcess extends EventEmitter implements AgentEnvironmentProcess {
     readonly stdout = new EventEmitter();
     readonly stderr = new EventEmitter();
@@ -176,7 +181,7 @@ export function spawnEnvironmentProcess(
 
     constructor() {
       super();
-      this.processPromise = environment.spawnSession(request);
+      this.processPromise = environment.spawnSession(launchRequest);
       void this.consume();
     }
 

package/lib/agents/transport.ts

@@ -55,6 +55,7 @@ import {
   type ExitHandler,
   type LineHandler,
 } from "./proc";
+import { agentCliArgv } from "../agent-cli";
 import { isEnvironmentTransportProvider } from "../task-environment/types";
 import { attachCompatibilityKeysMatch } from "./attach-compatibility";
 
@@ -326,15 +327,16 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
     onCloseRequested: markClosed,
     debugLabel: opts.debugLabel,
     launch: async () => {
+      const cliArgv = agentCliArgv(opts.environment, [opts.cli, ...opts.cliArgs]);
       const result = await opts.environment.launchDetachedSession({
         argv: [
           "node",
           runnerInEnvironment,
           environmentSessionDir,
           "--",
-          opts.cli,
-          ...opts.cliArgs,
+          ...cliArgv,
         ],
+        projectEnvProfile: "task",
         inheritEnv: opts.passEnv ?? [],
         env: opts.explicitEnv ?? {},
         launchTimeoutMs: 30_000,
@@ -484,15 +486,16 @@ function machineDurableTransport(opts: AgentTransportOptions): LineTransport {
       }
       const runnerPath = await deployRunner(environment, sessionDir);
       await publishMachineCurrentSession(environment, sessionDir);
+      const cliArgv = agentCliArgv(environment, [opts.cli, ...opts.cliArgs]);
       const result = await environment.launchDetachedSession({
         argv: [
           "node",
           runnerPath,
           sessionDir,
           "--",
-          opts.cli,
-          ...opts.cliArgs,
+          ...cliArgv,
         ],
+        projectEnvProfile: "task",
         inheritEnv: opts.passEnv ?? [],
         env: opts.explicitEnv ?? {},
         launchTimeoutMs: 30_000,
@@ -538,7 +541,8 @@ function directEnvironmentTransport(opts: AgentTransportOptions): LineTransport
   return new EnvironmentLineProcess({
     environment: opts.environment,
     request: {
-      argv: [opts.cli, ...opts.cliArgs],
+      argv: agentCliArgv(opts.environment, [opts.cli, ...opts.cliArgs]),
+      projectEnvProfile: "task",
       inheritEnv: opts.passEnv ?? [],
       env: opts.explicitEnv ?? {},
       maxOutputBytes: AGENT_SESSION_OUTPUT_BUFFER_BYTES,

package/lib/browser-testing.ts

@@ -1157,6 +1157,7 @@ export async function setupBrowserTesting(
     for (const step of VIEWER_STEPS) {
       if (environment) {
         await environment.launchDetachedSession({
+          projectEnvProfile: "maintenance",
           argv: ["sh", "-c", step],
           env: authorityEnv,
           maxOutputBytes: 64 * 1024,
@@ -1194,6 +1195,7 @@ export async function setupBrowserTesting(
     const installed = environment
       ? await (async () => {
           const chown = await environment.exec({
+            projectEnvProfile: "maintenance",
             argv: ["/usr/bin/chown", "node:node", "/opt/pw-browsers"],
             user: "root",
             env: authorityEnv,
@@ -1208,6 +1210,7 @@ export async function setupBrowserTesting(
             );
           }
           return environment.exec({
+            projectEnvProfile: "maintenance",
             argv: ["sh", "-lc", PREWARM_CMD],
             cwd: "/workspace",
             env: authorityEnv,
@@ -1309,6 +1312,7 @@ export async function setupBrowserTesting(
     ] as [string, ...string[]];
     const wrote = environment
       ? await environment.exec({
+          projectEnvProfile: "maintenance",
           argv: writeArgv,
           cwd: "/workspace",
           env: writeEnv,
@@ -1397,6 +1401,7 @@ export async function setupBrowserTesting(
       ] as [string, ...string[]];
       const registered = environment
         ? await environment.exec({
+            projectEnvProfile: "maintenance",
             argv: grokArgv,
             cwd: "/workspace",
             env: authorityEnv,
@@ -1469,6 +1474,7 @@ export async function setupBrowserTesting(
     };
     if (environment) {
       await environment.exec({
+        projectEnvProfile: "maintenance",
         argv: ["/bin/sh", "-c", guardedAptStart],
         user: "root",
         cwd: "/workspace",

package/lib/codex-auth.ts

@@ -261,6 +261,7 @@ export async function injectCodexIntoMachine(
   environment: {
     exec(request: {
       argv: readonly [string, ...string[]];
+      projectEnvProfile: "maintenance" | "task";
       timeoutMs: number;
       maxOutputBytes: number;
     }): Promise<{ exitCode: number | null; stderr: Uint8Array }>;
@@ -277,6 +278,7 @@ export async function injectCodexIntoMachine(
   if (!exists(join(dir, "auth.json"))) return true; // nothing to inject
   try {
     const made = await environment.exec({
+      projectEnvProfile: "maintenance",
       argv: ["/bin/mkdir", "-p", "/home/node/.codex"],
       timeoutMs: EXEC_TIMEOUT_MS,
       maxOutputBytes: 64 * 1024,

package/lib/credential-store.ts

@@ -36,12 +36,57 @@ export interface StoredParameter {
   value: string;
 }
 
+export interface StoredParameterVersion extends StoredParameter {
+  version: number;
+}
+
+export type ImmutableParameterPutResult = "created" | "matched";
+
+/** The immutable name exists, but its authenticated identity is different. */
+export class ImmutableParameterConflictError extends Error {
+  constructor(message = "immutable parameter identity conflicts with the existing value") {
+    super(message);
+    this.name = "ImmutableParameterConflictError";
+  }
+}
+
+/** A failed/ambiguous create could not yet be proved to be our prior write. */
+export class ImmutableParameterUnverifiedError extends Error {
+  constructor(message = "immutable parameter create could not be verified") {
+    super(message);
+    this.name = "ImmutableParameterUnverifiedError";
+  }
+}
+
 export interface CredentialStore {
   readonly kind: "aws-ssm";
   /** Create or overwrite one credential. Throws on failure. */
   put(name: string, value: string): Promise<void>;
+  /**
+   * Create one immutable SecureString with its identity tags in the same AWS
+   * request. A retry never overwrites or reads the value: metadata proves that
+   * an already-existing name is the exact prior write.
+   *
+   * Optional for custom/older stores. Callers that require create-once
+   * semantics must fail closed when it is absent.
+   */
+  putImmutable?(
+    name: string,
+    value: string,
+    tags: Record<string, string>,
+  ): Promise<ImmutableParameterPutResult>;
   /** The credential's plaintext, or null when it does not exist. */
   get(name: string): Promise<string | null>;
+  /**
+   * One exact immutable parameter version. Project-env replica migration
+   * uses this for legacy value references: reading the latest value and then
+   * assuming its version would allow a late old writer to substitute a new
+   * secret for the head the cloud actually named.
+   *
+   * Optional for older/custom stores. Callers that require a pinned read
+   * must fail closed when it is absent.
+   */
+  getVersion?(name: string, version: number): Promise<StoredParameterVersion | null>;
   /** Idempotent: a missing parameter is not an error. */
   delete(name: string): Promise<void>;
   /** Every credential under `path` (recursive), decrypted. Throws on failure. */
@@ -162,6 +207,19 @@ function isAccessDenied(result: CliResult): boolean {
   return /AccessDenied/.test(result.stderr);
 }
 
+function checkedTagEntries(tags: Record<string, string>): Array<[string, string]> {
+  const entries = Object.entries(tags);
+  for (const [key, value] of entries) {
+    if (
+      !/^[A-Za-z0-9_.:/=+@-]{1,128}$/.test(key) ||
+      !/^[A-Za-z0-9_.:/=+@ -]{0,256}$/.test(value)
+    ) {
+      throw new Error(`invalid tag ${key}`);
+    }
+  }
+  return entries;
+}
+
 /** Summarize a CLI failure WITHOUT echoing stdout (which could carry a value). */
 function failure(op: string, result: CliResult): Error {
   const line =
@@ -207,15 +265,59 @@ export class AwsSsmCredentialStore implements CredentialStore {
     if (result.status !== 0) throw failure("put-parameter", result);
   }
 
-  async tag(name: string, tags: Record<string, string>): Promise<void> {
+  async putImmutable(
+    name: string,
+    value: string,
+    tags: Record<string, string>,
+  ): Promise<ImmutableParameterPutResult> {
     if (!isParameterName(name)) throw new Error(`invalid parameter name: ${name}`);
-    const entries = Object.entries(tags);
-    if (entries.length === 0) return;
-    for (const [key, value] of entries) {
-      if (!/^[A-Za-z0-9_.:/=+@-]{1,128}$/.test(key) || !/^[A-Za-z0-9_.:/=+@ -]{0,256}$/.test(value)) {
-        throw new Error(`invalid tag ${key}`);
+    const entries = checkedTagEntries(tags);
+    if (entries.length === 0) {
+      throw new Error("immutable parameter identity tags are required");
+    }
+    const input = JSON.stringify({
+      Name: name,
+      Value: value,
+      Type: "SecureString",
+      KeyId: this.kmsKeyId,
+      Tier: "Advanced",
+      Overwrite: false,
+      Tags: entries.map(([Key, Value]) => ({ Key, Value })),
+    });
+    const result = await withPrivateInputFile(input, (path) =>
+      this.run(["ssm", "put-parameter", "--cli-input-json", `file://${path}`]),
+    );
+    if (result.status === 0) return "created";
+
+    // The CLI can lose the successful response, and a retry then receives
+    // ParameterAlreadyExists. The sign-in-box identity is intentionally
+    // write-only, so authenticate the prior write using metadata only.
+    let observed: Record<string, string>;
+    try {
+      observed = await this.listTags(name);
+    } catch {
+      throw new ImmutableParameterUnverifiedError();
+    }
+    let missing = false;
+    for (const [key, expected] of entries) {
+      const actual = observed[key];
+      if (actual === undefined) {
+        missing = true;
+      } else if (actual !== expected) {
+        throw new ImmutableParameterConflictError();
       }
     }
+    if (!missing) return "matched";
+
+    // Tags are eventually consistent with the create. Missing/partial tags
+    // are therefore retryable, never permission to add tags or overwrite.
+    throw new ImmutableParameterUnverifiedError();
+  }
+
+  async tag(name: string, tags: Record<string, string>): Promise<void> {
+    if (!isParameterName(name)) throw new Error(`invalid parameter name: ${name}`);
+    const entries = checkedTagEntries(tags);
+    if (entries.length === 0) return;
     const result = await this.run([
       "ssm",
       "add-tags-to-resource",
@@ -248,6 +350,39 @@ export class AwsSsmCredentialStore implements CredentialStore {
     return value;
   }
 
+  async getVersion(
+    name: string,
+    version: number,
+  ): Promise<StoredParameterVersion | null> {
+    if (!isParameterName(name)) throw new Error(`invalid parameter name: ${name}`);
+    if (!Number.isSafeInteger(version) || version < 1) {
+      throw new Error(`invalid parameter version: ${version}`);
+    }
+    const result = await this.run([
+      "ssm",
+      "get-parameter",
+      "--name",
+      `${name}:${version}`,
+      "--with-decryption",
+    ]);
+    if (result.status !== 0) {
+      if (isNotFound(result)) return null;
+      throw failure("get-parameter", result);
+    }
+    const parameter = (JSON.parse(result.stdout) as {
+      Parameter?: { Name?: unknown; Value?: unknown; Version?: unknown };
+    }).Parameter;
+    if (
+      parameter === undefined ||
+      parameter.Name !== name ||
+      typeof parameter.Value !== "string" ||
+      parameter.Version !== version
+    ) {
+      throw new Error("aws ssm get-parameter: malformed versioned response");
+    }
+    return { name, value: parameter.Value, version };
+  }
+
   async delete(name: string): Promise<void> {
     if (!isParameterName(name)) throw new Error(`invalid parameter name: ${name}`);
     const result = await this.run(["ssm", "delete-parameter", "--name", name]);

package/lib/engine-accounts.ts

@@ -654,6 +654,7 @@ async function copyDirIntoRaw(
   if (environment) {
     const run = async (argv: [string, ...string[]], step: string) => {
       const result = await environment.exec({
+        projectEnvProfile: "maintenance",
         argv,
         user: "root",
         env: RUNTIME_AUTHORITY_ENV,

package/lib/env-file.ts

@@ -133,6 +133,13 @@ export function restoreEnvFileSnapshotAtomic(
   }
 }
 
+/** Write `body` to `file` so a crash or power loss leaves either the old
+ *  file or the new one, never a torn or empty one: fsync the data, rename,
+ *  then fsync the directory. 0600, parent created 0700. */
+export function writeDurableFileAtomic(file: string, body: string): void {
+  replaceEnvFileAtomic(file, body);
+}
+
 function replaceEnvFileAtomic(file: string, body: string): void {
   const parent = dirname(file);
   mkdirSync(parent, { recursive: true, mode: 0o700 });