feat(status-bar): import Claude Code status aggregator behind spawnTerm flag

[carvalhoviniciusluiz]

Closes #58

Summary

Imports the Claude Code session-status aggregator status-bar component from upstream gnachman#648, gated behind a new spawnTerm feature flag so it is OFF by default and only offered when explicitly enabled.

The component aggregates Claude Code session statuses (Waiting / Working… / Idle) across all windows, showing a summary in the status bar and a clickable popover listing each session (click a row to reveal that session).

Feature flag (new): spawnterm.claude_statusbar — default OFF

Wired in all three synced places plus docs:

• spawnterm/flags/spawnterm-flag — added to the shell KNOWN_FLAGS.
• spawnterm/flags/spawnterm_flag.py — added to the KNOWN_FLAGS dict with a one-line description.
• sources/Settings/iTermSpawnTermCapabilities.m — added to both capabilityIdentifiers and the displayNameForCapability: map ("Claude Code Status Bar"), so it renders as a checkbox in Settings → General → AI → spawnTerm.
• spawnterm/docs/feature-flags.md — added to the seeded-schema example and the flag-schema table.

Shell/Python parity verified: bash spawnterm/flags/tests/test_flags.sh → PASS=26 FAIL=0 (includes byte-for-byte config parity, which fails if the two KNOWN_FLAGS diverge).

Where activation is gated

In sources/StatusBar/Setup/iTermStatusBarSetupViewController.m -loadElements, the component class is appended to the offered-components list only when [iTermSpawnTermCapabilities isEnabledForCapability:@"claude_statusbar"] returns YES (header imported). When the flag is OFF (default), the component is not offered or registered — stock behavior is unchanged.

Files changed

• sources/StatusBar/Components/iTermStatusBarClaudeCodeComponent.swift (new)
• sources/StatusBar/Components/ClaudeCodeStatusPopoverViewController.swift (new)
• ModernTests/ClaudeCodeSummaryBuilderTests.swift (new; ModernTests is a fileSystemSynchronizedGroups target, so no pbxproj entry is needed)
• sources/StatusBar/Setup/iTermStatusBarSetupViewController.m (gated registration + import)
• sources/Settings/iTermSpawnTermCapabilities.m (flag)
• iTerm2.xcodeproj/project.pbxproj (two source files registered to iTerm2SharedARC via tools/add_file_to_xcodeproj.rb; 8 lines, both in the Sources phase — no .h in a compile phase)
• spawnterm/flags/spawnterm-flag, spawnterm/flags/spawnterm_flag.py, spawnterm/docs/feature-flags.md, docs/notes-3.7.txt

No submodule pointers, ThirdParty/, or version-stamp artifacts were committed.

Provenance

Adapted from upstream gnachman#648 ("status-bar: Claude Code session status aggregator component"). The upstream PR's 9 commits were squashed via gh pr diff 648 --patch and applied with git apply --reject.

• The three new files applied cleanly (all upstream follow-up edits included) and were moved into this fork's sources/StatusBar/Components/ layout.
• The upstream iTerm2.xcodeproj/project.pbxproj hunks were rejected (our fork's project differs); the two files were instead registered with tools/add_file_to_xcodeproj.rb … iTerm2SharedARC, matching how upstream added them (build file + file ref + group + Sources phase).
• The upstream iTermStatusBarSetupViewController.m hunk did not apply (our file lives at sources/StatusBar/Setup/); the change was re-applied by hand and gated on the feature flag.

Adaptation for our tree

PTYSession.name is nonnull in this fork (inside NS_ASSUME_NONNULL), so upstream's session.name ?? sessionID would trigger a "non-optional left side of nil-coalescing" warning under warnings-as-errors. Replaced with an empty-string fallback that preserves the intent. All other APIs used by the imported code (iTermSessionTabStatus, SessionStatusController.instance + observer signature, NotifyingDictionary.values, revealSession(withGUID:), session(withGUID:), iTermStatusBarTextComponent overrides, status-bar position prefs) were verified present in this tree.

Build status — HONEST

Not a green build. This environment cannot compile iTerm2. tools/build.sh Development fails during the dependency phase, before any iTerm2 source is reached:

Companion/CompanionCore/Sources/CNoise/shim/cnoise_stubs.c:27:10: error: 'noise/protocol.h' file not found (in target 'CNoise' from project 'CompanionCore')

The CNoise C target (a CompanionCore dependency) builds before the iTerm2SharedARC sources, so the newly added Swift files never reach the compiler here. The change is therefore verified correct-by-inspection against the current tree (APIs confirmed, pbxproj/target wiring confirmed, flag parity tests green), not by a successful compile.

🤖 Generated with Claude Code

[carvalhoviniciusluiz]

Review by tech-lead — code APPROVED by inspection; build UNVERIFIED (environment).

Import do upstream gnachman#648 adaptado à nossa árvore (pbxproj rejeitado → add_file_to_xcodeproj.rb; setup VC re-aplicado à mão; arquivos movidos p/ sources/StatusBar/Components; ajuste nonnull p/ warnings=erros). Higiene limpa (sem vazamento).

• Flag spawnterm.claude_statusbar (default OFF) em shell + py + iTermSpawnTermCapabilities (capabilityIdentifiers + displayName) + docs; flags parity 26/26 → aparece como checkbox na aba AI→spawnTerm (spawnTerm settings pane (AI tab) — GUI to toggle the feature-flags #12).
• Gate correto: em iTermStatusBarSetupViewController -loadElements, o componente só é oferecido quando isEnabledForCapability:@"claude_statusbar" → OFF = stock inalterado.
• ModernTests ClaudeCodeSummaryBuilderTests incluído. Proveniência: Adapted from upstream ✨ feat(status-bar): add Claude Code session status aggregator component gnachman/iTerm2#648.
  Build não verificável aqui (submódulo CNoise). Sem ressalvas.