feat: Propagate isMainProgram flag to code generation

- Added isMainProgram flag to CompilerOptions
- Set flag in PerlLanguageProvider.executePerlCode()
- Modified loop handler to throw error directly when in main program's
  outermost loop instead of propagating via returnLabel
- Added RuntimeCode.throwControlFlowError() helper method for consistent
  error messages
- Main program loops now throw errors immediately, while subroutine loops
  still propagate to caller (Phase 4 catches it)

This optimizes error detection: main program errors are caught at the
loop handler level, while subroutine errors are caught at the boundary.

src/main/java/org/perlonjava/CompilerOptions.java

@@ -66,6 +66,7 @@ public class CompilerOptions implements Cloneable {
     public String debugFlags = ""; // For -D
     // Unicode/encoding flags for -C switches
     public boolean unicodeStdin = false; // -CS or -CI
+    public boolean isMainProgram = false; // True if this is the top-level main script
     public boolean unicodeStdout = false; // -CO
     public boolean unicodeStderr = false; // -CE
     public boolean unicodeInput = false; // -CI (same as stdin)

src/main/java/org/perlonjava/codegen/EmitForeach.java

@@ -254,13 +254,18 @@ public static void emitFor1(EmitterVisitor emitterVisitor, For1Node node) {
             // Get goto labels from current scope (TODO: implement getGotoLabels in EmitterContext)
             java.util.Map<String, org.objectweb.asm.Label> gotoLabels = null;  // For now
 
+            // Check if this is the outermost loop in the main program
+            boolean isMainProgramOutermostLoop = emitterVisitor.ctx.compilerOptions.isMainProgram 
+                    && parentLoopLabels == null;
+
             // Emit the handler
             emitControlFlowHandler(
                     mv,
                     currentLoopLabels,
                     parentLoopLabels,
                     emitterVisitor.ctx.javaClassInfo.returnLabel,
-                    gotoLabels);
+                    gotoLabels,
+                    isMainProgramOutermostLoop);
         }
 
         // Restore dynamic variable stack for our localization
@@ -307,13 +312,15 @@ public static void emitFor1(EmitterVisitor emitterVisitor, For1Node node) {
      * @param parentLoopLabels The parent loop's labels (null if this is the outermost loop)
      * @param returnLabel The subroutine's return label
      * @param gotoLabels Map of goto label names to ASM Labels in current scope
+     * @param isMainProgramOutermostLoop True if this is the outermost loop in main program (should throw error instead of returning)
      */
     private static void emitControlFlowHandler(
             MethodVisitor mv,
             LoopLabels loopLabels,
             LoopLabels parentLoopLabels,
             org.objectweb.asm.Label returnLabel,
-            java.util.Map<String, org.objectweb.asm.Label> gotoLabels) {
+            java.util.Map<String, org.objectweb.asm.Label> gotoLabels,
+            boolean isMainProgramOutermostLoop) {
 
         if (!ENABLE_LOOP_HANDLERS) {
             return;  // Feature not enabled yet
@@ -409,8 +416,43 @@ private static void emitControlFlowHandler(
         if (parentLoopLabels != null && parentLoopLabels.controlFlowHandler != null) {
             // Chain to parent loop's handler
             mv.visitJumpInsn(Opcodes.GOTO, parentLoopLabels.controlFlowHandler);
+        } else if (isMainProgramOutermostLoop) {
+            // Outermost loop in main program - throw error immediately
+            // Stack: [RuntimeControlFlowList]
+
+            // Cast to RuntimeControlFlowList
+            mv.visitTypeInsn(Opcodes.CHECKCAST, "org/perlonjava/runtime/RuntimeControlFlowList");
+            mv.visitInsn(Opcodes.DUP);
+
+            // Get control flow type
+            mv.visitMethodInsn(Opcodes.INVOKEVIRTUAL,
+                    "org/perlonjava/runtime/RuntimeControlFlowList",
+                    "getControlFlowType",
+                    "()Lorg/perlonjava/runtime/ControlFlowType;",
+                    false);
+            mv.visitInsn(Opcodes.DUP);
+
+            // Get label
+            mv.visitInsn(Opcodes.SWAP);
+            mv.visitMethodInsn(Opcodes.INVOKEVIRTUAL,
+                    "org/perlonjava/runtime/RuntimeControlFlowList",
+                    "getControlFlowLabel",
+                    "()Ljava/lang/String;",
+                    false);
+
+            // Call helper method to throw appropriate error
+            // Stack: [ControlFlowType, String label]
+            mv.visitMethodInsn(Opcodes.INVOKESTATIC,
+                    "org/perlonjava/runtime/RuntimeCode",
+                    "throwControlFlowError",
+                    "(Lorg/perlonjava/runtime/ControlFlowType;Ljava/lang/String;)V",
+                    false);
+
+            // Should never reach here (method throws), but add RETURN for verifier
+            mv.visitInsn(Opcodes.ACONST_NULL);
+            mv.visitInsn(Opcodes.ARETURN);
         } else {
-            // Outermost loop - return to caller
+            // Outermost loop in subroutine - return to caller (will be caught by Phase 4 or parent)
             mv.visitJumpInsn(Opcodes.GOTO, returnLabel);
         }
     }

src/main/java/org/perlonjava/runtime/RuntimeCode.java

@@ -1003,4 +1003,33 @@ public void dynamicRestoreState() {
         throw new PerlCompilerException("Can't modify anonymous subroutine");
     }
 
+    /**
+     * Helper method to throw appropriate control flow error.
+     * Called from loop handlers in main program when control flow escapes.
+     * 
+     * @param cfType The control flow type
+     * @param label The label (may be null)
+     * @throws PerlCompilerException Always throws with appropriate message
+     */
+    public static void throwControlFlowError(ControlFlowType cfType, String label) {
+        if (cfType == ControlFlowType.TAILCALL) {
+            // Tail call should have been handled by trampoline at returnLabel
+            throw new PerlCompilerException("Tail call escaped to top level (internal error) at ");
+        } else if (cfType == ControlFlowType.GOTO) {
+            if (label != null) {
+                throw new PerlCompilerException("Can't find label " + label + " at ");
+            } else {
+                throw new PerlCompilerException("goto must have a label at ");
+            }
+        } else {
+            // last/next/redo
+            String operation = cfType.name().toLowerCase();
+            if (label != null) {
+                throw new PerlCompilerException("Label not found for \"" + operation + " " + label + "\" at ");
+            } else {
+                throw new PerlCompilerException("Can't \"" + operation + "\" outside a loop block at ");
+            }
+        }
+    }
+
 }

src/main/java/org/perlonjava/scriptengine/PerlLanguageProvider.java

@@ -74,6 +74,9 @@ public static RuntimeList executePerlCode(CompilerOptions compilerOptions,
                                               boolean isTopLevelScript,
                                               int callerContext) throws Exception {
 
+        // Store the isMainProgram flag in CompilerOptions for use during code generation
+        compilerOptions.isMainProgram = isTopLevelScript;
+
         ScopedSymbolTable globalSymbolTable = new ScopedSymbolTable();
         // Enter a new scope in the symbol table and add special Perl variables
         globalSymbolTable.enterScope();