fix(onboard): show base image pull heartbeat

Signed-off-by: Ho Lim <subhoya@gmail.com>

Author: HOYALIM

src/lib/sandbox-base-image-resolution.test.ts

@@ -21,6 +21,9 @@ const sourceMocks = vi.hoisted(() => ({
   inputsChanged: vi.fn(),
   nearestTags: vi.fn(),
 }));
+const heartbeatMocks = vi.hoisted(() => ({
+  run: vi.fn((operation: () => unknown, _options?: { activity?: string }) => operation()),
+}));
 
 vi.mock("./adapters/docker", () => ({
   dockerBuild: dockerMocks.build,
@@ -35,6 +38,10 @@ vi.mock("./trace", () => ({
   addTraceEvent: traceMocks.add,
 }));
 
+vi.mock("./sandbox-base-image/local-build-heartbeat", () => ({
+  withLocalBuildHeartbeat: heartbeatMocks.run,
+}));
+
 vi.mock("./sandbox-base-image/source-identity", async (importOriginal) => ({
   ...(await importOriginal<typeof import("./sandbox-base-image/source-identity")>()),
   baseImageInputsDirty: sourceMocks.inputsDirty,
@@ -179,6 +186,8 @@ describe("sandbox base-image warm resolution", () => {
     ).toBeNull();
     expect(dockerMocks.imageInspect).toHaveBeenCalled();
     expect(dockerMocks.pull).toHaveBeenCalled();
+    expect(heartbeatMocks.run).toHaveBeenCalledTimes(dockerMocks.pull.mock.calls.length);
+    expect(heartbeatMocks.run.mock.calls.every((call) => call[1]?.activity === "pull")).toBe(true);
     expect(traceMocks.add).toHaveBeenCalledWith("nemoclaw.sandbox_base_image.cache_miss", {
       has_hint: true,
     });

src/lib/sandbox-base-image.ts

@@ -336,7 +336,7 @@ function resolvePulledCandidate(
         : "nemoclaw.sandbox_base_image.remote_pull",
       { source },
     );
-    const pullResult = dockerPull(imageRef, { ignoreError: true, suppressOutput: true });
+    const pullResult = pullSandboxBaseImage(imageRef);
     if (pullResult.status !== 0) return null;
   }
 
@@ -356,14 +356,21 @@ function resolvePulledCandidate(
     imageRefCanRefresh(imageRef)
   ) {
     addTraceEvent("nemoclaw.sandbox_base_image.remote_refresh", { source });
-    const pullResult = dockerPull(imageRef, { ignoreError: true, suppressOutput: true });
+    const pullResult = pullSandboxBaseImage(imageRef);
     if (pullResult.status !== 0) return null;
     return validatePulledCandidate(imageName, imageRef, source, options, candidateOptions, true);
   }
 
   return null;
 }
 
+function pullSandboxBaseImage(imageRef: string) {
+  return withLocalBuildHeartbeat(
+    () => dockerPull(imageRef, { ignoreError: true, suppressOutput: true }),
+    { activity: "pull" },
+  );
+}
+
 function resolveLocalCandidate(
   options: ResolveBaseImageOptions,
   forceBuild = false,

src/lib/sandbox-base-image/local-build-heartbeat.ts

@@ -4,32 +4,38 @@
 import { spawn } from "node:child_process";
 
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
-const HEARTBEAT_CHILD_SCRIPT = [
-  "const intervalMs = Number(process.argv[1]);",
-  "const parentPid = Number(process.argv[2]);",
-  "const startedAt = Date.now();",
-  "const stop = () => process.exit(0);",
-  'process.on("SIGINT", stop);',
-  'process.on("SIGTERM", stop);',
-  "setInterval(() => {",
-  "  try { process.kill(parentPid, 0); } catch { stop(); return; }",
-  "  const elapsedSeconds = Math.max(0, Math.round((Date.now() - startedAt) / 1000));",
-  "  process.stdout.write(`  ⏳ Still working on sandbox base image build… (${elapsedSeconds}s elapsed)\\n`);",
-  "}, intervalMs);",
-].join("\n");
+
+type HeartbeatActivity = "build" | "pull";
+
+function heartbeatChildScript(activity: HeartbeatActivity): string {
+  return [
+    "const intervalMs = Number(process.argv[1]);",
+    "const parentPid = Number(process.argv[2]);",
+    "const startedAt = Date.now();",
+    "const stop = () => process.exit(0);",
+    'process.on("SIGINT", stop);',
+    'process.on("SIGTERM", stop);',
+    "setInterval(() => {",
+    "  try { process.kill(parentPid, 0); } catch { stop(); return; }",
+    "  const elapsedSeconds = Math.max(0, Math.round((Date.now() - startedAt) / 1000));",
+    `  process.stdout.write(\`  ⏳ Still working on sandbox base image ${activity}… (\${elapsedSeconds}s elapsed)\\n\`);`,
+    "}, intervalMs);",
+  ].join("\n");
+}
 
 type SpawnHeartbeat = typeof spawn;
 
 export interface LocalBuildHeartbeatOptions {
+  activity?: HeartbeatActivity;
   intervalMs?: number;
   nodeExecutable?: string;
   parentPid?: number;
   spawnImpl?: SpawnHeartbeat;
 }
 
-/** Keep quiet synchronous Docker builds observable without exposing their captured logs. */
+/** Keep quiet synchronous Docker work observable without exposing its captured logs. */
 export function withLocalBuildHeartbeat<T>(
-  build: () => T,
+  operation: () => T,
   options: LocalBuildHeartbeatOptions = {},
 ): T {
   const intervalMs =
@@ -40,7 +46,12 @@ export function withLocalBuildHeartbeat<T>(
   try {
     child = (options.spawnImpl ?? spawn)(
       options.nodeExecutable ?? process.execPath,
-      ["-e", HEARTBEAT_CHILD_SCRIPT, String(intervalMs), String(options.parentPid ?? process.pid)],
+      [
+        "-e",
+        heartbeatChildScript(options.activity ?? "build"),
+        String(intervalMs),
+        String(options.parentPid ?? process.pid),
+      ],
       { env: {}, stdio: ["ignore", "inherit", "inherit"] },
     );
     child.on("error", () => undefined);
@@ -50,12 +61,12 @@ export function withLocalBuildHeartbeat<T>(
   }
 
   try {
-    return build();
+    return operation();
   } finally {
     try {
       child?.kill("SIGTERM");
     } catch {
-      // Progress reporting must never replace the Docker build result.
+      // Progress reporting must never replace the Docker operation result.
     }
   }
 }