fix: transport AppImage args via env and gate restart on app-ping

- Transport Linux AppImage CLI args through SUBMINER_APP_ARGC/ARG_* env vars instead of argv
- Add --app-ping command to probe single-instance lock ownership (exit 0 = running, 1 = not)
- Gate manual restart: poll app-ping until old app releases lock, then until new app owns it
- Preserve user-paused playback when disarming the auto-play-ready gate on restart
- Snapshot subtitles before connection side effects (sub-visibility hide) can suppress them
- Reapply overlay bounds after first show for Hyprland compatibility

launcher/mpv.test.ts

@@ -114,6 +114,36 @@ test('runAppCommandCaptureOutput strips ELECTRON_RUN_AS_NODE from app child env'
   }
 });
 
+test('runAppCommandCaptureOutput transports Linux AppImage args through environment', () => {
+  if (process.platform !== 'linux') return;
+  const { dir } = createTempSocketPath();
+  const appPath = path.join(dir, 'SubMiner.AppImage');
+  fs.writeFileSync(
+    appPath,
+    [
+      '#!/bin/sh',
+      'printf "args:%s\\n" "$*"',
+      'printf "argc:%s\\n" "$SUBMINER_APP_ARGC"',
+      'printf "arg0:%s\\n" "$SUBMINER_APP_ARG_0"',
+      'printf "arg1:%s\\n" "$SUBMINER_APP_ARG_1"',
+      '',
+    ].join('\n'),
+  );
+  fs.chmodSync(appPath, 0o755);
+
+  try {
+    const result = runAppCommandCaptureOutput(appPath, ['--app-ping', '--socket']);
+
+    assert.equal(result.status, 0);
+    assert.match(result.stdout, /^args:\n/m);
+    assert.match(result.stdout, /^argc:2\n/m);
+    assert.match(result.stdout, /^arg0:--app-ping\n/m);
+    assert.match(result.stdout, /^arg1:--socket\n/m);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('parseMpvArgString preserves empty quoted tokens', () => {
   assert.deepEqual(parseMpvArgString('--title "" --force-media-title \'\' --pause'), [
     '--title',

launcher/mpv.ts

@@ -39,6 +39,7 @@ export const state = {
 type SpawnTarget = {
   command: string;
   args: string[];
+  env?: NodeJS.ProcessEnv;
 };
 
 type PathModule = Pick<typeof path, 'join' | 'extname' | 'delimiter' | 'sep' | 'resolve'>;
@@ -46,6 +47,8 @@ type PathModule = Pick<typeof path, 'join' | 'extname' | 'delimiter' | 'sep' | '
 const DETACHED_IDLE_MPV_PID_FILE = path.join(os.tmpdir(), 'subminer-idle-mpv.pid');
 const OVERLAY_START_SOCKET_READY_TIMEOUT_MS = 900;
 const OVERLAY_START_COMMAND_SETTLE_TIMEOUT_MS = 700;
+const TRANSPORTED_APP_ARGC_ENV = 'SUBMINER_APP_ARGC';
+const TRANSPORTED_APP_ARG_PREFIX = 'SUBMINER_APP_ARG_';
 
 export interface LauncherRuntimePluginPlan {
   scriptPath: string | null;
@@ -1009,7 +1012,7 @@ export async function startOverlay(
   const target = resolveAppSpawnTarget(appPath, overlayArgs);
   state.overlayProc = spawn(target.command, target.args, {
     stdio: ['ignore', 'pipe', 'pipe'],
-    env: buildAppEnv(),
+    env: buildAppEnv(process.env, target.env),
   });
   attachAppProcessLogging(state.overlayProc);
   markOverlayManagedByLauncher(appPath);
@@ -1146,7 +1149,7 @@ function stopManagedOverlayApp(args: Args): void {
   const target = resolveAppSpawnTarget(state.appPath, stopArgs);
   const result = spawnSync(target.command, target.args, {
     stdio: 'ignore',
-    env: buildAppEnv(),
+    env: buildAppEnv(process.env, target.env),
   });
   if (result.error) {
     log('warn', args.logLevel, `Failed to stop SubMiner overlay: ${result.error.message}`);
@@ -1163,13 +1166,40 @@ function stopManagedOverlayApp(args: Args): void {
   }
 }
 
-function buildAppEnv(baseEnv: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+function clearTransportedAppArgs(env: Record<string, string | undefined>): void {
+  for (const key of Object.keys(env)) {
+    if (key === TRANSPORTED_APP_ARGC_ENV || /^SUBMINER_APP_ARG_\d+$/.test(key)) {
+      delete env[key];
+    }
+  }
+}
+
+function buildTransportedAppArgsEnv(appArgs: string[]): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {
+    [TRANSPORTED_APP_ARGC_ENV]: String(appArgs.length),
+  };
+  appArgs.forEach((arg, index) => {
+    env[`${TRANSPORTED_APP_ARG_PREFIX}${index}`] = arg;
+  });
+  return env;
+}
+
+function shouldTransportAppArgsForAppImage(appPath: string): boolean {
+  return process.platform === 'linux' && /\.AppImage$/i.test(appPath);
+}
+
+function buildAppEnv(
+  baseEnv: NodeJS.ProcessEnv = process.env,
+  extraEnv: NodeJS.ProcessEnv = {},
+): NodeJS.ProcessEnv {
   const env: Record<string, string | undefined> = {
     ...baseEnv,
     SUBMINER_APP_LOG: getAppLogPath(),
     SUBMINER_MPV_LOG: getMpvLogPath(),
   };
   delete env.ELECTRON_RUN_AS_NODE;
+  clearTransportedAppArgs(env);
+  Object.assign(env, extraEnv);
   const layers = env.VK_INSTANCE_LAYERS;
   if (typeof layers === 'string' && layers.trim().length > 0) {
     const filtered = layers
@@ -1274,7 +1304,7 @@ function runSyncAppCommand(
 } {
   const target = resolveAppSpawnTarget(appPath, appArgs);
   const result = spawnSync(target.command, target.args, {
-    env: buildAppEnv(),
+    env: buildAppEnv(process.env, target.env),
     encoding: 'utf8',
   });
   if (result.stdout) {
@@ -1307,6 +1337,13 @@ function maybeCaptureAppArgs(appArgs: string[]): boolean {
 }
 
 function resolveAppSpawnTarget(appPath: string, appArgs: string[]): SpawnTarget {
+  if (shouldTransportAppArgsForAppImage(appPath)) {
+    return {
+      command: appPath,
+      args: [],
+      env: buildTransportedAppArgsEnv(appArgs),
+    };
+  }
   if (process.platform !== 'win32') {
     return { command: appPath, args: appArgs };
   }
@@ -1321,7 +1358,7 @@ export function runAppCommandWithInherit(appPath: string, appArgs: string[]): vo
   const target = resolveAppSpawnTarget(appPath, appArgs);
   const proc = spawn(target.command, target.args, {
     stdio: ['ignore', 'pipe', 'pipe'],
-    env: buildAppEnv(),
+    env: buildAppEnv(process.env, target.env),
   });
   attachAppProcessLogging(proc, { mirrorStdout: true, mirrorStderr: true });
   proc.once('error', (error) => {
@@ -1340,7 +1377,7 @@ export function runAppCommandSilently(appPath: string, appArgs: string[]): void
   const target = resolveAppSpawnTarget(appPath, appArgs);
   const proc = spawn(target.command, target.args, {
     stdio: ['ignore', 'pipe', 'pipe'],
-    env: buildAppEnv(),
+    env: buildAppEnv(process.env, target.env),
   });
   attachAppProcessLogging(proc);
   proc.once('error', (error) => {
@@ -1391,7 +1428,7 @@ export function runAppCommandAttached(
   return new Promise((resolve, reject) => {
     const proc = spawn(target.command, target.args, {
       stdio: ['ignore', 'pipe', 'pipe'],
-      env: buildAppEnv(),
+      env: buildAppEnv(process.env, target.env),
     });
     attachAppProcessLogging(proc, { mirrorStdout: true, mirrorStderr: true });
     proc.once('error', (error) => {
@@ -1462,7 +1499,7 @@ export function launchAppCommandDetached(
     const proc = spawn(target.command, target.args, {
       stdio: ['ignore', stdoutFd, stderrFd],
       detached: true,
-      env: buildAppEnv(),
+      env: buildAppEnv(process.env, target.env),
     });
     proc.once('error', (error) => {
       log('warn', logLevel, `${label}: failed to launch detached app: ${error.message}`);