FEA-1500: Obsolete; replace dead in-code anchors

[thadeusb]

Summary

Closes out FEA-1500 as OBSOLETE (we are not migrating the agent-monitor hook transport) and removes the now-dead in-code anchors that referenced it.

Why FEA-1500 is obsolete

FEA-1500 tracked "remove the legacy :4820 HTTP hook listener after a transport migration." Its stated premise — that the port/transport is a backward-compatible contract baked into external config that must survive "until all installs self-heal" — is incorrect about where the contract boundary sits:

• The :4820 HTTP call lives inside the app-owned handler scripts (resources/hooks/{hook-handler,codex-hook-handler}.js), which refreshHandlerCopy() overwrites in place on every boot.
• ~/.claude/settings.json / ~/.codex/hooks.json only pin the handler file path + the ELECTRON_RUN_AS_NODE command — not the transport.
• So the handler and the in-process listener ship in the same build and update together atomically when the user launches. There is no version-skew window where a handler POSTs to a transport that no longer exists.

The only genuine flaw of TCP 4820 is port collision (it's an unreserved port; a squatting process disables capture and could receive hook payloads). That's rare and already degrades safely (EADDRINUSE → "agent monitoring is off this session"). A unix-socket swap would be a ~1-release internal change, but it isn't worth doing. The fixed-port loopback-HTTP transport is the accepted permanent design.

Changes

• src/main/agent-monitor-listener.ts — replace the CLOSEDLOOP-TICKET FEA-1500 anchor with the actual design rationale (fixed-port internal contract, zero per-hook env; unix-socket alternative considered and declined).
• resources/hooks/hook-handler.js, resources/hooks/codex-hook-handler.js — drop the "backward-compatible contract (FEA-1500)" framing; state that handler + listener must stay in sync because they ship together.
• apps/desktop/CLAUDE.md — the Fixed-port bullet now states the loopback-HTTP transport is the accepted permanent design (was: "FEA-1500 tracks migrating this transport later").
• apps/desktop/package.json — version bump 0.15.111 → 0.15.112 (CI-enforced for any apps/desktop/ change).

Testing

Comment/doc/version-only change; no code behavior modified. The edits touch only comments, a markdown doc, and the package.json version string — none affect compilation or runtime.

Risks

None identified. No gateway route, cloud-relay message, or persisted-store schema changed; the :4820 transport behavior is unchanged.

[thadeusb]

The internal-contract argument holds up. settings.json only pins the handler path and the run-as-node command, the port/path/envelope live in the handler scripts that refreshHandlerCopy rewrites on boot, so there's no skew window for FEA-1500 to guard against. Comments line up with the code now.

[shafty023]

Non-inline findings:

• [P3] apps/desktop/CLAUDE.md:173 says hook events are "harness-stamped from __provider", but the listener rejects payload-level __provider and stamps provider by route (/api/hooks/event vs /api/hooks/codex/event). Please update this doc to make provider attribution route-owned and payload __provider invalid.

• [P3] apps/desktop/CLAUDE.md:228 says any apps/desktop/ change requires a clean-machine packaged-DMG smoke test. The PR currently records no local validation for this desktop change. Please either run and record that packaged-DMG smoke, or document an accepted exception for doc/comment/version-only changes.

[shafty023]

refreshHandlerCopy() is boot repair and catches failures; enabled installs can keep a stale userData handler copy invoked by persistent Claude/Codex settings. Calling the port/path/envelope an INTERNAL contract risks future changes without a listener shim/transition that silently drop hooks for stale copies. Please keep the compatibility requirement explicit: route/envelope changes need backward-compatible listener support until persisted handler copies are known refreshed.

[thadeusb]

Good catch — fixed in 6d6b1ff. Dropped the INTERNAL contract framing and made the compatibility requirement explicit: the route + envelope must stay backward-compatible because the userData handler copy refreshes only best-effort on boot (refreshHandlerCopy failures are caught/logged) and can outlive an app upgrade, so any route/envelope change needs backward-compatible receiver support until persisted copies are known refreshed. Also called out that /api/hooks/event has two receivers (legacy sidecar + in-process listener).

[shafty023]

This comment now makes the first-party handler sound paired only with AgentHookListener, but default Agent Monitor mode still starts AgentMonitorSidecar and syncAgentMonitorHooksOnBoot() installs/repairs the same handler command. While legacy sidecar remains default, /api/hooks/event compatibility has two receivers. Please scope the statement to design-system mode or say the handler envelope must stay compatible with both sidecar and in-process receivers.

[thadeusb]

Agreed — fixed in 6d6b1ff. The comment now states the route + envelope must stay backward-compatible with BOTH receivers of /api/hooks/event: the legacy AgentMonitorSidecar (default Agent Monitor mode) and the in-process AgentHookListener (design-system mode), and notes the handler is a persisted userData copy that refreshes only best-effort on boot.

[shafty023]

~/.claude/settings.json does not bake CLAUDE_DASHBOARD_PORT || 4820; it stores the Electron-as-Node command pointing at the userData handler copy, and the copied handler owns the port fallback and route. Leaving this wording preserves the obsolete FEA-1500 premise while this PR is trying to remove it. Please reword this bullet so settings pin the handler path/command, while handler content owns the fixed-port fallback and envelope.

[thadeusb]

Fixed in 6d6b1ff. Reworded the bullet so ~/.claude/settings.json pins only the Electron-as-Node command + userData handler path, while the copied handler owns the CLAUDE_DASHBOARD_PORT || 4820 fallback, route, and envelope. Also noted /api/hooks/event is served by both the legacy sidecar (default) and the in-process listener (design-system). Removes the 'baked into settings.json' premise the PR is trying to retire.