@fitlab-ai/agent-infra 0.8.2 → 0.8.3

package/lib/sandbox/clipboard/win32.ts

@@ -0,0 +1,173 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { ExecFileSyncOptions } from 'node:child_process';
+
+const PROBE_TIMEOUT_MS = 2_000;
+const READ_IMAGE_TIMEOUT_MS = 5_000;
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const POWERSHELL_ARGS = ['-NoProfile', '-NonInteractive', '-STA', '-Command'];
+
+type ExecFn = (cmd: string, args: string[], options?: ExecFileSyncOptions) => Buffer | string;
+type MkdtempFn = (prefix: string) => string;
+type ReadFileFn = (filePath: fs.PathOrFileDescriptor) => Buffer | string;
+type RmFn = (filePath: fs.PathLike, options: { recursive?: boolean; force?: boolean }) => void;
+type ExistsFn = (filePath: fs.PathLike) => boolean;
+
+export type Win32ClipboardAdapter = {
+  available(): { ok: true } | { ok: false; reason: string };
+  readImagePng(): Buffer | null;
+  readImageFromPath(imagePath: string): Buffer | null;
+  readImageFromText(text: string): Buffer | null;
+};
+
+export function createWin32ClipboardAdapter({
+  execFn = execFileSync,
+  mkdtempFn = fs.mkdtempSync,
+  readFileFn = fs.readFileSync,
+  rmFn = fs.rmSync,
+  existsFn = fs.existsSync
+}: {
+  execFn?: ExecFn;
+  mkdtempFn?: MkdtempFn;
+  readFileFn?: ReadFileFn;
+  rmFn?: RmFn;
+  existsFn?: ExistsFn;
+} = {}): Win32ClipboardAdapter {
+  return {
+    available() {
+      try {
+        execFn('powershell.exe', [...POWERSHELL_ARGS, clipboardProbeScript()], {
+          encoding: 'utf8',
+          timeout: PROBE_TIMEOUT_MS
+        });
+        return { ok: true };
+      } catch {
+        return {
+          ok: false,
+          reason: 'Windows PowerShell Get-Clipboard is unavailable; install or enable powershell.exe to use image paste'
+        };
+      }
+    },
+    readImagePng() {
+      const tmpDir = mkdtempFn(path.join(os.tmpdir(), 'agent-infra-clipboard-'));
+      const outputPath = path.join(tmpDir, 'clipboard.png');
+      try {
+        execFn('powershell.exe', [...POWERSHELL_ARGS, pngWriteScript(outputPath)], {
+          encoding: 'utf8',
+          timeout: READ_IMAGE_TIMEOUT_MS
+        });
+        const png = Buffer.from(readFileFn(outputPath));
+        return isPng(png) ? png : null;
+      } catch {
+        return null;
+      } finally {
+        rmFn(tmpDir, { recursive: true, force: true });
+      }
+    },
+    readImageFromPath(imagePath) {
+      const tmpDir = mkdtempFn(path.join(os.tmpdir(), 'agent-infra-clipboard-'));
+      const outputPath = path.join(tmpDir, 'clipboard.png');
+      try {
+        execFn('powershell.exe', [...POWERSHELL_ARGS, pngFromPathScript(imagePath, outputPath)], {
+          encoding: 'utf8',
+          timeout: READ_IMAGE_TIMEOUT_MS
+        });
+        const png = Buffer.from(readFileFn(outputPath));
+        return isPng(png) ? png : null;
+      } catch {
+        return null;
+      } finally {
+        rmFn(tmpDir, { recursive: true, force: true });
+      }
+    },
+    readImageFromText(text) {
+      const trimmed = text.trim();
+      if (!isWindowsImagePath(trimmed)) {
+        return null;
+      }
+      if (!existsFn(trimmed)) {
+        return null;
+      }
+      return this.readImageFromPath(trimmed);
+    }
+  };
+}
+
+function clipboardProbeScript(): string {
+  return 'if ($null -eq (Get-Command Get-Clipboard -ErrorAction SilentlyContinue)) { exit 1 }';
+}
+
+// Embed a filesystem path in a PowerShell single-quoted string literal.
+// Single-quoted strings in PowerShell are verbatim (no variable expansion,
+// no escape sequences). The only special character is a single quote itself,
+// which is escaped by doubling it.
+function psLiteral(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+function pngWriteScript(outputPath: string): string {
+  const psOutputPath = psLiteral(outputPath);
+  return [
+    '$ErrorActionPreference = "Stop"',
+    `$outputPath = ${psOutputPath}`,
+    '$image = $null',
+    'try {',
+    '  Add-Type -AssemblyName System.Drawing',
+    '  $image = Get-Clipboard -Format Image -ErrorAction SilentlyContinue',
+    '  if ($null -ne $image) {',
+    '    $image.Save($outputPath, [System.Drawing.Imaging.ImageFormat]::Png)',
+    '    return',
+    '  }',
+    '  $files = Get-Clipboard -Format FileDropList -ErrorAction SilentlyContinue',
+    '  if ($null -ne $files) {',
+    '    $allowed = @(".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp", ".tiff", ".tif", ".ico")',
+    '    foreach ($file in $files) {',
+    '      if (-not (Test-Path -LiteralPath $file -PathType Leaf)) { continue }',
+    '      $ext = [System.IO.Path]::GetExtension($file)',
+    '      if ($allowed -notcontains $ext) { continue }',
+    '      try {',
+    '        $image = [System.Drawing.Image]::FromFile($file)',
+    '        $image.Save($outputPath, [System.Drawing.Imaging.ImageFormat]::Png)',
+    '        return',
+    '      } catch {}',
+    '    }',
+    '  }',
+    '  throw "clipboard has no image"',
+    '} finally {',
+    '  if ($null -ne $image -and $image -is [System.IDisposable]) { $image.Dispose() }',
+    '}'
+  ].join('\n');
+}
+
+function pngFromPathScript(imagePath: string, outputPath: string): string {
+  const psImagePath = psLiteral(imagePath);
+  const psOutputPath = psLiteral(outputPath);
+  return [
+    '$ErrorActionPreference = "Stop"',
+    `$imagePath = ${psImagePath}`,
+    `$outputPath = ${psOutputPath}`,
+    '$image = $null',
+    'try {',
+    '  Add-Type -AssemblyName System.Drawing',
+    '  if (-not (Test-Path -LiteralPath $imagePath -PathType Leaf)) { throw "file not found: $imagePath" }',
+    '  $image = [System.Drawing.Image]::FromFile($imagePath)',
+    '  $image.Save($outputPath, [System.Drawing.Imaging.ImageFormat]::Png)',
+    '} finally {',
+    '  if ($null -ne $image -and $image -is [System.IDisposable]) { $image.Dispose() }',
+    '}'
+  ].join('\n');
+}
+
+const IMAGE_EXTENSIONS_RE = /\.(png|jpg|jpeg|gif|bmp|webp|tiff?|ico)$/i;
+
+function isWindowsImagePath(text: string): boolean {
+  // Must be a Windows absolute path: drive letter + colon + backslash/slash
+  // followed by a path ending with a known image extension.
+  return /^[A-Za-z]:[\\/].+$/.test(text) && IMAGE_EXTENSIONS_RE.test(text);
+}
+
+function isPng(buffer: Buffer): boolean {
+  return buffer.length >= PNG_MAGIC.length && PNG_MAGIC.every((byte, index) => buffer[index] === byte);
+}

package/lib/sandbox/commands/create.ts

@@ -16,6 +16,7 @@ import {
   parsePositiveIntegerOption,
   sandboxBranchLabel,
   sandboxImageConfigLabel,
+  sandboxImageRefreshLabel,
   sandboxLabel,
   shareBranchDir,
   shareCommonDir,
@@ -37,17 +38,13 @@ import {
 } from '../shell.ts';
 import { resolveTaskBranch } from '../task-resolver.ts';
 import {
-  imageSignatureFields,
   resolveTools,
-  toolConfigDirCandidates,
-  toolNpmPackagesArg,
-  toolShellInstallScriptBase64
+  toolConfigDirCandidates
 } from '../tools.ts';
 import type { SandboxTool } from '../tools.ts';
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.ts';
 import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.ts';
 import { validateSelinuxDisableEnv } from '../engines/selinux.ts';
-import { resolveBuildUid } from '../engines/native.ts';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.ts';
 import { ensureSandboxDiscoveryReadmes } from '../readme-scaffold.ts';
 import {
@@ -56,6 +53,14 @@ import {
   validateClaudeCredentialsEnvOverride
 } from '../credentials.ts';
 import { detectHostTimezone } from '../host-timezone.ts';
+import {
+  buildImageSignature,
+  buildSandboxImageArgs,
+  isRefreshDisabled,
+  isRefreshDue,
+  parseImageLabels,
+  parseRefreshTimestamp
+} from '../image-build.ts';
 
 const OPENCODE_YOLO_PERMISSION = '{"*":"allow","read":"allow","bash":"allow","edit":"allow","webfetch":"allow","external_directory":"allow","doom_loop":"allow"}';
 const SANDBOX_ALIAS_BLOCK_BEGIN = '# >>> agent-infra managed aliases >>>';
@@ -82,7 +87,7 @@ alias gy='gemini --yolo; tput ed'
 `;
 const CONTAINER_HOME = '/home/devuser';
 const CONTAINER_SHELL_CONFIG_MOUNT = `${CONTAINER_HOME}/.host-shell-config`;
-const USAGE = `Usage: ai sandbox create <branch> [base] [--cpu <n>] [--memory <n>]
+const USAGE = `Usage: ai sandbox create <branch> [base] [--cpu <n>] [--memory <n>] [--no-refresh]
 
 Host aliases:
   ${'~'}/.agent-infra/aliases/sandbox.sh is auto-created on first run and exposed
@@ -115,16 +120,6 @@ type HostShellConfig = {
   mounts: Array<{ hostPath: string; containerPath: string }>;
 };
 
-function buildSignature(preparedDockerfile: PreparedDockerfile, tools: SandboxTool[]): string {
-  return createHash('sha256')
-    .update(JSON.stringify({
-      dockerfile: preparedDockerfile.signature,
-      tools: imageSignatureFields(tools)
-    }))
-    .digest('hex')
-    .slice(0, 12);
-}
-
 function resolveToolDirs(config: Pick<SandboxCreateConfig, 'project'>, tools: SandboxTool[], branch: string): ResolvedTool[] {
   return tools.map((tool) => {
     const candidates = toolConfigDirCandidates(tool, config.project, branch);
@@ -1191,43 +1186,43 @@ export function buildImage(
     runFn = runEngine,
     runSafeFn = runSafeEngine,
     runVerboseFn = runVerboseEngine,
-    env = process.env
+    env = process.env,
+    refresh = false,
+    lastRefresh
   }: {
     engine?: string;
     runFn?: EngineRunFn;
     runSafeFn?: EngineRunSafeFn;
     runVerboseFn?: EngineRunVerboseFn;
     env?: NodeJS.ProcessEnv;
+    refresh?: boolean;
+    lastRefresh?: number;
   } = {}
 ): void {
   const selectedEngine = engine ?? detectEngine({ engine: config.engine });
-  const { uid: hostUid, gid: hostGid } = resolveBuildUid({
-    engine: selectedEngine,
-    runFn,
-    runSafeFn,
-    env
-  });
+  runVerboseFn(
+    selectedEngine,
+    'docker',
+    buildSandboxImageArgs(config, tools, dockerfilePath, imageSignature, {
+      engine: selectedEngine,
+      runFn,
+      runSafeFn,
+      env,
+      refresh,
+      lastRefresh
+    }),
+    { cwd: config.repoRoot }
+  );
+}
 
-  runVerboseFn(selectedEngine, 'docker', [
-    'build',
-    '-t',
-    config.imageName,
-    '--build-arg',
-    `HOST_UID=${hostUid}`,
-    '--build-arg',
-    `HOST_GID=${hostGid}`,
-    '--build-arg',
-    `AI_TOOL_PACKAGES=${toolNpmPackagesArg(tools)}`,
-    '--build-arg',
-    `AI_TOOLS_SHELL_INSTALL_B64=${toolShellInstallScriptBase64(tools)}`,
-    '--label',
-    sandboxLabel(config),
-    '--label',
-    `${sandboxImageConfigLabel(config)}=${imageSignature}`,
-    '-f',
-    toEnginePath(selectedEngine, dockerfilePath),
-    toEnginePath(selectedEngine, config.repoRoot)
-  ], { cwd: config.repoRoot });
+function readImageLabels(config: Pick<SandboxCreateConfig, 'imageName'> & Pick<SandboxCreateConfig, 'project'>, engine: string): Record<string, string> {
+  return parseImageLabels(runSafeEngine(engine, 'docker', [
+    'image',
+    'inspect',
+    '--format',
+    '{{ json .Config.Labels }}',
+    config.imageName
+  ]));
 }
 
 export async function create(args: string[]): Promise<void> {
@@ -1238,6 +1233,7 @@ export async function create(args: string[]): Promise<void> {
     options: {
       cpu: { type: 'string' },
       memory: { type: 'string' },
+      'no-refresh': { type: 'boolean' },
       help: { type: 'boolean', short: 'h' }
     }
   });
@@ -1287,7 +1283,7 @@ export async function create(args: string[]): Promise<void> {
   const shareBranch = shareBranchDir(effectiveConfig, branch);
   const preparedDockerfile = prepareDockerfile(effectiveConfig);
   const baseBranch = base ?? runSafe('git', ['-C', effectiveConfig.repoRoot, 'branch', '--show-current']);
-  const expectedImageSignature = buildSignature(preparedDockerfile, tools);
+  const expectedImageSignature = buildImageSignature(preparedDockerfile, tools);
   const engine = detectEngine(effectiveConfig);
 
   p.intro(pc.cyan('AI Sandbox'));
@@ -1310,27 +1306,53 @@ export async function create(args: string[]): Promise<void> {
     p.log.success('Docker is ready');
 
     const imageExists = runOkEngine(engine, 'docker', ['image', 'inspect', effectiveConfig.imageName]);
-    const currentImageSignature = imageExists
-      ? runSafeEngine(engine, 'docker', [
-        'image',
-        'inspect',
-        '--format',
-        `{{ index .Config.Labels "${sandboxImageConfigLabel(effectiveConfig)}" }}`,
-        effectiveConfig.imageName
-      ])
-      : '';
-    const needsImageBuild = !imageExists || currentImageSignature !== expectedImageSignature;
+    const imageLabels = imageExists ? readImageLabels(effectiveConfig, engine) : {};
+    const currentImageSignature = imageLabels[sandboxImageConfigLabel(effectiveConfig)] ?? '';
+    const currentLastRefresh = parseRefreshTimestamp(imageLabels[sandboxImageRefreshLabel(effectiveConfig)] ?? '');
+    const signatureStale = !imageExists || currentImageSignature !== expectedImageSignature;
+    const now = Date.now();
+    const refreshDue = imageExists
+      && !signatureStale
+      && !isRefreshDisabled(process.env, values['no-refresh'] ?? false)
+      && isRefreshDue(currentLastRefresh, now, effectiveConfig.refreshIntervalDays);
+    const needsImageBuild = signatureStale || refreshDue;
 
     if (needsImageBuild) {
-      p.log.step(imageExists ? 'Rebuilding stale image...' : 'Building image for first use...');
-      buildImage(
-        effectiveConfig,
-        tools,
-        preparedDockerfile.path,
-        expectedImageSignature,
-        { engine }
+      const buildRefresh = !imageExists || refreshDue;
+      const buildLastRefresh = buildRefresh ? now : currentLastRefresh || 0;
+
+      p.log.step(
+        refreshDue
+          ? 'Refreshing stale image...'
+          : imageExists
+            ? 'Rebuilding stale image...'
+            : 'Building image for first use...'
       );
-      p.log.success(imageExists ? 'Image rebuilt' : 'Image built');
+      try {
+        buildImage(
+          effectiveConfig,
+          tools,
+          preparedDockerfile.path,
+          expectedImageSignature,
+          { engine, refresh: buildRefresh, lastRefresh: buildLastRefresh }
+        );
+        p.log.success(
+          refreshDue
+            ? 'Image refreshed'
+            : imageExists
+              ? 'Image rebuilt'
+              : 'Image built'
+        );
+      } catch (error) {
+        if (refreshDue && !signatureStale && imageExists) {
+          p.log.warn(
+            'Scheduled sandbox image refresh failed; continuing with the existing image. ' +
+            commandErrorMessage(error)
+          );
+        } else {
+          throw error;
+        }
+      }
     } else {
       p.log.step(`Using existing image ${effectiveConfig.imageName}`);
     }
@@ -1579,8 +1601,6 @@ export async function create(args: string[]): Promise<void> {
                 path.join(effectiveConfig.repoRoot, '.git'),
                 `${toEnginePath(engine, effectiveConfig.repoRoot)}/.git`
               ),
-              '-v',
-              volumeArg(engine, hostJoin(effectiveConfig.home, '.ssh'), '/home/devuser/.ssh', ':ro'),
               ...dotfilesMount,
               ...toolVolumes,
               ...tmpfsArgs,

package/lib/sandbox/commands/rebuild.ts

@@ -1,40 +1,27 @@
 import { parseArgs } from 'node:util';
-import { createHash } from 'node:crypto';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { loadConfig } from '../config.ts';
 import type { SandboxConfig } from '../config.ts';
 import { prepareDockerfile } from '../dockerfile.ts';
-import { sandboxImageConfigLabel, sandboxLabel } from '../constants.ts';
+import { sandboxImageRefreshLabel } from '../constants.ts';
 import { detectEngine, ensureDocker } from '../engine.ts';
-import { runEngine, runSafeEngine, runVerboseEngine } from '../shell.ts';
+import { runEngine, runOkEngine, runSafeEngine, runVerboseEngine } from '../shell.ts';
 import { pruneSandboxDanglingImages } from '../image-prune.ts';
-import {
-  imageSignatureFields,
-  resolveTools,
-  toolNpmPackagesArg,
-  toolShellInstallScriptBase64
-} from '../tools.ts';
+import { resolveTools } from '../tools.ts';
 import type { SandboxTool } from '../tools.ts';
-import { toEnginePath } from '../engines/wsl2-paths.ts';
-import { resolveBuildUid } from '../engines/native.ts';
+import {
+  buildImageSignature,
+  buildSandboxImageArgs,
+  parseImageLabels,
+  parseRefreshTimestamp
+} from '../image-build.ts';
 
 const USAGE = `Usage: ai sandbox rebuild [--quiet] [--refresh]`;
 
-type PreparedDockerfile = ReturnType<typeof prepareDockerfile>;
 type EngineRunFn = (engine: string, cmd: string, args: string[], opts?: { cwd?: string }) => string;
 type EngineRunSafeFn = EngineRunFn;
 
-function buildSignature(preparedDockerfile: PreparedDockerfile, tools: SandboxTool[]): string {
-  return createHash('sha256')
-    .update(JSON.stringify({
-      dockerfile: preparedDockerfile.signature,
-      tools: imageSignatureFields(tools)
-    }))
-    .digest('hex')
-    .slice(0, 12);
-}
-
 export function buildArgs(
   config: SandboxConfig,
   tools: SandboxTool[],
@@ -45,49 +32,41 @@ export function buildArgs(
     runFn = runEngine,
     runSafeFn = runSafeEngine,
     env = process.env,
-    refresh = false
+    refresh = false,
+    lastRefresh
   }: {
     engine?: string;
     runFn?: EngineRunFn;
     runSafeFn?: EngineRunSafeFn;
     env?: NodeJS.ProcessEnv;
     refresh?: boolean;
+    lastRefresh?: number;
   } = {}
 ): string[] {
-  const selectedEngine = engine ?? detectEngine(config);
-  const { uid: hostUid, gid: hostGid } = resolveBuildUid({
-    engine: selectedEngine,
+  return buildSandboxImageArgs(config, tools, dockerfilePath, imageSignature, {
+    engine: engine ?? detectEngine(config),
     runFn,
     runSafeFn,
-    env
+    env,
+    refresh,
+    lastRefresh
   });
+}
 
-  const args = [
-    'build',
-    '-t',
-    config.imageName,
-    '--build-arg',
-    `HOST_UID=${hostUid}`,
-    '--build-arg',
-    `HOST_GID=${hostGid}`,
-    '--build-arg',
-    `AI_TOOL_PACKAGES=${toolNpmPackagesArg(tools)}`,
-    '--build-arg',
-    `AI_TOOLS_SHELL_INSTALL_B64=${toolShellInstallScriptBase64(tools)}`,
-    '--label',
-    sandboxLabel(config),
-    '--label',
-    `${sandboxImageConfigLabel(config)}=${imageSignature}`,
-    '-f',
-    toEnginePath(selectedEngine, dockerfilePath),
-    toEnginePath(selectedEngine, config.repoRoot)
-  ];
-
-  if (refresh) {
-    args.splice(1, 0, '--no-cache', '--pull');
+function readExistingLastRefresh(config: SandboxConfig, engine: string): number {
+  if (!runOkEngine(engine, 'docker', ['image', 'inspect', config.imageName])) {
+    return 0;
   }
 
-  return args;
+  const labels = parseImageLabels(runSafeEngine(engine, 'docker', [
+    'image',
+    'inspect',
+    '--format',
+    '{{ json .Config.Labels }}',
+    config.imageName
+  ]));
+
+  return parseRefreshTimestamp(labels[sandboxImageRefreshLabel(config)] ?? '');
 }
 
 export async function rebuild(args: string[]): Promise<void> {
@@ -110,19 +89,24 @@ export async function rebuild(args: string[]): Promise<void> {
   const config = loadConfig();
   const tools = resolveTools(config);
   const preparedDockerfile = prepareDockerfile(config);
-  const imageSignature = buildSignature(preparedDockerfile, tools);
+  const imageSignature = buildImageSignature(preparedDockerfile, tools);
   const quiet = values.quiet ?? false;
   const refresh = values.refresh ?? false;
   const engine = detectEngine(config);
 
   await ensureDocker(config, undefined);
+  const lastRefresh = refresh ? Date.now() : readExistingLastRefresh(config, engine);
   p.intro(pc.cyan('Rebuilding sandbox image'));
 
   try {
     if (quiet) {
       const spinner = p.spinner();
       spinner.start('Building image...');
-      runEngine(engine, 'docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine, refresh }), {
+      runEngine(engine, 'docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature, {
+        engine,
+        refresh,
+        lastRefresh
+      }), {
         cwd: config.repoRoot
       });
       spinner.stop(pc.green('Sandbox image rebuilt'));
@@ -131,7 +115,11 @@ export async function rebuild(args: string[]): Promise<void> {
       runVerboseEngine(
         engine,
         'docker',
-        buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine, refresh }),
+        buildArgs(config, tools, preparedDockerfile.path, imageSignature, {
+          engine,
+          refresh,
+          lastRefresh
+        }),
         { cwd: config.repoRoot }
       );
       p.log.success(pc.green('Sandbox image rebuilt'));

package/lib/sandbox/config.ts

@@ -13,6 +13,7 @@ const DEFAULTS = Object.freeze({
   engine: null,
   runtimes: ['node22'],
   tools: ['agent-infra', 'claude-code', 'codex', 'gemini-cli', 'opencode'],
+  refreshIntervalDays: 7,
   dockerfile: null,
   vm: {
     cpu: null,
@@ -29,6 +30,7 @@ type SandboxConfigInput = {
   runtimes?: string[];
   tools?: string[];
   customTools?: unknown;
+  refreshIntervalDays?: unknown;
   dockerfile?: string | null;
   vm?: Record<string, unknown>;
 };
@@ -55,6 +57,7 @@ export type SandboxConfig = {
   runtimes: string[];
   tools: string[];
   customTools: SandboxTool[];
+  refreshIntervalDays: number;
   dockerfile: string | null;
   vm: SandboxVmConfig;
 };
@@ -80,11 +83,16 @@ function asPositiveNumberOrNull(value: unknown): number | null {
   return typeof value === 'number' ? value : null;
 }
 
-function cloneDefaults(): SandboxConfigInput & { vm: SandboxVmConfig; runtimes: string[]; tools: string[] } {
+function asNonNegativeIntegerOrDefault(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : fallback;
+}
+
+function cloneDefaults(): SandboxConfigInput & { vm: SandboxVmConfig; runtimes: string[]; tools: string[]; refreshIntervalDays: number } {
   return {
     engine: DEFAULTS.engine,
     runtimes: [...DEFAULTS.runtimes],
     tools: [...DEFAULTS.tools],
+    refreshIntervalDays: DEFAULTS.refreshIntervalDays,
     dockerfile: DEFAULTS.dockerfile,
     vm: { ...DEFAULTS.vm }
   };
@@ -160,6 +168,10 @@ export function loadConfig({
       ? [...sandbox.tools]
       : defaults.tools,
     customTools,
+    refreshIntervalDays: asNonNegativeIntegerOrDefault(
+      sandbox.refreshIntervalDays,
+      defaults.refreshIntervalDays
+    ),
     dockerfile,
     vm: {
       cpu: asPositiveNumberOrNull(sandbox.vm?.cpu) ?? defaults.vm.cpu,

package/lib/sandbox/constants.ts

@@ -107,6 +107,10 @@ export function sandboxImageConfigLabel(config: Pick<SandboxPathConfig, 'project
   return `${sandboxLabel(config)}.image-config`;
 }
 
+export function sandboxImageRefreshLabel(config: Pick<SandboxPathConfig, 'project'>): string {
+  return `${sandboxLabel(config)}.last-refresh`;
+}
+
 export function parsePositiveIntegerOption(value: unknown, optionName: string): number | undefined {
   if (value === undefined || value === null) {
     return undefined;