RooCodeInc · mrubens · Sep 10, 2026 · Sep 10, 2026 · Sep 10, 2026 · Sep 10, 2026
@@ -263,6 +263,7 @@ as per-task auth tokens or workspace paths.
 | `MODAL_ENDPOINT`                     | Optional          | Modal endpoint override.                                                                                                                 |
 | `MODAL_ENVIRONMENT`                  | Optional          | Modal environment name.                                                                                                                  |
 | `MODAL_APP_NAME`                     | Optional          | Modal app name override.                                                                                                                 |
+| `MODAL_BASE_IMAGE_REF`               | Optional          | Worker image Modal sandboxes start from. Defaults to the published image for the running release. Mutable tags such as `develop` are resolved to their current digest at launch; ECR refs are used as-is, so pin them.   |
 | `MODAL_REGIONS`                      | Optional          | Comma-separated Modal sandbox placement regions (for example `us` or `us-west`). Unset keeps Modal default placement.                    |
 | `MODAL_VM_MEMORY_MIB`                | Optional          | Memory allocated to Modal VM sandboxes used for nested Docker workloads. Defaults to `8192` MiB.                                         |
 | `E2B_API_KEY`                        | E2B               | E2B API key. Can also be saved from **Settings > Sandboxes**.                                                                            |

@@ -53,6 +53,18 @@ the task. Roomote starts Docker as the VM sandbox's primary service and requests
 standard sandbox runtime with 2 CPU cores and 4 GiB of memory.
 Container builds and services share the task sandbox's CPU and memory.
 
+## Worker image
+
+Modal sandboxes start from the published Roomote worker image for the running
+release. Override it with `MODAL_BASE_IMAGE_REF` to use a fork or registry
+mirror. Modal caches images by their reference string, so a mutable tag such as
+`develop` or `latest` would never be re-pulled after the first launch. Roomote
+resolves mutable tags to their current digest at launch time and reuses the
+last resolved digest if the registry is briefly unreachable. Immutable tags
+(`develop-<sha>`, `main-<sha>`, `v*`) and `@sha256` references are used as-is.
+ECR references are not resolved because the Roomote server holds no AWS
+credentials of its own; pin a digest or enable ECR tag immutability there.
+
 ## Verify setup
 
 1. save Modal credentials

@@ -8,6 +8,7 @@ import type {
   OpenCodeSession,
   OpenCodeSessionMessage,
 } from './types';
+import { redactSecrets } from '@roomote/communication/redact-secrets';
 
 // Bound every unary OpenCode HTTP call so a wedged server cannot leave the
 // worker sitting forever on a bare `fetch` with only the task-wide cancel
@@ -484,7 +485,11 @@ export class OpenCodeServerClient {
         )}`,
       );
       throw new Error(
-        `OpenCode request failed method=${method} path=${path} status=${response.status}`,
+        `OpenCode request failed method=${method} path=${path} status=${response.status}${
+          responseText
+            ? ` body=${redactSecrets(responseText.slice(0, 300))}`
+            : ''
+        }`,
       );
     } catch (error) {
       const elapsedMs = Date.now() - startedAt;

@@ -3602,9 +3602,12 @@ export class OpenCodeServerHarness
     const message = error instanceof Error ? error.message : String(error);
     const sessionId = 'opencode-session-create-failed';
     const timeoutMs = this.client.sessionCreateTimeoutMsValue;
+    // The request error may carry a slice of the raw OpenCode response body,
+    // so redact it and render it as code before it reaches the transcript.
+    const safeMessage = redactSecrets(message).replace(/`/gu, "'");
     const userText = message.includes('did not respond within')
       ? message
-      : `OpenCode session creation failed before the agent could start.\n\n${message}\n\nOpen the Logs sidebar and inspect harness.log for OpenCode lines (prefixed [opencode-server]).\n\n${formatOpenCodeSessionCreateTimeoutText(timeoutMs)}`;
+      : `OpenCode session creation failed before the agent could start.\n\n\`\`\`\n${safeMessage}\n\`\`\`\n\nOpen the Logs sidebar and inspect harness.log for OpenCode lines (prefixed [opencode-server]).\n\n${formatOpenCodeSessionCreateTimeoutText(timeoutMs)}`;
 
     this.logger.error(
       `OpenCode initial session create failed; failing the task terminally error=${message}`,

@@ -40,10 +40,40 @@ import {
   toAbortError,
   throwIfAborted,
 } from '../modal/abort';
+import {
+  isImmutableImageTag,
+  parseImageRef,
+  pinModalBaseImageRef,
+} from '../modal/registry-digest';
 import { normalizeModalRpcError } from '../modal/rpc-diagnostics';
 
 const DEFAULT_APP_NAME = 'roomote';
 
+const warnedUnpinnedEcrRefs = new Set<string>();
+
+/**
+ * ECR digests cannot be resolved from the controller: the OCI token flow does
+ * not apply, and the controller holds only the OIDC role Modal assumes, not
+ * AWS credentials of its own for `ecr:GetAuthorizationToken`. Modal keys its
+ * image cache on the ref string, so a mutable ECR tag will not be re-pulled
+ * after the first build. Warn once per process so operators know to pin.
+ */
+function warnUnpinnedEcrBaseImageRef(ref: string): void {
+  const parsed = parseImageRef(ref);
+  if (!parsed || parsed.digest || isImmutableImageTag(parsed.tag)) {
+    return;
+  }
+  if (warnedUnpinnedEcrRefs.has(ref)) {
+    return;
+  }
+  warnedUnpinnedEcrRefs.add(ref);
+  console.warn(
+    `[ModalClient] ECR base image uses a mutable tag; Modal will not re-pull it after the first build. Pin an @sha256 digest or an immutable tag, or enable ECR tag immutability ${JSON.stringify(
+      { ref },
+    )}`,
+  );
+}
+
 const DEFAULT_MODAL_WORKDIR = '/sandbox';
 const MODAL_VM_DOCKER_COMMAND = [
   '/usr/bin/sudo',
@@ -300,18 +330,37 @@ export class ModalClient implements ComputeProviderClient {
     return this.resolvedRegistrySecretPromise;
   }
 
-  private async resolveImage(): Promise<Image> {
+  private async resolveImage(
+    signal?: AbortSignal,
+  ): Promise<{ image: Image; imageRef: string }> {
     if (this.imageMode === 'ecr-oidc') {
+      warnUnpinnedEcrBaseImageRef(this.baseImageRef);
       const secret = await this.getEcrSecret();
-      return this.sdk.images.fromAwsEcr(this.baseImageRef, secret);
+      return {
+        image: this.sdk.images.fromAwsEcr(this.baseImageRef, secret),
+        imageRef: this.baseImageRef,
+      };
     }
 
+    // Modal keys its image cache on the ref string, so a mutable tag such as
+    // `:develop` would never be re-pulled after the first build. Pin the tag to
+    // its current digest so a new push produces a new image definition.
+    const imageRef = await pinModalBaseImageRef({
+      ref: this.baseImageRef,
+      registryUsername: this.config.registryUsername,
+      registryPassword: this.config.registryPassword,
+      signal,
+    });
+
     if (this.imageMode === 'registry-auth') {
       const secret = await this.getRegistrySecret();
-      return this.sdk.images.fromRegistry(this.baseImageRef, secret);
+      return {
+        image: this.sdk.images.fromRegistry(imageRef, secret),
+        imageRef,
+      };
     }
 
-    return this.sdk.images.fromRegistry(this.baseImageRef);
+    return { image: this.sdk.images.fromRegistry(imageRef), imageRef };
   }
 
   private normalizeSandboxTags(
@@ -450,8 +499,8 @@ export class ModalClient implements ComputeProviderClient {
       throw error;
     }
 
-    const image = await raceWithAbort({
-      promise: this.resolveImage(),
+    const { image, imageRef } = await raceWithAbort({
+      promise: this.resolveImage(input.signal),
       signal: input.signal,
       abortMessage: `Resolving Modal image "${this.baseImageRef}" was aborted`,
     });
@@ -461,6 +510,7 @@ export class ModalClient implements ComputeProviderClient {
     try {
       console.log(
         `[ModalClient] Creating sandbox... ${JSON.stringify({
+          imageRef,
           encryptedPorts: input.ports,
           regions: this.config.regions ?? '(default)',
           cpu: this.config.cpu ?? '(default)',

@@ -28,6 +28,7 @@ import type {
 } from '../types';
 import { unsupported } from '../errors';
 import { sleepWithSignal, throwIfAborted, toAbortError } from '../modal/abort';
+import { pinModalBaseImageRef } from '../modal/registry-digest';
 import { RoomoteBrokerExec } from './roomote-broker-exec';
 import {
   BrokerRequestError,
@@ -283,10 +284,16 @@ export class RoomoteBrokerClient implements ComputeProviderClient {
     throwIfAborted(input.signal);
 
     const idempotencyKey = input.idempotencyKey ?? randomUUID();
+    // Same mutable-tag pitfall as the direct Modal adapter: the broker keys
+    // its image cache on the ref string, so pin the tag to its digest first.
+    const imageRef = sourceSnapshotId
+      ? undefined
+      : await pinModalBaseImageRef({
+          ref: this.config.baseImageRef,
+          signal: input.signal,
+        });
     const body = JSON.stringify({
-      ...(sourceSnapshotId
-        ? { snapshotId: sourceSnapshotId }
-        : { imageRef: this.config.baseImageRef }),
+      ...(sourceSnapshotId ? { snapshotId: sourceSnapshotId } : { imageRef }),
       ...(input.ports?.length ? { ports: input.ports } : {}),
       ...(input.tags && Object.keys(input.tags).length > 0
         ? { tags: input.tags }