feat: stabilize startup sync and overlay/runtime paths

launcher/commands/command-modules.test.ts

@@ -159,6 +159,40 @@ test('stats command launches attached app command with response path', async ()
   ]);
 });
 
+test('stats command returns after startup response even if app process stays running', async () => {
+  const context = createContext();
+  context.args.stats = true;
+  const forwarded: string[][] = [];
+  const started = new Promise<number>((resolve) => setTimeout(() => resolve(0), 20));
+
+  const statsCommand = runStatsCommand(context, {
+    createTempDir: () => '/tmp/subminer-stats-test',
+    joinPath: (...parts) => parts.join('/'),
+    runAppCommandAttached: async (_appPath, appArgs) => {
+      forwarded.push(appArgs);
+      return started;
+    },
+    waitForStatsResponse: async () => ({ ok: true, url: 'http://127.0.0.1:5175' }),
+    removeDir: () => {},
+  });
+  const result = await Promise.race([
+    statsCommand.then(() => 'resolved'),
+    new Promise<'timeout'>((resolve) => setTimeout(() => resolve('timeout'), 5)),
+  ]);
+
+  assert.equal(result, 'timeout');
+
+  const final = await statsCommand;
+  assert.equal(final, true);
+  assert.deepEqual(forwarded, [
+    [
+      '--stats',
+      '--stats-response-path',
+      '/tmp/subminer-stats-test/response.json',
+    ],
+  ]);
+});
+
 test('stats cleanup command forwards cleanup vocab flags to the app', async () => {
   const context = createContext();
   context.args.stats = true;
@@ -189,6 +223,36 @@ test('stats cleanup command forwards cleanup vocab flags to the app', async () =
   ]);
 });
 
+test('stats cleanup command forwards lifetime rebuild flag to the app', async () => {
+  const context = createContext();
+  context.args.stats = true;
+  context.args.statsCleanup = true;
+  context.args.statsCleanupLifetime = true;
+  const forwarded: string[][] = [];
+
+  const handled = await runStatsCommand(context, {
+    createTempDir: () => '/tmp/subminer-stats-test',
+    joinPath: (...parts) => parts.join('/'),
+    runAppCommandAttached: async (_appPath, appArgs) => {
+      forwarded.push(appArgs);
+      return 0;
+    },
+    waitForStatsResponse: async () => ({ ok: true }),
+    removeDir: () => {},
+  });
+
+  assert.equal(handled, true);
+  assert.deepEqual(forwarded, [
+    [
+      '--stats',
+      '--stats-response-path',
+      '/tmp/subminer-stats-test/response.json',
+      '--stats-cleanup',
+      '--stats-cleanup-lifetime',
+    ],
+  ]);
+});
+
 test('stats command throws when stats response reports an error', async () => {
   const context = createContext();
   context.args.stats = true;
@@ -207,9 +271,11 @@ test('stats command throws when stats response reports an error', async () => {
   }, /Immersion tracking is disabled in config\./);
 });
 
-test('stats command fails if attached app exits before startup response', async () => {
+test('stats cleanup command fails if attached app exits before startup response', async () => {
   const context = createContext();
   context.args.stats = true;
+  context.args.statsCleanup = true;
+  context.args.statsCleanupVocab = true;
 
   await assert.rejects(async () => {
     await runStatsCommand(context, {

launcher/commands/stats-command.ts

@@ -24,13 +24,15 @@ type StatsCommandDeps = {
   removeDir: (targetPath: string) => void;
 };
 
+const STATS_STARTUP_RESPONSE_TIMEOUT_MS = 8_000;
+
 const defaultDeps: StatsCommandDeps = {
   createTempDir: (prefix) => fs.mkdtempSync(path.join(os.tmpdir(), prefix)),
   joinPath: (...parts) => path.join(...parts),
   runAppCommandAttached: (appPath, appArgs, logLevel, label) =>
     runAppCommandAttached(appPath, appArgs, logLevel, label),
   waitForStatsResponse: async (responsePath) => {
-    const deadline = Date.now() + 8000;
+    const deadline = Date.now() + STATS_STARTUP_RESPONSE_TIMEOUT_MS;
     while (Date.now() < deadline) {
       try {
         if (fs.existsSync(responsePath)) {
@@ -71,20 +73,46 @@ export async function runStatsCommand(
     if (args.statsCleanupVocab) {
       forwarded.push('--stats-cleanup-vocab');
     }
+    if (args.statsCleanupLifetime) {
+      forwarded.push('--stats-cleanup-lifetime');
+    }
     if (args.logLevel !== 'info') {
       forwarded.push('--log-level', args.logLevel);
     }
-    const attachedExitPromise = deps.runAppCommandAttached(
-      appPath,
-      forwarded,
-      args.logLevel,
-      'stats',
-    );
+    const attachedExitPromise = deps.runAppCommandAttached(appPath, forwarded, args.logLevel, 'stats');
+
+    if (!args.statsCleanup) {
+      const startupResult = await Promise.race([
+        deps
+          .waitForStatsResponse(responsePath)
+          .then((response) => ({ kind: 'response' as const, response })),
+        attachedExitPromise.then((status) => ({ kind: 'exit' as const, status })),
+      ]);
+      if (startupResult.kind === 'exit') {
+        if (startupResult.status !== 0) {
+          throw new Error(
+            `Stats app exited before startup response (status ${startupResult.status}).`,
+          );
+        }
+        const response = await deps.waitForStatsResponse(responsePath);
+        if (!response.ok) {
+          throw new Error(response.error || 'Stats dashboard failed to start.');
+        }
+        return true;
+      }
+      if (!startupResult.response.ok) {
+        throw new Error(startupResult.response.error || 'Stats dashboard failed to start.');
+      }
+      await attachedExitPromise;
+      return true;
+    }
+    const attachedExitPromiseCleanup = attachedExitPromise;
+
     const startupResult = await Promise.race([
       deps
         .waitForStatsResponse(responsePath)
         .then((response) => ({ kind: 'response' as const, response })),
-      attachedExitPromise.then((status) => ({ kind: 'exit' as const, status })),
+      attachedExitPromiseCleanup.then((status) => ({ kind: 'exit' as const, status })),
     ]);
     if (startupResult.kind === 'exit') {
       if (startupResult.status !== 0) {
@@ -101,7 +129,7 @@ export async function runStatsCommand(
     if (!startupResult.response.ok) {
       throw new Error(startupResult.response.error || 'Stats dashboard failed to start.');
     }
-    const exitStatus = await attachedExitPromise;
+    const exitStatus = await attachedExitPromiseCleanup;
     if (exitStatus !== 0) {
       throw new Error(`Stats app exited with status ${exitStatus}.`);
     }