PR queue: notice when it's my turn without opening hub

[ooloth]

Read the plan of record before starting: gh issue view 327 --comments.
The agreed architecture, the measured spike findings, and the full phase sequence live in a
comment on this issue. gh issue view 327 prints only this body and does not show it. The
Ideal state below is the original framing; where it and the plan of record disagree, the plan
of record wins.

Milestone

M1 — I always know what's in my PR queue, so review and reply happen sooner.

Current state

Hub isn't naturally opened, so its information provides no benefit — attention stays self-managedthe way it was before hub existed, rather than hub-managed as intended. The result: awareness ofthe PR queue lapses regardless of whether I'm the author or the reviewer, PRs resolve slower thanthey need to, and that slowness affects my team's velocity, not just mine.

This isn't a fresh problem. #14 proposed a background daemon in 2026-04 to solve a related need(instant TUI startup); it was closed in favor of the TUI owning its own refresh loop(ADR 008) because, at the time, "the CLI doesn'tneed instant startup badly enough to justify a background process." #35 later proposed a hubbrief command on cron specifically to reach the user without violating that same no-daemonconstraint, deliberately excluding push delivery and a long-lived process. Neither fully closes thegap this milestone is scoped to close: actually being notified, not just having a file or a faster CLI waiting to be checked.

Ideal state

• A new surface, hub-daemon, runs detection unattended — without any TUI needing to be open, and without me starting or remembering to open anything
• Two new PR attention reasons exist: replies where the ball is back in my court after I engaged, and my own PRs that have been reviewed and are waiting on my reply. (New non-draft PRs and explicit review requests are already detected today, per Surface all non-draft open PRs in configured repos, not just mine or review-requested #72 — this milestone doesn't touch that.) Superseded detail: this originally said "two new PrKind variants." The plan of record instead splits the type into two axes, relationship and attention, because a PR can be both mine and awaiting my reply and one field cannot carry both.
• I'm notified locally only while logged in and able to act — never off-hours
• The notification names the top N oldest outstanding items (N tunable); the same item can legitimately keep appearing across notifications — the message reports current queue state, not novelty
• I can conveniently trigger an investigation of a notified item, opening as a real Claude Code session in a named tmux window, with a useful opening prompt the system authors, not one I write. Superseded detail: this originally said "matching hub's existing i-key pattern." That pattern is a tmux split-window beside the TUI, with no window name and no way to address it afterwards; Phase 2.1 — Open investigations in named tmux windows instead of splitting the TUI pane #330 changes i to open a named window, which is what makes the next bullet possible at all.
• The system never opens a second investigation window for an item that already has one (Phase 2.2 — Switch to an existing investigation window instead of opening a second one #331)
• The unified list shows which of the (now four) reasons a PR needs my attention

Out of scope

• Auto-triggering an investigation without me asking — tracked in docs/questions/where-do-auto-triggered-investigation-outputs-appear.md
• Per-category refresh intervals — tracked in docs/questions/should-refresh-run-on-a-per-category-schedule.md
• Slack (or any channel beyond a local OS notification) — tracked in docs/questions/should-notifications-also-go-to-slack.md
• Ranking by importance instead of oldest-first — tracked in docs/questions/should-ranking-consider-importance-not-just-age.md
• Immediate backfill of the active set as items clear — tracked in docs/questions/should-the-active-set-backfill-immediately-or-wait-for-the-next-detection-pass.md
• Snoozing/dismissing an item, pausing/muting the whole system — not needed now; the design must not foreclose adding either later
• A standalone OS-level window as an alternative delivery surface — decided against; the existing tmux-window investigation pattern is kept as-is
• Anything changing what hub-cli is for — it stays the agent-facing toolkit per ADR 010, which now explicitly rules out hosting an unattended process there. hub-daemon is a new, separate surface
• Dashboard / multi-instance-TUI viewing — already works today, untouched here

Starting points

• workflows/src/status.rs — the fetch/detect/sort logic hub-daemon calls; already independent of ui/tui
• domain/src/pr.rs — PrKind, to extend with the two new PR-attention categories
• clients/src/github/prs/fetch.rs — where PR data (including reviewThreads/comments, already fetched) gets turned into PrKind values today; the new categories are classified from data already present in the response, not a new query
• ADR 008, ADR 009, ADR 010 (including its 2026-09-04 addendum), and vision.md's "What hub is not" — the standing decisions this milestone knowingly amends

QA plan

1. With hub-daemon running and no TUI open, have someone reply on a PR thread you'd previously commented on — expect a local notification naming it within the daemon's polling interval, without opening hub-tui at all
2. Open one of your own PRs that's been reviewed and not yet replied to — expect it to appear in the notification, distinguishable in the unified list from a fresh review request
3. Simulate being away (locked/logged out) during a detection cycle — expect no notification during that window, and expect the item still waiting, not re-notified redundantly, once back
4. Trigger an investigation on a notified item — expect a new tmux window with a populated, useful prompt
5. Trigger investigation on the same item again — expect no second window; the existing one surfaces instead
6. Clear one of the top-N items — expect the active set to shrink, with no new item pulled in until the next scheduled detection pass

Done when

I am aware of the top PRs requiring my attention at all times while on my laptop.

[ooloth]

Agreed plan of record (2026-09-04)

Sequence and architectural decisions settled in the planning discussion for this milestone. Recorded here so the reasoning survives context loss.

Decisions settled

The daemon owns fetching; the TUI becomes a client. No dual-fetch path. The TUI drops its own refresh loop and interval entirely. A TUI that silently self-fetches would hide a dead daemon, which is the exact failure this milestone exists to fix.

Dev loop is repaired by isolation, not a fallback flag. HUB_HOME (default ~/.hub) resolves the socket, database and logs, so a dev daemon on ~/.hub-dev never collides with the installed one. A version handshake on connect reports a build mismatch with an actionable message instead of an empty screen. No --standalone flag.

Transport is a Unix socket at $HUB_HOME/hub.sock, carrying newline-delimited JSON commands and events. SQLite stays the data store; the socket carries control, not data. The socket bind doubles as the liveness check, and flock on $HUB_HOME/daemon.lock is the single-instance guard.

Ops legibility is a requirement, not a polish item. Every socket error maps to a sentence with an action ("hub-daemon isn't running. Start it with just daemon-start"). hub-daemon status answers "what's wrong" in one command. just daemon-start/stop/restart/logs wrap launchctl so its syntax never has to be remembered. The daemon unlinks its own stale socket on startup, guarded by the flock, so crash recovery is automatic. One log line per poll pass. Daemon health shows in the TUI status bar always.

Delivery is terminal-notifier, with osascript as fallback. Detected at startup rather than bailing, since notifications are the daemon's whole purpose.

Notifications name PRs only to start, structured so widening to all signal types is a one-line filter change. Widening is gated on computed attention and urgency landing first.

The PR type splits into two axes: relationship (kind) and attention (why it is waiting on me now, with a since timestamp). Naming deferred to the type-design step of its slice.

Ranking is by time since the ball landed in my court, implemented in the unified list so notifications inherit it.

Cache splits to a row per source in the slice that introduces the daemon as a writer, because that is the moment to do it and it avoids a second migration when per-source refresh intervals arrive.

Spike findings (2026-09-04, measured)

• osascript notifications fire from a launchd agent. Verified: agent ran with PPID=1, parent /sbin/launchd, no TTY, exit 0, delivery record present in Notification Center.
• osascript notifications are attributed to com.apple.scripteditor2, not hub. They share one permission toggle with every other osascript notification on the machine.
• terminal-notifier is already installed (v2.0.0, fr.julienxx.oss.terminal-notifier). Not a new dependency. It has its own bundle identity, so hub gets its own permission toggle and icon.
• -group genuinely replaces: two sends with the same group left exactly one notification on screen. This is why presence gating is unnecessary. Returning after any number of passes shows one accurate current-state banner.
• terminal-notifier requires a first-run permission grant, and blocked for over two minutes while that prompt was pending. The notification call must run with a timeout and never inline in the poll loop's critical path.
• Installing a LaunchAgent fires a macOS "App Background Activity" notification and creates a Login Items & Extensions entry, from which the agent can be disabled without hub knowing.

Sequence

Every item ends with something observable. Phase 2 is independent of everything after it.

Phase 1 — record the intent

1. Phase 1.1 — Record the decision to run hub unattended, amending ADRs 008 and 009 #329 — ADR 020 and the vision rewrite. Hub gains an unattended surface; the daemon owns refresh; the TUI becomes a client. Amends ADRs 008 and 009, rewrites "not a notification system" in vision.md.
2. Phase 1.2 — Inventory built vs. planned subsystems so agents stop coding against integration points that don't exist #299 (existing) — inventory of built vs. planned subsystems, so nobody codes against ADR 019's session records as though they exist.

Phase 2 — the new investigation norm (TUI only, no daemon)

3. Phase 2.1 — Open investigations in named tmux windows instead of splitting the TUI pane #330 — i opens a named window instead of a split. Observable: a window named per item; several open in parallel without crowding the viewport.
4. Phase 2.2 — Switch to an existing investigation window instead of opening a second one #331 — i on an item that already has a window switches to it. Observable: press i twice, the second press focuses the first window.
5. Phase 2.3 — Harden the investigation prompt against externally-authored text #310 (existing, rewritten; tmux investigation launch: sanitize API-sourced prompt content passed via -e arguments #79 closed as its duplicate) — harden the prompt against externally-authored text. Extract command construction into a pure, snapshot-tested function; mark PR titles and comment bodies as data. Observable: investigate a PR whose title contains injection-shaped text, see it rendered inert.

Phase 3 — the daemon exists

6. hub-daemon runs one pass and exits. Writes the cache in the new per-source shape plus a health row. Observable: run it once by hand, open the TUI, see fresh data it never fetched itself.
7. HUB_HOME isolation and just dev. Observable: a dev daemon and TUI on ~/.hub-dev while the installed setup keeps running untouched.
8. Loop on an interval, with flock and a per-pass timeout. Observable: repeated passes in the log; a second instance refuses with a clear message.
9. 1Password retry with backoff. Observable: lock 1Password, start the daemon, see it retry and report "credentials unavailable"; unlock, see it recover on its own.
10. Under launchd, with log paths and just daemon-start/stop/restart/logs. Observable: launchctl kickstart, see it running unattended; just daemon-logs shows history.

Phase 4 — notifications

11. osascript notification naming the top N PRs. Observable: close the TUI, get a banner with real content.
12. Swap to terminal-notifier with grouping, fallback and timeout. Observable: two passes leave one banner not two; remove terminal-notifier from PATH and the osascript fallback still fires.

Phase 5 — TUI becomes a client

13. Daemon serves the socket; hub-daemon status prints health. Observable: run it, see real info; stop the daemon, get the actionable error.
14. TUI shows daemon health in the status bar. Observable: "daemon ok · 4m ago"; kill the daemon, see it say so.
15. r sends refresh over the socket. Observable: press r, daemon log shows a pass, TUI updates.
16. TUI drops its own fetch loop, plus the version handshake. Observable: kill the daemon and the TUI shows stale data with a clear message rather than fetching.

Phase 6 — the PR attention model

17. Two-axis type, using only existing information. Observable: the unified list separates "waiting on me" from "not," with no new classification yet.
18. Add "my PR was reviewed and I owe a response," classified from reviews (already fetched). Observable: your reviewed PR moves into the waiting group.
19. Its investigation prompt. Observable: press i on such a PR, see the tailored prompt.
20. Add "a reply landed in a thread I was in." Includes username plumbing and thread-fetch adjustments. Observable: someone replies to your comment, it appears categorized.
21. Its investigation prompt. Observable: same.
22. Rank by time-since-ball-landed. Observable: list order matches what has actually been waiting; notifications inherit it.

Items 17 and 22 churn insta snapshots. Item 20 is the one most likely to want splitting further at its type-design step: bot comments, your own follow-ups, threads you left, and the 10-comment-per-thread fetch cap are all edge cases.

Tracked, not built

• Computed attention and urgency. Urgency is currently a hardcoded constant per query, which is what makes the unified list untrustworthy enough to notify from beyond PRs. This is the gate on widening item 11's scope.
• Per-source refresh intervals. Unlocked by item 6's cache split, not implemented.
• Presence gating beyond "logged into the GUI session," which a LaunchAgent gives for free.
• Auto-triggered investigations. Out of scope, existing question file.
• ADR 019's filesystem session records, which remain unbuilt.

Issue relationships: measured, they are invisible to agents

Phase 1 and 2 issues are wired as sub-issues of this epic, and #331 is marked blockedBy #330 (the only genuine hard dependency among them). Testing whether that ordering signal actually reaches an agent:

• gh issue view 331 default output: shows title, state, labels, milestone, body. No parent, no blockedBy.
• gh issue view --json and gh issue list --json: the field list has no parent, blockedBy, or subIssues at all (gh 2.92). Not fetchable.
• REST gh api repos/ooloth/hub/issues/331: exposes parent_issue_url and sub_issues_summary, but not blockedBy.
• GraphQL: the only route that exposes parent, blockedBy, and issueDependenciesSummary.

So an agent using the ordinary gh issue list / gh issue view path sees none of it. The relationships are useful in the browser and for the epic's progress bar, but they are not the ordering signal.

What reaches an agent is the title, which gh issue list prints for every row, long before any body is fetched. So every issue in this milestone carries a Phase N.M — title prefix, with the "Phase N of #327 — step X of Y" line repeated at the top of the body as the fallback for anything reading bodies.

Settled question files

should-the-active-set-backfill-immediately-or-wait-for-the-next-detection-pass.md is answered: nothing is persisted, each poll notifies the current top N. should-ranking-consider-importance-not-just-age.md is answered by item 22. Both are feature nuances rather than architectural boundaries, so neither becomes a decision record.