bug: --background doesn't suppress macOS app-foregrounding when creating tabs

[voidfreud]

Root cause (found via investigation — see comment)

--background was designed to prevent iTerm2 from re-focusing a different session within itself. It never handled macOS raising iTerm2.app to the foreground when a new tab materialises. capture_focus / restore_focus in src/ita/_core.py:303-349 only snapshot and restore the iTerm2-internal focused session — they never capture or restore the macOS frontmost application.

Observation: During agent runs, Alex's focus was stolen by iTerm2 coming to the front each time a tab was created. PR #392's env var / --background flag all worked as designed. The env-var plumbing was never the bug.

Scope

Affects every use of ita new / ita tab new / ita layout ... — including real agent workflows, not just tests. When an agent creates a tab while user is in another app, macOS raises iTerm2 to foreground.

Proposed fix (proper)

Extend capture_focus / restore_focus to also preserve the macOS frontmost app:

• Option A (PyObjC): NSWorkspace.sharedWorkspace().frontmostApplication() → store in FocusSnapshot → NSRunningApplication.activateWithOptions_ to restore. Requires PyObjC as a dep.
• Option B (osascript shell-out): osascript -e 'tell application "System Events" to get name of first process whose frontmost is true' → store → osascript -e 'tell application "X" to activate' to restore. No new dep, small subprocess overhead per creation.

Option B is probably the cleaner near-term fit (no new dep, ita already uses osascript in a few places). Option A is cleaner long-term if PyObjC is already transitively pulled.

Priority

Medium-high. Real UX impact beyond tests.

Related

• bug: fast-lane tests spawn iTerm2 windows/tabs despite CliRunner migration (PR #358) #394 / PR fix(#394): mark iTerm2-touching tests as integration-only (fast-lane becomes hermetic) #395 — fast-lane hermetic (would have guarded this, but integration tests shouldn't run by default)
• test-ux: fixtures don't use --background, steal focus during test runs #379 / PR fix: test-UX bundle — #379 #380 #383 #384 #392 — ITA_DEFAULT_BACKGROUND env var (working as designed)
• dx: agent prompt discipline — rule-4 agent ran broader integration suite beyond scope #402 — agent prompt discipline (avoids triggering this class of issue in tests)
• feat(#346): --background flag on creation commands (CONTRACT §1, §10) #356 — original --background flag

[voidfreud]

Investigation report (read-only agent, 2026-04-14):

Env-var reach (all working)

• Read sites: src/ita/_session.py:79, _tab.py:34, _layout.py:32
• Propagation: conftest os.environ.setdefault → subprocess inherits (no env= override in helpers.ita())
• All three CLI creation paths (new / tab new / layout) flip background=True and call capture_focus / restore_focus correctly.

Which tests produced the 17 tabs

• tests/test_invariant_mutators_honor_protection.py (7 inventory + 8 extras = 15 parametrisations)
• tests/test_invariant_mutators_honor_locking.py (7 mutators)
• Both marked @pytest.mark.integration — should NOT have been run in scope. Root scope-creep = dx: agent prompt discipline — rule-4 agent ran broader integration suite beyond scope #402.
• Both use session / protected_session fixture → go through CLI ita new path → env var applied.

Why --background didn't prevent focus theft

capture_focus only preserves iTerm2-internal focused session. iTerm2.app itself comes to macOS foreground on tab creation, and that's never suppressed. See title + proposed fix.