Fix: script-default visualizers not cleared in headless mode (--headless and HEADLESS=1)

[ChaitanyaParate]

Summary

Fixes a runtime crash in AppLauncher when a task script registers a default visualizer via parser.set_defaults(visualizer=["kit"]) and the process is launched in headless mode.

Fixes #7403

Root cause

_resolve_visualizer_settings incorrectly promoted set_defaults() values to explicit user intent (_cli_visualizer_explicit = True), even though the user never typed --viz on the command line.

Fix

• Instead of unconditionally clearing visualizers (which conflicts with develop's newly supported HEADLESS=1 + Kit visualizer livestreaming lifecycle), this PR fixes the root cause directly by tracking whether the arguments came from set_defaults.
• Added parser.set_defaults(visualizer_explicit=False) in add_app_launcher_args.
• Updated _resolve_visualizer_settings to correctly respect visualizer_explicit=False while preserving the presence-based fallback for programmatic kwargs (e.g., AppLauncher(visualizer=["kit"])).

Testing

• Added test_visualizer_argparse_set_defaults_is_not_explicit and test_visualizer_direct_kwargs_is_explicit to verify intent resolution logic.
• Updated test_matrix_headless_with_viz_names_takes_precedence to align with the new develop lifecycle (expecting visualizers not to be unconditionally cleared under headless modes).

Checklist

• Pre-commit hooks run and passed (./isaaclab.sh -f)
• Tests added / updated
• CHANGELOG.rst updated (via changelog fragment)

[greptile-apps]

Greptile Summary

This PR distinguishes script-defined argparse visualizer defaults from explicit --visualizer input so headless launches do not incorrectly enforce CLI visualizer behavior.

• Adds a non-explicit default marker when registering launcher arguments.
• Preserves presence-based intent detection for direct programmatic launcher kwargs.
• Adds coverage for argparse defaults, direct kwargs, aliases, and headless visualizer resolution.
• Documents the corrected headless-launch behavior.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete blocking or independently actionable non-blocking defects identified.

The new intent marker correctly separates parser defaults from explicit CLI input while retaining direct-kwargs detection, and downstream handling prevents non-explicit defaults from reaching the explicit-visualizer error path.

Important Files Changed

Filename	Overview
source/isaaclab/isaaclab/app/app_launcher.py	Introduces an argparse intent marker and updates visualizer resolution to distinguish parser defaults from explicit CLI or direct-kwargs selections.
source/isaaclab/test/app/test_kwarg_launch.py	Updates alias expectations and adds focused tests for visualizer intent and headless behavior.
source/isaaclab/changelog.d/chaitanya-fix-headless-visualizer-resolution.rst	Accurately documents the corrected handling of script-defined visualizer defaults.

_{Reviews (1): Last reviewed commit: "Fix headless visualizer bug related to p..." | Re-trigger Greptile}

[isaaclab-review-bot]

Isaac Lab Review Bot

The explicitness sentinel correctly distinguishes argparse defaults from explicit --viz input and direct kwargs, but it introduces a regression: a script-defined default such as visualizer=["kit"] no longer contributes to headless intent, so an ordinary launch is forced headless when visualizer_intent is absent.

• Design and architecture: The tri-state explicitness handling is appropriate, but script-defined visualizer defaults are demoted without being transferred to the existing configuration-intent path. Their selected backend remains recorded while headless resolution behaves as though no visualizer was selected.
• API: Explicit --viz and AppLauncher(visualizer=[...]) retain their existing explicit-selection behavior. However, the argparse integration surface changes materially: parser.set_defaults(visualizer=["kit"]) now causes a normal launch to resolve as headless unless the script separately supplies visualizer_intent.
• Implementation: Because visualizer_explicit=False bypasses the presence fallback, _resolve_headless_settings reaches its non-explicit branch and consults only _cfg_has_any_visualizers and _cfg_has_kit_visualizer. With no visualizer_intent, both are false, forcing headless even though _cli_visualizer_types contains kit. Non-explicit argparse defaults should feed the configuration-intent state or otherwise preserve their normal-launch semantics.

Minor fixes needed. Posted 1 actionable finding inline.

Automated review; human maintainers own approval decisions.

[isaaclab-review-bot]

🟡 Warning · Design Architecture — Script default visualizers now silently force headless

With visualizer_explicit=False always present in the parsed namespace, a script using parser.set_defaults(visualizer=["kit"]) takes the else branch of _resolve_headless_settings (lines 938-954). That branch consults only visualizer_intent, which such scripts do not set, so _headless becomes True even on a plain non-headless run, while _cli_visualizer_types still holds kit. Map non-explicit argparse visualizer defaults into _cfg_has_any_visualizers/_cfg_has_kit_visualizer instead of discarding them.

[ChaitanyaParate]

non-explicit argparse visualizer defaults are now properly mapped into _cfg_has_any_visualizers and _cfg_has_kit_visualizer

[AntoineRichard]

Thanks for digging into this. I tried to reproduce it before reviewing the code, and I don't think the bug is where the issue says it is.

The first repro command uses --headless, but that flag was removed from the CLI in 3.0. add_app_launcher_args doesn't register it anymore, and there's a test asserting the parser rejects it (test_argparser_launch.py:49). So it never reaches AppLauncher at all — you just get unrecognized arguments: --headless from Hydra.

The second one works fine for me on current develop:

HEADLESS=1 uv run python scripts/environments/zero_agent.py --task Isaac-Cartpole --num_envs 1 --max_steps 5

That exits 0, and the log shows the Kit visualizer being created and running headless. zero_agent goes through simple_agents.py:249, which is exactly the parser.set_defaults(visualizer=["kit"]) case, so it should be hitting the path you describe.

Tracing where the RuntimeError can actually come from: it's raised in _resolve_visualizer_cfgs only when _create_default_visualizer_configs fails to import isaaclab_visualizers.kit. That import is config-only, and isaaclab-visualizers is a hard workspace dependency, so on a normal install it can't fail. Could you paste the full traceback and the output of uv pip list | grep isaaclab? I suspect this is an environment problem rather than a logic one.

On the patch itself, it would cause a regression. Flipping set_defaults to non-explicit doesn't just relax the error check — it makes the whole idiom a no-op downstream. _resolve_visualizer_cfgs branches on cli_explicit, and when that's false it ignores the CLI types entirely and falls back to cfg.visualizer_cfgs, which defaults to []. The _cfg_has_* assignments you added only affect headless resolution inside AppLauncher; they're never published to carb, so SimulationContext doesn't see them.

I applied just the app_launcher.py hunk and reran the command above. The "Registered backend 'kit' for factory Visualizer" line and the KitVisualizer startup warning both disappear — no visualizer gets created. About 30 scripts use this idiom (most of scripts/demos, scripts/tutorials, and the simple agents), so they'd all launch a Kit window with nothing driving it.

One thing in here is worth keeping, though. test_kwarg_launch.py is already failing on develop, and it's the same four tests you touched. Three are newton → newton_gl alias fallout where the assertions were never updated, and test_matrix_headless_with_viz_names_takes_precedence feeds headless=True into _resolve_visualizer_settings, which stopped honoring it when --headless was deprecated. Those are real and we should fix them, but as a standalone PR — and I'd delete the headless one rather than flip its expectations, since it covers a path that no longer exists.

@matthewtrepte for viz.

[AntoineRichard]

Will not merge unless more information is provided.

[ChaitanyaParate]

I am closing this PR because the root diagnosis was incorrect. As confirmed by a clean-install reproduction, the RuntimeError regarding explicit visualizer intent was not a logic bug in AppLauncher. It was caused by an environment misconfiguration where the isaaclab_visualizers extension failed to load, which masqueraded as a config failure. The proposed fix in this PR would cause a regression by disabling kit visualizer initialization for all non-headless runs that rely on script defaults.

For the full explanation of the root cause, please see the update in #7403.

I have extracted the valid test fixes (the newton_gl alias fallout) into a separate branch and will submit them as a new, standalone PR.