Keep running objects alive without a reference (#267)

[cmsj]

Fixes #267.

JavaScript garbage collection must be unobservable, but collecting an object the user had dropped could stop real work: an unreferenced running hs.task was killed, so hs.task.shell() promises could never settle; an unstored hs.hotkey.bind() stayed registered but silently stopped firing; a visible hs.menubar item vanished. This adopts the rule Node and the HTML spec use for pending activity: an object that is running keeps running, with its callbacks, until it finishes or is stopped, whether or not the user kept a reference. Once it's inactive it's ordinary garbage.

Two retention mechanisms

Retention is unified across every module on exactly two mechanisms:

• Callbacks: always JSCallback. ModuleRoot now pins each module's JS wrapper until shutdown, so JSCallback(owner: self) works on modules too. That fixes the module-owned callbacks in hs.notify, hs.urlevent and hs.midi, and the hs.window.js helpers are garbage collected shortly after startup #185 class of lost hs.foo.js properties. Every raw stored JSFunction/JSValue callback is converted, except modal one-shots (text prompt, file picker), which hold theirs until show() invokes it.
• Child objects: the module's HSObjectTracker<T> (renamed from HSWeakObjectSet). It tracks children weakly, and setActive(_:_:in:) pins an active child's JS wrapper (not just the Swift object, or its JSCallbacks would still be collected). setActive is called only from the didSet of the state that defines activity, so every stop, finish or failure path un-pins it. Pins are stored centrally, and removeAllObjects() in shutdown() drops them all, so a missed un-pin lasts until the next reload at most and can't keep an old JSContext alive.

selfRetain, Unmanaged self-retains and the strong child registries are gone.

Behaviour changes

• Running hotkeys, timers, taps, watchers, queries, searches, tasks, servers, sockets, ports, pings, shares, sounds and shown UI keep working without a reference.
• Inactive objects are now collectable, e.g. a hidden hs.ui window, canvas, chooser or menubar item you don't keep a reference to. Previously these were held until destroy().
• New hs.activeObjects() lists everything currently running.

Proposed release note:

Objects that are running now keep running until they finish or you stop them, even if you don't keep a reference to them: bound hotkeys, started timers and watchers, running tasks, shown windows and menu bar items, and so on. Previously, garbage collection could silently stop them. If your config relied on dropping a reference to make something stop, call its stop(), disable(), hide() or destroy() instead. Hidden windows, canvases and choosers you don't keep a reference to are now released. hs.activeObjects() lists everything currently running.

Bugs found along the way

• hs.ui.webview callbacks were owned by the inline-built element, so they could be collected while the user still held the window. They now belong to the window, via a new JSCallback.transferOwnership(from:to:).
• hs.ui onClick/onHover closures captured their callback strongly. A callback closing over its own window made a Swift/JS cycle the GC can't break. They now use window-owned JSCallbacks.
• Bonjour advertise callbacks were owned by a private object with no JS wrapper, so they were collectable at the first GC.
• Four hs.task tests used Thread.sleep in synchronous tests, which can never see a task's termination arrive.

Enforcement

• JSTestHarness fails any test that ends with an object still active that should have finished on its own (tasks, one-shot timers, pings, sounds: finishesOnItsOwn in setActive).
• scripts/check-object-lifetimes.js, run by npm run docs:test, rejects new selfRetain = self and strong HS* collections. The 5 remaining collections are listed with their justification.
• The HSModule and HSTests skills document the rules.

Testing

• Each migrated object has GC tests in both directions: active and unreferenced keeps working; inactive and unreferenced is collected.
• I confirmed each "keeps working" test fails with pinning disabled. The audio device test is the exception, because a device is also kept alive by its own watcher emitter, so only its "collected" half is meaningful.
• No GC test for hs.sharing (needs system UI), the Stream Deck and camera device watchers (need hardware), or Bonjour advertising (publishing doesn't fire in the VM). Their mechanisms are covered generically.
• Full suite in the VM: 2366 tests passed, 3 known issues.

Docs

The getting-started lifecycle section told users to keep a reference to everything or it would stop. It's rewritten for the new rule (new anchor #object-lifecycle-running-things-keep-running), and the other guides, docstrings and npm run docs:generate output are updated.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

[High impact] The PR appears safe to merge, with a non-blocking fix recommended for invalid callback replacements.

Findings

1.  Bad replacements disable working handlers ▶

Fix with agent prompt

### Issue 1
Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift:909-910
Replacing `onClick` or `onHover` with a non-function now disables the working callback. `elementCallback` detaches the old callback before checking the replacement. When `JSCallback` rejects the new value, the element still holds its old closure, but that closure can no longer call anything.

Create the new callback successfully before detaching the old one.

```suggestion
        guard let cb = JSCallback(value: callback, owner: self) else { return nil }
        elementCallbacks.removeValue(forKey: key)?.detach(from: self)
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR keeps active objects and their callbacks alive through garbage collection. Inactive objects can still be collected, and hs.activeObjects() lists running work.

• Running objects keep working until they finish or you stop them.
• Shown windows and menu items stay alive until hidden.
• Lifecycle guides and checks now teach the active-object rule.

_{Reviews (2) · Last reviewed commit: "Stop monitoring a search's services when..." · Reviewed by Greptile}

[github-actions]

❌ Test Results: Failed

Total	Passed	Failed	Skipped	Expected Failures	Duration
2370	2197	1	170	2	11m 59s

Ran on: Virtual Machine, macOS 27.0.1 (26A434)

Failures

Hammerspoon 2Tests › HSTaskIntegrationTests/testTimeoutPattern()

Issue recorded: Test ended with 1 object(s) still active: <HSTask: /bin/sleep>. Wait for them to finish or stop them, or set allowsActiveObjectsAtTeardown if that's deliberate.

_{From this run of 62c6414.}

[cmsj]

@greptile

[greptile-apps]

Bad replacements disable working handlers

Replacing onClick or onHover with a non-function now disables the working callback. elementCallback detaches the old callback before checking the replacement. When JSCallback rejects the new value, the element still holds its old closure, but that closure can no longer call anything.

Create the new callback successfully before detaching the old one.

Suggested change

	elementCallbacks.removeValue(forKey: key)?.detach(from: self)
	guard let cb = JSCallback(value: callback, owner: self) else { return nil }
	guard let cb = JSCallback(value: callback, owner: self) else { return nil }
	elementCallbacks.removeValue(forKey: key)?.detach(from: self)

Prompt To Fix With AI

This is a comment left during a code review.
Path: Hammerspoon 2/Modules/hs.ui/Core/HSUIWindow.swift
Line: 909-910

Comment:
**Bad replacements disable working handlers**

Replacing `onClick` or `onHover` with a non-function now disables the working callback. `elementCallback` detaches the old callback before checking the replacement. When `JSCallback` rejects the new value, the element still holds its old closure, but that closure can no longer call anything.

Create the new callback successfully before detaching the old one.

```suggestion
        guard let cb = JSCallback(value: callback, owner: self) else { return nil }
        elementCallbacks.removeValue(forKey: key)?.detach(from: self)
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.