k0-board 0.1.1 → 0.2.0

package/bin/k0-board.js

@@ -126,6 +126,31 @@ async function waitForServer(seconds = 10) {
   return false
 }
 
+// ── Opening the board ────────────────────────────────────────────────────────
+/**
+ * Opens the board in a browser and answers with the address it used.
+ *
+ * `k0.localhost` is the name the board deserves, and inside a browser it is guaranteed to mean
+ * this machine — RFC 6761 reserves the whole of `.localhost` for loopback and every browser
+ * honours it. A resolver is under no such obligation, and on Windows usually declines. So the
+ * name is tried first, from here, and the number is what we fall back to: a board at a duller
+ * address beats a blank page at a prettier one.
+ *
+ * Not being able to open anything at all is not a failure. Installing over SSH, or on a machine
+ * with no session to put a window in, is an ordinary thing to do, and the install has already
+ * succeeded by the time we get here.
+ */
+async function openBoard() {
+  let url = `http://k0.localhost:${PORT}`
+  try {
+    await fetch(`${url}/api/status`, { signal: AbortSignal.timeout(1500) })
+  } catch {
+    url = `http://127.0.0.1:${PORT}`
+  }
+  await shell.openBrowser(url).catch(() => {})
+  return url
+}
+
 // ── install ──────────────────────────────────────────────────────────────────
 async function install() {
   say(`\n${bold('k0')} — the board that drives your Claude Code sessions`)
@@ -218,7 +243,8 @@ async function install() {
     appDir: APP_DIR,
     tray,
   })
-  if (await waitForServer()) ok(`k0 is up: ${bold(`http://k0.localhost:${PORT}`)}`)
+  const up = await waitForServer()
+  if (up) ok(`k0 is up: ${bold(`http://k0.localhost:${PORT}`)}`)
   else warn(`the server is not answering yet — look in ${paths.LOG_DIR}`)
 
   // ── The two invitations ────────────────────────────────────────────────────
@@ -231,6 +257,12 @@ async function install() {
     note(`Where: ${extra.target}`)
   }
 
+  // Last of all, on purpose: by now the imported cards are on the board, so what opens is
+  // somebody's own work rather than an empty grid they would have to reload.
+  if (up && !flag('no-open')) {
+    say(`\n${bold('Done.')} The board is open at ${await openBoard()}`)
+    return
+  }
   say(`\n${bold('Done.')} The board is at http://k0.localhost:${PORT}`)
   if (process.platform === 'win32') note(`If that name does not resolve, use http://127.0.0.1:${PORT}`)
 }
@@ -334,16 +366,17 @@ async function uninstall() {
 // ── start ────────────────────────────────────────────────────────────────────
 /** Runs the server in the foreground and opens the board. No service, nothing installed. */
 async function start() {
+  const open = !flag('no-open')
   if (await alive()) {
     ok(`k0 is already running on http://k0.localhost:${PORT}`)
-    await shell.openBrowser(`http://k0.localhost:${PORT}`).catch(() => {})
+    if (open) await openBoard()
     return
   }
   const child = spawn(process.execPath, [path.join(SOURCE, 'server', 'index.js')], {
     stdio: 'inherit',
     env: { ...process.env, K0_PORT: String(PORT) },
   })
-  if (await waitForServer()) await shell.openBrowser(`http://k0.localhost:${PORT}`).catch(() => {})
+  if ((await waitForServer()) && open) await openBoard()
   child.on('exit', (code) => process.exit(code ?? 0))
 }
 
@@ -434,6 +467,7 @@ ${bold('k0-board')} — a board of sticky notes that drives your Claude Code ses
 Options
   ${bold('--yes')}            do not ask, assume yes
   ${bold('--from-source')}    point the service at this directory instead of copying it
+  ${bold('--no-open')}        do not open the board in a browser at the end
   ${bold('--no-<name>')}      skip one optional change, e.g. --no-lid-sleep
 `)
 }

package/menubar/K0MenuBar.swift

@@ -173,27 +173,93 @@ final class K0: NSObject, NSApplicationDelegate, UNUserNotificationCenterDelegat
     let item = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
     var seen: [Int: String] = [:]      // the last known status of every card
     var firstPass = true               // no notifications on the first pass: that would be noise at startup
-    var notificationsAllowed = false
+    /// What macOS currently thinks of this app's notifications. **Asked again and again, never
+    /// remembered from the one answer at launch**: `requestAuthorization` replies asynchronously,
+    /// this app starts at login — before the notification service is necessarily up — and a
+    /// boolean captured in that callback would then say "no" for the rest of the day, with
+    /// nothing anywhere to say why.
+    var notificationStatus: UNAuthorizationStatus = .notDetermined
+    private var loggedStatus: UNAuthorizationStatus?
+    private var ticksBeforeAsking = 0
     let images = ImagePaste()
 
     func applicationDidFinishLaunching(_ n: Notification) {
         item.button?.image = icon(nil)
         item.menu = NSMenu()
 
-        let centre = UNUserNotificationCenter.current()
-        centre.delegate = self
-        centre.requestAuthorization(options: [.alert, .sound]) { ok, _ in
-            self.notificationsAllowed = ok
-        }
+        UNUserNotificationCenter.current().delegate = self
 
         images.start()
         watchScreens()
         watchTerminal()
 
-        Timer.scheduledTimer(withTimeInterval: 2, repeats: true) { _ in self.refresh() }
+        Timer.scheduledTimer(withTimeInterval: 2, repeats: true) { _ in
+            self.refresh()
+            self.readNotificationPermission()
+        }
         refresh()
+        readNotificationPermission()
+    }
+
+    /// Reads the permission on **every** pass, two seconds apart, along with everything else.
+    ///
+    /// It rides the same beat as the rest on purpose. Somebody who has just switched k0 on in
+    /// System Settings comes straight back to this menu to see it change, and a menu that still
+    /// says "blocked" reads as broken — they switch it off again, or give up. Half a minute is
+    /// long enough for that; two seconds is not. The read is one call to a service already
+    /// listening, next to an HTTP request that happens anyway.
+    ///
+    /// Asking is the part that is kept slow: the request is fired only where the permission has
+    /// never been asked for, and at most once every half minute, because a request that fails
+    /// leaves the status exactly as it was and would otherwise be retried on every pass.
+    ///
+    /// The log line is the point of the rest. A permission that was refused and one that was
+    /// never asked for are both perfectly silent, and until this was written down the only visible
+    /// symptom was a notification that did nothing. `launchd` sends it to
+    /// `~/.k0/logs/com.k0.menubar.err.log`.
+    func readNotificationPermission() {
+        let centre = UNUserNotificationCenter.current()
+        centre.getNotificationSettings { settings in
+            DispatchQueue.main.async {
+                self.record(settings.authorizationStatus)
+                guard settings.authorizationStatus == .notDetermined else { return }
+                guard self.ticksBeforeAsking <= 0 else {
+                    self.ticksBeforeAsking -= 1
+                    return
+                }
+                self.ticksBeforeAsking = 15   // half a minute, at one read every two seconds
+                centre.requestAuthorization(options: [.alert, .sound]) { granted, error in
+                    if let error {
+                        NSLog("k0: macOS refused the notification permission: \(error.localizedDescription)")
+                    } else if !granted {
+                        NSLog("k0: the notification permission was declined")
+                    }
+                    // Whatever the answer, the next read is two seconds away and will report it.
+                }
+            }
+        }
     }
 
+    private func record(_ status: UNAuthorizationStatus) {
+        notificationStatus = status
+        guard loggedStatus != status else { return }
+        loggedStatus = status
+        NSLog("k0: notifications are \(Self.name(status))")
+    }
+
+    private static func name(_ status: UNAuthorizationStatus) -> String {
+        switch status {
+        case .authorized: return "allowed"
+        case .provisional: return "allowed quietly"
+        case .denied: return "denied"
+        case .notDetermined: return "not granted — macOS has not registered this app"
+        default: return "in an unknown state (\(status.rawValue))"
+        }
+    }
+
+    /// True only when a notification posted now would actually be delivered.
+    var canNotify: Bool { notificationStatus == .authorized || notificationStatus == .provisional }
+
     // MARK: The screen changing under the windows
 
     /// You plug a monitor in or out, or change resolution, and the session windows stay where
@@ -381,10 +447,21 @@ final class K0: NSObject, NSApplicationDelegate, UNUserNotificationCenterDelegat
         let restart = NSMenuItem(title: "Restart", action: #selector(restartServer), keyEquivalent: "")
         restart.target = self
         menu.addItem(restart)
-        let notifications = NSMenuItem(title: "Notifications", action: #selector(toggleNotifications), keyEquivalent: "")
-        notifications.target = self
-        notifications.state = Notifications.enabled ? .on : .off
-        menu.addItem(notifications)
+        // macOS has the last word here, and when it is saying no the switch below would be a lie:
+        // ticked, and nothing ever arrives. So the item stops pretending and takes you to the one
+        // place where that can be undone.
+        if canNotify {
+            let notifications = NSMenuItem(title: "Notifications", action: #selector(toggleNotifications), keyEquivalent: "")
+            notifications.target = self
+            notifications.state = Notifications.enabled ? .on : .off
+            menu.addItem(notifications)
+        } else {
+            let blocked = NSMenuItem(title: "Notifications blocked by macOS…",
+                                     action: #selector(openNotificationSettings),
+                                     keyEquivalent: "")
+            blocked.target = self
+            menu.addItem(blocked)
+        }
         // The four modes sit next to these because they are the same kind of gesture — something
         // you leave as it is — but the tick comes from the server rather than from here: over
         // there the board changes them too, and the menu is rebuilt every two seconds anyway.
@@ -442,6 +519,14 @@ final class K0: NSObject, NSApplicationDelegate, UNUserNotificationCenterDelegat
         sender.state = Notifications.enabled ? .on : .off
     }
 
+    /// Straight to the Notifications pane. The colour of the dot in the menu bar still tells you
+    /// what is waiting — what is missing without this permission is only being told without
+    /// looking.
+    @objc func openNotificationSettings() {
+        guard let url = URL(string: "x-apple.systempreferences:com.apple.Notifications-Settings.extension") else { return }
+        NSWorkspace.shared.open(url)
+    }
+
     /// The server holds the mode, so here we only ask. The tick moves straight away so the menu
     /// is not left mute under your finger; the real one arrives with the next round, which is at
     /// most two seconds later.
@@ -516,7 +601,15 @@ final class K0: NSObject, NSApplicationDelegate, UNUserNotificationCenterDelegat
         return Int(text.trimmingCharacters(in: .whitespacesAndNewlines)) == expected
     }
 
+    /// There is one way to notify and no other. There used to be a second one — `osascript -e
+    /// 'display notification'` — for when the Mac would not deliver this bundle's own. It is gone:
+    /// a banner posted by `osascript` **belongs to Script Editor**, so it carries no card, has no
+    /// delegate, and clicking it opened Script Editor's file dialog instead of the terminal. A
+    /// notification you cannot click is worse than none, because you go and click it.
+    ///
+    /// When macOS will not deliver ours, the menu says so — see `buildMenu`.
     func notify(_ w: Waiting) {
+        guard canNotify else { return }
         let c = UNMutableNotificationContent()
         c.title = "k0"
         c.body = "\(w.title) · \(label[w.status] ?? w.status)"
@@ -524,20 +617,10 @@ final class K0: NSObject, NSApplicationDelegate, UNUserNotificationCenterDelegat
         c.sound = .default
         let r = UNNotificationRequest(identifier: "k0-\(w.id)-\(w.status)", content: c, trigger: nil)
         UNUserNotificationCenter.current().add(r) { error in
-            // If the Mac will not deliver this bundle's notifications, fall back to the system
-            // banner: it looks the same, but it is not clickable.
-            if error != nil || !self.notificationsAllowed { self.fallbackNotify(w) }
+            if let error { NSLog("k0: the notification was not delivered: \(error.localizedDescription)") }
         }
     }
 
-    func fallbackNotify(_ w: Waiting) {
-        let text = "\(w.title) · \(label[w.status] ?? w.status)"
-        let p = Process()
-        p.executableURL = URL(fileURLWithPath: "/usr/bin/osascript")
-        p.arguments = ["-e", "display notification \"\(text)\" with title \"k0\""]
-        try? p.run()
-    }
-
     // Clicking the notification goes straight to that terminal.
     func userNotificationCenter(_ center: UNUserNotificationCenter,
                                 didReceive response: UNNotificationResponse,

package/menubar/build.sh

@@ -22,7 +22,13 @@ swiftc -O -swift-version 5 -o "$BIN" K0MenuBar.swift
 
 # Ad-hoc signature: without one, macOS does not deliver the bundle's notifications.
 codesign --force --sign - --identifier com.k0.menubar "$APP" >/dev/null 2>&1 || {
-  echo "⚠️  signing failed: notifications will use the fallback banner"
+  echo "⚠️  signing failed: macOS will not deliver this app's notifications"
 }
 
+# And a signature is not enough on its own: macOS only grants the notification permission to an
+# app it knows about. The bundle never passes through Finder — launchd starts it — so nothing
+# else would ever register it, and the permission would be refused with no explanation.
+LSREGISTER=/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister
+if [ -x "$LSREGISTER" ]; then "$LSREGISTER" -f "$APP" >/dev/null 2>&1 || true; fi
+
 echo "✅ $(pwd)/$APP"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "k0-board",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "A board of sticky notes that drives your Claude Code sessions",
   "keywords": [
     "claude-code",
@@ -32,14 +32,17 @@
     "web",
     "menubar",
     "!menubar/k0.app",
-    ".claude/skills",
+    ".claude/skills/k0-import",
+    ".claude/skills/k0-changelog",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
     "start": "node server/index.js",
-    "test": "node test/clean.test.mjs && node test/states.test.mjs && node test/files.test.mjs && node test/mentions.test.mjs && node test/refs.test.mjs && node test/machine.test.mjs && node test/mode.test.mjs",
+    "test": "node --test \"test/*.test.mjs\"",
+    "test:watch": "node --test --watch \"test/*.test.mjs\"",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-exclude=\"platform/**\" --test-coverage-exclude=\"test/**\" \"test/*.test.mjs\"",
     "doctor": "node bin/k0-board.js doctor"
   }
 }

package/platform/contract.js

@@ -33,6 +33,10 @@
  * @property {object} metrics
  * @property {boolean} metrics.pressure              the kernel publishes a memory-pressure verdict
  * @property {boolean} metrics.swap                  swap usage is readable
+ * @property {object} servers
+ * @property {boolean} servers.run                   can start and stop a project's dev server
+ * @property {boolean} servers.ports                 can tell which port a process is listening on
+ * @property {boolean} servers.adopt                 can recognise a server started outside k0
  * @property {object} service
  * @property {boolean} service.autostart             can register a service that starts at login
  * @property {boolean} tray                          a menu bar / system tray icon is available
@@ -47,6 +51,7 @@ export const NO_CAPABILITIES = {
   terminal: { windows: false, font: false, readScreen: false, pasteWithoutSending: false, title: false },
   power: { keepAwake: false, keepDisplayAwake: false, lidSleep: false, battery: false },
   metrics: { pressure: false, swap: false },
+  servers: { run: false, ports: false, adopt: false },
   service: { autostart: false },
   tray: false,
   revealInFileManager: false,
@@ -101,6 +106,30 @@ export const NO_CAPABILITIES = {
  * @property {() => Promise<number>} pressureLevel  1 normal, 2 warning, 4 critical
  */
 
+/**
+ * The dev server a project runs while you are working on it — the one the globe in the column
+ * heading switches on and off. k0 starts it detached, so it outlives both the session that
+ * asked for it and k0 itself; what this adapter adds is the two things only the operating
+ * system knows, and the one gesture Node cannot make portably.
+ *
+ * @typedef {object} ServersAdapter
+ * @property {() => {run: boolean, ports: boolean, adopt: boolean}} capabilities
+ * @property {() => Promise<Map<number, Set<number>>>} listeners
+ *   Every process holding a TCP port open, and which ports. This is how k0 knows a server is
+ *   up: not by asking it, which would be a network request, but by seeing it hold the socket.
+ * @property {(pids: number[]) => Promise<Map<number, string>>} cwds
+ *   Where each of those processes is working from, which is what ties one to a repository.
+ *   An adapter that cannot say returns an empty map and reports `adopt: false`.
+ * @property {(command: string) => {file: string, args: string[]}} shell
+ *   How to run `command` inside a project. It goes through a LOGIN shell on Unix, and that is
+ *   not a flourish: the server runs from a launch agent whose PATH is barely more than
+ *   /usr/bin:/bin, while npm and node usually arrive from a version manager whose PATH only
+ *   exists inside a shell. It is the same reason `findClaude` ends up in a shell.
+ * @property {(root: number, pids: number[], signal?: string) => Promise<boolean>} stop
+ *   Stops the server and everything it started. `pids` is the whole subtree, `root` included:
+ *   killing the top process alone leaves the real server holding the port.
+ */
+
 /**
  * @typedef {object} ShellAdapter
  * @property {(absPath: string) => Promise<unknown>} revealInFileManager
@@ -129,6 +158,7 @@ export const NO_CAPABILITIES = {
  * @property {TerminalAdapter} terminal
  * @property {PowerAdapter} power
  * @property {MetricsAdapter} metrics
+ * @property {ServersAdapter} servers
  * @property {ShellAdapter} shell
  * @property {ServiceAdapter} service
  */

package/platform/darwin/index.js

@@ -1,6 +1,7 @@
 import * as terminal from './terminal.js'
 import * as power from './power.js'
 import * as metrics from './metrics.js'
+import * as servers from './servers.js'
 import * as shell from './shell.js'
 import * as service from './service.js'
 import { extras } from './extras.js'
@@ -13,12 +14,26 @@ export const capabilities = {
   terminal: terminal.capabilities,
   power: power.capabilities,
   metrics: metrics.capabilities,
+  servers: servers.capabilities(),
   service: service.capabilities,
   tray: true,
   revealInFileManager: true,
 }
 
-/** Nothing is missing here, so there is nothing to explain. */
-export const notes = {}
+/**
+ * Nothing is missing here, so there is nothing to explain — with one exception that is not
+ * about macOS but about a particular Mac: lsof ships with the system, and if it has been taken
+ * away k0 says what it can no longer see rather than showing every dev server as off.
+ */
+export const notes = {
+  ...(capabilities.servers.ports
+    ? {}
+    : {
+        'servers.ports':
+          'lsof was not found on this Mac. It ships with macOS, so something has removed or ' +
+          'blocked it — without it k0 cannot see which port a dev server is listening on, or ' +
+          'recognise one you started yourself.',
+      }),
+}
 
-export { terminal, power, metrics, shell, service, extras }
+export { terminal, power, metrics, servers, shell, service, extras }

package/platform/darwin/servers.js

@@ -0,0 +1,16 @@
+import { lsofListeners, lsofCwds, LSOF, stop, shell } from '../shared/servers.js'
+
+/**
+ * Dev servers on macOS. Everything comes out of one `lsof`, which ships with the system, so
+ * there is nothing to install and nothing that can be missing — but the capability is still
+ * probed rather than declared, because a machine with a locked-down /usr/sbin is a machine
+ * where the globe has to say so instead of showing every server as off.
+ */
+export const capabilities = () => {
+  const has = !!LSOF()
+  return { run: true, ports: has, adopt: has }
+}
+
+export const listeners = lsofListeners
+export const cwds = lsofCwds
+export { stop, shell }

package/platform/index.js

@@ -56,6 +56,13 @@ const unsupported = {
     swap: async () => ({ total: 0, used: 0 }),
     pressureLevel: async () => 1,
   },
+  servers: {
+    capabilities: () => ({ run: false, ports: false, adopt: false }),
+    listeners: async () => new Map(),
+    cwds: async () => new Map(),
+    shell: (command) => ({ file: process.env.SHELL || '/bin/sh', args: ['-lc', command] }),
+    stop: async () => false,
+  },
   shell: {
     revealInFileManager: async () => {},
     openBrowser: async () => {},
@@ -78,7 +85,8 @@ const unsupported = {
 const platform = load ? { ...unsupported, ...(await load()) } : unsupported
 
 export default platform
-export const { name, capabilities, notes, terminal, power, metrics, shell, service, extras } = platform
+export const { name, capabilities, notes, terminal, power, metrics, servers, shell, service, extras } =
+  platform
 
 /**
  * Is this capability available here? Takes a dotted path, so callers read as a question:

package/platform/linux/index.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url'
 import * as tmux from '../shared/tmux.js'
 import * as power from './power.js'
 import * as metrics from './metrics.js'
+import * as servers from './servers.js'
 import * as shell from './shell.js'
 import * as service from './service.js'
 import { NO_CAPABILITIES } from '../contract.js'
@@ -19,6 +20,7 @@ export const capabilities = {
   terminal: tmux.capabilities(),
   power: power.capabilities(),
   metrics: metrics.capabilities(),
+  servers: servers.capabilities(),
   service: service.capabilities(),
   tray: !!which('python3'),
   revealInFileManager: shell.capabilities().revealInFileManager,
@@ -52,9 +54,24 @@ export const notes = {
   ...(capabilities.tray
     ? {}
     : { tray: 'python3 with PyGObject is needed for a tray icon. The board works without it.' }),
+  ...(capabilities.servers.ports
+    ? {}
+    : {
+        'servers.ports':
+          'Neither ss nor lsof was found, so k0 cannot see which port a dev server is listening ' +
+          'on. Install iproute2 (for ss) and the globe will know where to send you.',
+      }),
+  ...(capabilities.servers.adopt
+    ? {}
+    : {
+        'servers.adopt':
+          'This system has no /proc, so k0 cannot tell which repository a dev server you ' +
+          'started yourself belongs to. The globe switches on and off the servers k0 started, ' +
+          'and says nothing about the others rather than showing them as off.',
+      }),
 }
 
-export { power, metrics, shell, service }
+export { power, metrics, servers, shell, service }
 
 /** Nothing on Linux reaches outside k0's own files, so there is nothing to consent to. */
 export const extras = []

package/platform/linux/servers.js

@@ -0,0 +1,41 @@
+import fs from 'node:fs'
+import { lsofListeners, ssListeners, LSOF, stop, shell } from '../shared/servers.js'
+import { which } from '../shared/run.js'
+
+/**
+ * Dev servers on Linux.
+ *
+ * Two differences from macOS. Listening sockets can come from `ss` as well as from `lsof`, and
+ * `ss` is the one a minimal system is likelier to have — it arrives with iproute2, where lsof
+ * arrives with nothing. And the working directory of a process is a symlink in /proc, which is
+ * both cheaper than lsof and always there, so adoption works even where neither tool is.
+ */
+const hasSs = () => !!which('ss', ['/usr/sbin/ss', '/usr/bin/ss', '/sbin/ss'])
+
+export const capabilities = () => ({
+  run: true,
+  ports: !!LSOF() || hasSs(),
+  // /proc is what makes this true, and it is what a container without it makes false.
+  adopt: fs.existsSync('/proc/self/cwd'),
+})
+
+/** lsof first when it is there — it answers both questions in the same shape as macOS. */
+export async function listeners() {
+  if (LSOF()) return lsofListeners()
+  return ssListeners()
+}
+
+/** One readlink each. A process that ends mid-loop is skipped, not an error. */
+export async function cwds(pids) {
+  const out = new Map()
+  for (const pid of pids) {
+    try {
+      out.set(pid, fs.readlinkSync(`/proc/${pid}/cwd`))
+    } catch {
+      /* gone, or not ours to look at */
+    }
+  }
+  return out
+}
+
+export { stop, shell }

package/platform/linux/tray.py

@@ -41,6 +41,18 @@ except (ImportError, ValueError) as err:  # pragma: no cover - depends on the de
     print(f"k0: no tray support on this desktop ({err}); the board still works", file=sys.stderr)
     raise SystemExit(0)
 
+# libnotify is what makes a notification clickable: `notify-send` can only shout, and a
+# notification you cannot click is one that tells you a session is waiting and then leaves you to
+# find its terminal yourself. Where it is missing we still shout — see `notify`.
+try:  # pragma: no cover - depends on the desktop
+    gi.require_version("Notify", "0.7")
+    from gi.repository import Notify
+
+    if not Notify.init("k0"):
+        Notify = None
+except (ImportError, ValueError, GLib.Error):
+    Notify = None
+
 
 PORT = os.environ.get("K0_PORT", "4319")
 BASE = f"http://127.0.0.1:{PORT}"
@@ -130,7 +142,35 @@ def api(path, payload=None):
         return None
 
 
-def notify(title, body):
+# Notifications still waiting to be clicked. They are held here for one reason: a Notify object
+# that Python garbage-collects takes its action callback with it, and the click then does nothing.
+_shown = []
+
+
+def _forget(notification):
+    if notification in _shown:
+        _shown.remove(notification)
+
+
+def notify(card_id, title, body):
+    """Say that a session is waiting, and let the click take you to it.
+
+    The action is named `default`, which is what a notification daemon calls the click on the
+    banner itself rather than on a button. Not every daemon honours actions; where it does not,
+    or where libnotify is missing altogether, this falls back to `notify-send`, which still says
+    what happened — the terminal is then one click away in the menu instead of none.
+    """
+    if Notify is not None:
+        try:
+            note = Notify.Notification.new(title, body, None)
+            note.add_action("default", "Open", lambda *_: api(f"/api/card/{card_id}/focus", {}))
+            note.connect("closed", _forget)
+            _shown.append(note)
+            if note.show():
+                return
+            _forget(note)
+        except (GLib.Error, TypeError):
+            pass
     try:
         subprocess.Popen(["notify-send", "-a", "k0", title, body])
     except OSError:
@@ -177,7 +217,7 @@ class Tray:
         if not self.first_pass:
             for card in waiting:
                 if (card["id"], card["status"]) not in self.seen:
-                    notify(LABELS.get(card["status"], "k0"), card.get("title", ""))
+                    notify(card["id"], LABELS.get(card["status"], "k0"), card.get("title", ""))
         self.seen = now
         self.first_pass = False