feat(release): make v0.1.2 always ready

[tcballard]

Summary

Implements docs/v0.1.2-always-ready.md.

Adds:

• an agent-aware Signal First menu-bar state that names the single waiting agent and gives project context on hover, in the context menu, and to VoiceOver
• exact Codex task routing plus fail-closed Terminal and iTerm TTY routing
• native Launch at Login, update visibility, privacy-safe diagnostics, and stuck-session recovery in Settings
• deterministic coverage and user-facing documentation for the complete v0.1.2 contract

Scope

Included

• Expand the existing red speech-bubble status item to show Codex needs you, Claude needs you, or the generic agent fallback.
• Keep the persistent title compact while deriving a privacy-safe project basename for the tooltip, return action, and accessibility label.
• Return valid Codex sessions through codex://threads/<UUID>.
• Focus supported Terminal and iTerm sessions only through their exact recorded TTY; show a visible failure if no exact route remains.
• Expose macOS Service Management launch state and recovery guidance.
• Show installed and latest release versions without downloading an update.
• Copy a diagnostics report that excludes repository names, paths, prompts, session IDs, command output, and credentials.
• Identify suspected stuck sessions and clear them only after explicit confirmation.

Excluded

• Automatic updates, background update services, telemetry, crash uploads, or remote diagnostics.
• A custom status-item view, notch imitation, transient panel, or multi-item island.
• A session roster, waiting count, chooser, history, or attention inbox; those remain Perch's product territory.
• Inexact app-only terminal activation that could land on the wrong task.
• Changes to needs-you, CI, review, snooze, or hide ordering semantics.
• Broader v0.2 architecture.

Product / Architecture Decisions

• Preserve the existing NSStatusItem and NSStatusBarButton; the bloom is a native variable-width title, not a second control or custom pill.
• Keep Meanwhile focused on one deterministic current interruption. Perch remains the cross-session overview and navigator.
• Reuse the selected WorkItem title for needs-you copy so the engine remains the source of provider identity.
• Put project identity in secondary context rather than lengthening the persistent menu-bar label.
• Validate Codex session IDs as UUIDs before constructing the trusted codex://threads/<UUID> route.
• Treat focus as successful only when the exact Codex task URL is accepted or a positively identified Terminal/iTerm TTY is selected. Otherwise keep the interruption active and explain the failure.
• Keep idle icon-only and retain the existing compact CI! and review-number states.
• Keep all support diagnostics local, user-initiated, and privacy-safe.
• Represent stuck sessions as suspected until the user confirms cleanup; do not silently alter the wait gate.

User-Facing Contract

Menu Bar

• Idle: icon only.
• Agent interruption: red speech bubble plus the waiting agent name, for example Codex needs you.
• Hover text, the context-menu return action, and VoiceOver identify the current project without exposing its full path.
• Left-click returns to the exact Codex task or supported terminal tab. An unavailable route produces an explicit warning and leaves the interruption active.
• Right-click retains Return, Snooze, Hide Until It Changes, Settings, and Quit.
• Review and failing-CI labels remain compact, with item-specific accessibility labels.

Settings

• Launch at Login reflects the real system state and links to Login Items when macOS requires approval.
• Update status shows the installed and latest published versions and offers an explicit recheck.
• Copy Diagnostics acts immediately and never sends data automatically.
• Suspected stuck sessions require a destructive-action confirmation before cleanup.

CLI

No CLI contract changes.

Human Output

Unavailable focus shows a native warning that the exact task could not be opened and confirms that the interruption remains active.

JSON Output

No public JSON contract changes.

Exit Codes

No exit-code contract changes.

Verification

Ran

• swift test --filter 'TerminalFocuserTests|MenuBarPresenterTests|AgentFocusRouterTests'
• swift test
• swift build -c release
• CONFIGURATION=release CODE_SIGN_IDENTITY=- SWIFT_BUILD_PATH=/tmp/meanwhile-routing-release-build APP_OUTPUT_DIR=/tmp/meanwhile-routing-app ./Scripts/package-app.sh
• git diff --check

Covered

• The focused routing, terminal, presentation, and accessibility suite passed: 18 tests, 0 failures.
• The complete SwiftPM suite passed: 62 tests, 0 failures.
• Valid Codex UUIDs produce only the exact thread URL; malformed IDs and other providers never attempt that route.
• Rejected Codex URLs fall back once, while unsupported, missing, and stale terminal targets fail closed without activating an arbitrary app.
• Project context is basename-only, rejects private or unhelpful values, and middle-truncates long names.
• Review and failing-CI items retain accurate VoiceOver labels while an agent is thinking.
• Both executable products built in release mode, and the packaged app passed deep strict code-sign verification.
• The packaged app rendered the selected red symbol and full one-line agent label in the real macOS menu bar.

Review Path

1. AgentFocusRouter and TerminalFocuser exact-route behavior.
2. MenuBarPresenter, status-item mapping, and accessibility semantics.
3. Settings reliability and recovery sections.
4. Core diagnostics, release checking, event-store behavior, tests, and docs/v0.1.2-always-ready.md.

Notes For Reviewer

• The local ad-hoc bundle exposes the designed unavailable fallback for Launch at Login; validate enabled and approval-required states in the final Developer ID release candidate.
• Claude desktop sessions do not currently expose a validated exact-task deep link. Meanwhile uses only supported exact terminal routes and fails visibly otherwise.
• A strict Swift 6 concurrency probe reports only the pre-existing GlobalHotKey deinitializer issue; this branch adds no new strict-concurrency diagnostics.