feat(ego-lint): add stage/messageTray actor leak detection (R-LIFE-22, R-LIFE-24)

R-LIFE-22 (blocking): Detects global.stage.add_child(), addTopChrome(),
and addChrome() without matching removal or .destroy() in cleanup methods.
Supersedes R-LIFE-19 (advisory pattern rule) with smarter Tier 2 check.

R-LIFE-24 (advisory): Detects Main.messageTray.add() without matching
.destroy() in cleanup methods.

Both checks extract cleanup method bodies (disable/destroy/_destroy*/
onDestroy) and verify each tracked this._xxx variable has proper cleanup.
Null assignment alone is NOT valid cleanup for stage actors.

Closes #36

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ZviBaratz

field-tests/annotations/clipboard-indicator.yaml

@@ -76,10 +76,10 @@ findings:
   - id: "resource-tracking/ownership::orphan detected"
     classification: tp
     notes: "1 orphan detected — correct"
-  # ego-review blocking issues
-  - id: "lifecycle::_historyLabel on global.stage never removed"
+  # stage/messageTray actor leaks (now detected by ego-lint)
+  - id: "lifecycle/stage-actor-leak::this._historyLabel"
     classification: tp
-    notes: "B1: Actor leak on every enable/disable cycle — ego-review finding"
-  - id: "lifecycle::_notifSource never destroyed in disable()"
+    notes: "B1: Actor leak on every enable/disable cycle — now detected by R-LIFE-22"
+  - id: "lifecycle/messagetray-source-leak::this._notifSource"
     classification: tp
-    notes: "B2: Notification source persists — ego-review finding"
+    notes: "B2: Notification source persists — now detected by R-LIFE-24"

rules/patterns.yaml

@@ -790,14 +790,6 @@
 # --- Lifecycle (advisory) ---
 # Pattern-based lifecycle checks (complement script-based checks in check-lifecycle.py).
 
-- id: R-LIFE-19
-  pattern: "global\\.stage\\.add_child\\s*\\("
-  scope: ["*.js"]
-  severity: advisory
-  message: "global.stage.add_child() — ensure matching remove_child() in disable()/destroy()"
-  category: lifecycle
-  fix: "In disable(), call global.stage.remove_child(this._actor); this._actor = null;"
-
 # --- GNOME 44-46 migration (version-gated) ---
 # APIs removed or renamed in GNOME 44-46 transition to ESM.
 

skills/ego-lint/references/rules-reference.md

@@ -2049,13 +2049,22 @@ Rules for APIs removed or changed in specific GNOME Shell versions. These rules
 - **Fix**: Add `this._session.abort()` before nullifying the session reference in `disable()`.
 - **Tested by**: `tests/fixtures/soup-session-no-abort@test/`
 
-### R-LIFE-19: global.stage.add_child() without matching remove_child()
+### R-LIFE-22: Stage/chrome actor leak (add without remove)
+- **Severity**: blocking
+- **Checked by**: check-lifecycle.py
+- **Rule**: `global.stage.add_child()`, `Main.layoutManager.addTopChrome()`, and `Main.layoutManager.addChrome()` must have a matching removal (`remove_child`/`removeTopChrome`/`removeChrome`) or `.destroy()` in `disable()`/`destroy()`. Only tracks `this._xxx` patterns.
+- **Rationale**: Actors added to `global.stage` or the layout manager chrome persist on the compositor stage across enable/disable cycles. Unlike container widgets that are destroyed with their parent, stage children must be explicitly removed or they leak — causing visible artifacts and memory growth. Nulling the reference (`this._actor = null`) does NOT remove the actor from the stage.
+- **Fix**: In `disable()`, call `global.stage.remove_child(this._actor); this._actor.destroy(); this._actor = null;` or just `this._actor.destroy()` (destroying a Clutter actor removes it from its parent).
+- **Tested by**: `tests/fixtures/stage-add-child@test/`, `tests/fixtures/stage-add-child-clean@test/` (negative)
+- **Supersedes**: R-LIFE-19 (advisory pattern rule)
+
+### R-LIFE-24: MessageTray source leak (add without destroy)
 - **Severity**: advisory
-- **Checked by**: apply-patterns.py
-- **Rule**: `global.stage.add_child()` must have a matching `remove_child()` in `disable()` or `destroy()`.
-- **Rationale**: Actors added to `global.stage` persist on the compositor stage across enable/disable cycles. Unlike container widgets that are destroyed with their parent, stage children must be explicitly removed or they leak — causing visual artifacts and memory growth.
-- **Fix**: In `disable()`, call `global.stage.remove_child(this._actor); this._actor = null;`.
-- **Tested by**: `tests/fixtures/stage-add-child@test/`
+- **Checked by**: check-lifecycle.py
+- **Rule**: `Main.messageTray.add(this._source)` must have a matching `this._source.destroy()` in `disable()`/`destroy()`. Only tracks `this._xxx` patterns.
+- **Rationale**: Notification sources added to the message tray persist if not explicitly destroyed. While lower impact than stage actor leaks (notifications expire and sources may be GC'd), they can accumulate across enable/disable cycles.
+- **Fix**: In `disable()`, call `this._source.destroy(); this._source = null;`.
+- **Tested by**: `tests/fixtures/messagetray-source-leak@test/`
 
 ### R-LIFE-20: Bus name ownership without release
 - **Severity**: advisory

skills/ego-lint/scripts/check-lifecycle.py

@@ -24,6 +24,8 @@
   - R-LIFE-18: Subprocess without cancellation in disable/destroy
   - R-LIFE-20: Bus name ownership without release
   - R-LIFE-21: GSettings signal leak (bare connect without disconnect)
+  - R-LIFE-22: Stage actor leak (add_child/addChrome without remove)
+  - R-LIFE-24: MessageTray source leak (add without destroy)
   - R-SEC-16: Clipboard + keybinding cross-reference
   - R-FILE-07: Missing export default class
 
@@ -1010,6 +1012,137 @@ def check_widget_lifecycle(ext_dir):
                f"All {len(created_widgets)} widget(s) properly cleaned up")
 
 
+def check_stage_actor_lifecycle(ext_dir):
+    """R-LIFE-22: Stage actor add without matching remove in disable()/destroy()."""
+    js_files = find_js_files(ext_dir, exclude_prefs=True)
+    if not js_files:
+        return
+
+    # Patterns that add actors to stage/chrome
+    add_patterns = [
+        (r'global\.stage\.add_child\s*\(\s*this\.(_\w+)', 'global.stage.remove_child'),
+        (r'Main\.layoutManager\.addTopChrome\s*\(\s*this\.(_\w+)', 'removeTopChrome'),
+        (r'Main\.layoutManager\.addChrome\s*\(\s*this\.(_\w+)', 'removeChrome'),
+    ]
+
+    added_actors = []  # (var_name, file_rel, lineno, remove_method)
+
+    for filepath in js_files:
+        content = strip_comments(read_file(filepath))
+        rel = os.path.relpath(filepath, ext_dir)
+        for lineno, line in enumerate(content.splitlines(), 1):
+            for add_re, remove_method in add_patterns:
+                m = re.search(add_re, line)
+                if m:
+                    added_actors.append((m.group(1), rel, lineno, remove_method))
+
+    if not added_actors:
+        return
+
+    # Extract cleanup method bodies across all files
+    cleanup_re = re.compile(
+        r'\b(?:disable|destroy|_destroy\w*|onDestroy)\s*\(')
+
+    cleanup_text = ''
+    for filepath in js_files:
+        content = strip_comments(read_file(filepath))
+        lines = content.splitlines()
+        i = 0
+        while i < len(lines):
+            if cleanup_re.search(lines[i]):
+                depth = 0
+                started = False
+                for j in range(i, len(lines)):
+                    depth += lines[j].count('{') - lines[j].count('}')
+                    if '{' in lines[j]:
+                        started = True
+                    cleanup_text += lines[j] + '\n'
+                    if started and depth <= 0:
+                        break
+                i = j + 1 if started else i + 1
+            else:
+                i += 1
+
+    leaked = []
+    for var_name, rel, lineno, remove_method in added_actors:
+        escaped = re.escape(var_name)
+        has_remove = bool(re.search(
+            rf'{re.escape(remove_method)}\s*\(\s*this\.{escaped}', cleanup_text))
+        has_destroy = bool(re.search(
+            rf'this\.{escaped}\.destroy\s*\(', cleanup_text))
+        if not has_remove and not has_destroy:
+            leaked.append(f"this.{var_name} ({rel}:{lineno})")
+
+    if leaked:
+        result("FAIL", "lifecycle/stage-actor-leak",
+               f"Actor(s) added to stage/chrome but not removed in "
+               f"disable()/destroy(): {', '.join(leaked[:5])}")
+    else:
+        result("PASS", "lifecycle/stage-actor-leak",
+               f"All {len(added_actors)} stage/chrome actor(s) properly cleaned up")
+
+
+def check_message_tray_lifecycle(ext_dir):
+    """R-LIFE-24: MessageTray source added without destroy in disable()/destroy()."""
+    js_files = find_js_files(ext_dir, exclude_prefs=True)
+    if not js_files:
+        return
+
+    add_re = re.compile(r'Main\.messageTray\.add\s*\(\s*this\.(_\w+)')
+    added_sources = []  # (var_name, file_rel, lineno)
+
+    for filepath in js_files:
+        content = strip_comments(read_file(filepath))
+        rel = os.path.relpath(filepath, ext_dir)
+        for lineno, line in enumerate(content.splitlines(), 1):
+            m = add_re.search(line)
+            if m:
+                added_sources.append((m.group(1), rel, lineno))
+
+    if not added_sources:
+        return
+
+    # Extract cleanup method bodies across all files
+    cleanup_re = re.compile(
+        r'\b(?:disable|destroy|_destroy\w*|onDestroy)\s*\(')
+
+    cleanup_text = ''
+    for filepath in js_files:
+        content = strip_comments(read_file(filepath))
+        lines = content.splitlines()
+        i = 0
+        while i < len(lines):
+            if cleanup_re.search(lines[i]):
+                depth = 0
+                started = False
+                for j in range(i, len(lines)):
+                    depth += lines[j].count('{') - lines[j].count('}')
+                    if '{' in lines[j]:
+                        started = True
+                    cleanup_text += lines[j] + '\n'
+                    if started and depth <= 0:
+                        break
+                i = j + 1 if started else i + 1
+            else:
+                i += 1
+
+    leaked = []
+    for var_name, rel, lineno in added_sources:
+        escaped = re.escape(var_name)
+        has_destroy = bool(re.search(
+            rf'this\.{escaped}\.destroy\s*\(', cleanup_text))
+        if not has_destroy:
+            leaked.append(f"this.{var_name} ({rel}:{lineno})")
+
+    if leaked:
+        result("WARN", "lifecycle/messagetray-source-leak",
+               f"MessageTray source(s) added but not destroyed in "
+               f"disable()/destroy(): {', '.join(leaked[:5])}")
+    else:
+        result("PASS", "lifecycle/messagetray-source-leak",
+               f"All {len(added_sources)} messageTray source(s) properly cleaned up")
+
+
 def check_gsettings_signal_leak(ext_dir):
     """R-LIFE-21: Bare settings.connect() without stored ID is a guaranteed leak."""
     js_files = find_js_files(ext_dir, exclude_prefs=True)
@@ -1123,6 +1256,8 @@ def main():
     check_soup_session_abort(ext_dir)
     check_destroy_then_null(ext_dir)
     check_widget_lifecycle(ext_dir)
+    check_stage_actor_lifecycle(ext_dir)
+    check_message_tray_lifecycle(ext_dir)
     check_gsettings_signal_leak(ext_dir)
     check_settings_cleanup(ext_dir)
 

tests/assertions/field-test-improvements.sh

@@ -43,11 +43,25 @@ assert_exit_code "exits with 0 (no FAIL)" 0
 assert_output_not_contains "no constructor-resources WARN for prefs.js" "\[WARN\].*quality/constructor-resources"
 echo ""
 
-# --- stage-add-child (R-LIFE-19) ---
+# --- stage-add-child (R-LIFE-22) ---
 echo "=== stage-add-child ==="
 run_lint "stage-add-child@test"
-assert_exit_code "exits with 0 (advisory only)" 0
-assert_output_contains "warns on global.stage.add_child" "\[WARN\].*R-LIFE-19"
+assert_exit_code "exits with 1 (FAIL — stage actor leak)" 1
+assert_output_contains "fails on stage actor leak" "\[FAIL\].*lifecycle/stage-actor-leak"
+echo ""
+
+# --- messagetray-source-leak (R-LIFE-24) ---
+echo "=== messagetray-source-leak ==="
+run_lint "messagetray-source-leak@test"
+assert_exit_code "exits with 0 (WARN only)" 0
+assert_output_contains "warns on messageTray source leak" "\[WARN\].*lifecycle/messagetray-source-leak"
+echo ""
+
+# --- stage-add-child-clean (R-LIFE-22 negative) ---
+echo "=== stage-add-child-clean ==="
+run_lint "stage-add-child-clean@test"
+assert_exit_code "exits with 0 (clean)" 0
+assert_output_not_contains "no stage actor leak" "lifecycle/stage-actor-leak.*FAIL"
 echo ""
 
 # --- shell-keybinding-mode (R-DEPR-11) ---

tests/fixtures/messagetray-source-leak@test/LICENSE

@@ -0,0 +1 @@
+SPDX-License-Identifier: GPL-2.0-or-later

tests/fixtures/messagetray-source-leak@test/extension.js

@@ -0,0 +1,14 @@
+import * as Main from 'resource:///org/gnome/shell/ui/main.js';
+import {Extension} from 'resource:///org/gnome/shell/extensions/extension.js';
+import * as MessageTray from 'resource:///org/gnome/shell/ui/messageTray.js';
+
+export default class MessageTrayLeakExtension extends Extension {
+    enable() {
+        this._source = new MessageTray.Source({title: 'Test'});
+        Main.messageTray.add(this._source);
+    }
+
+    disable() {
+        this._source = null;
+    }
+}

tests/fixtures/messagetray-source-leak@test/metadata.json

@@ -0,0 +1,7 @@
+{
+  "uuid": "messagetray-source-leak@test",
+  "name": "MessageTray Source Leak Test",
+  "description": "Test fixture for R-LIFE-24",
+  "shell-version": ["45"],
+  "url": ""
+}

tests/fixtures/stage-add-child-clean@test/LICENSE

@@ -0,0 +1 @@
+SPDX-License-Identifier: GPL-2.0-or-later

tests/fixtures/stage-add-child-clean@test/extension.js

@@ -0,0 +1,14 @@
+import St from 'gi://St';
+import {Extension} from 'resource:///org/gnome/shell/extensions/extension.js';
+
+export default class StageChildCleanExtension extends Extension {
+    enable() {
+        this._label = new St.Label({text: 'Hello'});
+        global.stage.add_child(this._label);
+    }
+
+    disable() {
+        global.stage.remove_child(this._label);
+        this._label = null;
+    }
+}