claude-inbox 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76328d9652ac26483494547c0b26c4099a5c8996816743c9b88b21dfebff0def
-  data.tar.gz: 15d80ce8e007a533cf70fe35a6215d148fe9f48925fb9b51b50a9913f43ebc9c
+  metadata.gz: 6c29f6bef2ba7ecc7f4d63161cfc064517e21f95a3a187313a1c5b882ae34786
+  data.tar.gz: 5195d163ef619f7f82a7224ca0a9b4dfe508fd23d8c1b3d87ab0a7b3b419cb28
 SHA512:
-  metadata.gz: 7cd8965adf8b34a34b8ee2fb412b8742d3457e2616cc3a0de549f4a9ee7b5fd9385635445e56bf6de37f3eef43da85ce5456df52da0319ac4a2312e223b872ed
-  data.tar.gz: 39c760a37be19c854d69c98b8e429fa5fcc48ab4bbfe03c00033e78bd217c161a29051074e70dbb98db234d1913f2320187eafcfabb68396a96a95c8eee1f0a3
+  metadata.gz: 9b051d9eeba2b19da5c9ced63f9dcd00030619cc4c7ac667f873da8db411ecf3c777352d2b373dfb7def00c9737c6d1ed0bc8edb0663b0a73d850c01e429d20d
+  data.tar.gz: cfe120a05f387965ba538ea48dbf726ad1bf379684b1515d213bead19d02803be8030b14abd938457671c6d80fe0d65ce1de1715632db8c304b768a5e6d46ae8

data/README.md

@@ -1,218 +1,156 @@
 # claude-inbox
 
-Inbox-style triage on top of Claude Code's background sessions. A companion to
-`claude agents`, not a replacement: it reads the same daemon state through
-`claude agents --json` and adds snooze, auto-settle and the session's pull
-request.
+An inbox for Claude Code's background sessions. It lists what `claude agents`
+lists and adds snooze, settle, pinning and each session's pull request.
 
 ![claude-inbox with one working session, one snoozed and the settled section folded](docs/screenshot.png)
 
 ## Install
 
+Requires Ruby 3.2+ and `claude` on PATH.
+
 ```
 gem install claude-inbox
 claude-inbox
 ```
 
-Requires Ruby 3.2+ and a `claude` on PATH with the agents feature. Versions
-are published to rubygems and listed under GitHub Releases.
-`claude-inbox --version` prints the installed version.
+Put arguments you want on every launch in `~/.config/claude-inbox/config`.
+
+To add the pane to every Claude Code session:
+
+```
+claude-inbox install
+```
+
+`claude-inbox install --force` also replaces any other copy of the pane.
+
+## Claude Code pane
+
+The same inbox as a pane inside Claude Code, docked beside the transcript in
+a fullscreen terminal.
+
+![The inbox pane docked beside a Claude Code transcript](docs/pane.png)
+
+`/inbox` opens it, `ctrl+x tab` focuses it and `esc` leaves. The keys are the
+ones below, with `ge` for `G`, `n` `p` for `Tab` `Shift+Tab`, and no `a`,
+`P`, `X`, `Ctrl-x`, `/` or `R`. `Enter` switches to the session when you
+attached through `claude-inbox`.
+
+It opens when a session starts. To stop that, set
+`pluginConfigs.inbox-pane.options.openOnStart` to `false` in
+`~/.claude/settings.json`.
 
 ## Sections
 
-1. **Pinned.** Parked at the top by hand, regardless of state. `t` toggles it.
-2. **Needs you.** `blocked` or `failed`, until you attach to it (see
-   Acknowledge below).
-3. **Active.** `working`, recently finished sessions that haven't settled yet,
-   interactive sessions, and a needs-you session you've attached to that
-   hasn't resolved. Interactive sessions report only `status`, so it gets
-   mapped: busy is working, idle is done, waiting needs you. The daemon calls
-   a terminal you opened yourself, a Remote Control worker, a sub-agent and a
-   headless `claude -p` run all "interactive"; the inbox tells them apart from
-   the process tree. Sub-agents and headless runs are dropped, since nobody is
-   sitting in them. Remote sessions settle and snooze like any other row,
-   and Enter pulls one into the daemon (see Remote Control below). A
-   terminal you are sitting in never settles and can't be attached, peeked
-   or stopped from outside; Enter tells you so.
-4. **Snoozed.** Sorted by wake time, parked ("until I wake it") entries last.
-   Collapsed; Enter expands.
-5. **Settled.** Parked with `x`, or whose pull request is merged or closed.
-   Collapsed; Enter expands.
-
-A row with a pull request shows it after the state: `#885 open`, `#885 draft`,
-`#885 merged`, `#885 closed`. `o` opens it in the browser.
-
-`working` from the daemon covers two situations, and the row says which. A
-spinner and `working` mean the agent is thinking. A steady `◌` and `idle · 1
-shell` mean the agent has stopped and is waiting on work it started, such as a
-`--watch` shell or a sub-agent. That is why a session with nothing left to do
-can sit there for an hour. The open work is named next to the state either
-way: `working · 2 agents`, `idle · 1 shell`.
-
-Under each row in Pinned, Needs You and Active is the line `claude agents`
-prints too: what it is waiting on while blocked (`↳ confirm: drop the top
-line?`), what it produced once done, otherwise its status line. A terminal you
-opened yourself has none and shows its directory instead.
-
-A session you gave a color to with `/color` wears it on the label. Nothing
-else is tinted, so a blocked session still looks blocked.
+1. **Pinned.** Rows you pinned with `t`.
+2. **Needs you.** Blocked or failed sessions you haven't attached to yet.
+3. **Active.** Everything else that's running or not yet settled, including
+   interactive terminals.
+4. **Snoozed.** Sorted by wake time. Collapsed.
+5. **Settled.** Settled with `x`, or every pull request is merged or closed.
+   Collapsed.
+
+Under each row is what the session is waiting on, what it produced, or its
+status line. A row with a pull request shows it as `#885 open`, `#885 merged`
+and so on. A steady `◌` with `idle · 1 shell` means the agent stopped and is
+waiting on a shell or sub-agent it started.
 
 ## Keys
 
-Vim bindings; arrows work as well as `j`/`k`. The mouse works too, in
-terminals that report it: clicking a row selects and attaches, and the wheel
-moves the selection. Apple Terminal reports neither, so there the wheel
-scrolls its own history and clicks do nothing.
+Vim bindings. Arrows and the mouse work too.
 
 | Key | Action |
 |---|---|
 | `j` `k` | move down / up |
 | `gg` `G` | first / last row |
 | `Ctrl-d` `Ctrl-u` | half page down / up (`Ctrl-f` `Ctrl-b` full page) |
-| `Enter` `l` | attach (full-screen handoff; `←` or `Ctrl+Z` return here), adopt a remote session, or expand Snoozed / Settled |
-| `Tab` `Shift+Tab` | jump to the next / previous section |
-| `h` | close the peek pane, else collapse the current Snoozed / Settled fold |
-| `za` `zo` `zc` | toggle / open / close the Snoozed or Settled fold under the cursor |
+| `Enter` `l` | attach (`←` or `Ctrl+Z` returns here), adopt a remote session, or expand Snoozed / Settled |
+| `Tab` `Shift+Tab` | next / previous section |
+| `h` | close the peek pane, else collapse the current fold |
+| `za` `zo` `zc` | toggle / open / close the fold under the cursor |
 | `p` | toggle the read-only peek pane |
 | `J` `K` (`Ctrl-e` `Ctrl-y`) | scroll the peek pane |
-| `n` | new session (see below) |
+| `n` | new session |
+| `N` | pair a phone |
 | `t` | pin / unpin |
 | `s` | snooze: `1` 15m · `2` 1h · `3` tomorrow 9am · `4` until woken |
-| `u` | wake a snoozed session now, or bring back one you settled |
-| `x` | settle a working or needs-you session by hand (returns when it changes state, unless it just finished) |
-| `a` | set a local alias (never touches the real session name) |
-| `o` | open the session's pull request in the browser |
+| `u` | wake a snoozed session, or bring back a settled one |
+| `x` | settle by hand |
+| `a` | set a local alias |
+| `o` | open the pull request in the browser |
 | `w` | open the session at claude.ai/code |
-| `P` | link a pull request by hand (empty clears; the scanned links return) |
-| `X` | stop the session (`y` to confirm) |
-| `Ctrl-x` | delete the session for good, conversation and worktree with it (`y` to confirm) |
-| `/` | filter by name, cwd, the prompt it started from, or what it is doing now; `Enter` keeps it, `Esc` clears |
+| `P` | link a pull request by hand (empty clears) |
+| `X` | stop the session; `Enter` resumes it later |
+| `Ctrl-x` | delete the session, transcript and worktree for good |
+| `/` | filter; `Enter` keeps it, `Esc` clears |
 | `R` | poll now |
 | `q` | quit |
 
-`X` and `Ctrl-x` both ask first, and both take `y`, but they are not the same
-thing. `X` runs `claude stop`: the process ends, the conversation is kept, and
-`Enter` resumes it later. `Ctrl-x` runs `claude rm`: the session, its
-transcript and its worktree all go. Nothing resumes afterwards, so read the
-box before answering.
+`X` and `Ctrl-x` both ask for `y` first.
 
 ### New session
 
-`n` opens a form: prompt, name, directory, model, effort, permissions,
-worktree, Remote Control. `Tab` / `Shift+Tab` move between fields, `Esc` cancels. Choice
-fields cycle with `h` `l` or the arrows; "default" shows what your settings
-resolve to. The directory defaults to the selected row's, and `Tab` completes
-it.
-
-`Ctrl-S` starts the session and drops you back in the inbox; `Ctrl-O` starts
-it and attaches. Either way the new row is selected once it shows up. It runs
-`claude --bg "<prompt>"` in that directory, with only the flags you changed.
-
-The prompt is multi-line; `Enter` breaks a line. Paste an image with `Cmd-V`
-(or `Ctrl-V`), or drop a file onto the window, and it lands at the cursor as
-an `[Image #1]` token the prompt can point at: "make the button look like
-[Image #1]". Pasted images are saved under `~/.config/claude-inbox/images/`
-for 14 days; a dropped file is referenced where it is. Reading the clipboard
-is macOS only.
-
-Remote Control set to yes starts the session with `--remote-control`, so it
-runs under the daemon like any other row and is also listed at claude.ai/code
-and in the Claude mobile app. See Remote Control below.
-
-Slash commands work as at Claude Code's own prompt. Type `/` at the start of a
-word for a menu of your skills and commands, plugin skills as `plugin:name`,
-claude.ai's synced skills as `anthropic-skills:name`. `↑` `↓` choose, `Tab` or
-`Enter` insert, `Esc` closes the menu. Built-ins such as `/init` aren't listed
-but still work.
+`n` opens a form for the prompt, name, directory, model, effort, permissions,
+worktree and Remote Control. `Tab` moves between fields, `Ctrl-S` starts the
+session and `Ctrl-O` starts it and attaches.
+
+Paste an image on macOS, or drop a file into the prompt, and refer to it as
+`[Image #1]`. Type `/` for a menu of your skills.
 
 ## How sessions move
 
-**Wake.** A snoozed session returns when its timer elapses, when you press
-`u`, or when it becomes blocked or failed after being snoozed. A session that
-was already blocked when you snoozed it stays snoozed; that is the point of
-snoozing. `u` also brings back a settled row and puts it wherever its raw
-state belongs.
-
-**Acknowledge.** Attaching to a needs-you session marks its current state
-seen and moves it to Active. It comes back to Needs You when its state
-changes again. Still blocked with a new prompt doesn't count.
-
-**Settle.** Settled by hand with `x`, or because every pull request it has is
-merged or closed. A hand-settled session stays put when it finishes, and
-returns as soon as it changes state in any other way. `failed` never settles.
-A session with no pull request never settles on its own, however long it has
-been quiet. A session with one stays Active while any of its PRs is open or a
-draft.
-
-**Reap.** A background session quiet for 14 days is deleted on the next poll
-with `claude rm`, so the transcript and the worktree go with it, same as
-`Ctrl-x`. This is the one thing here that destroys anything without asking
-first. Reaping does not key on Settled: an open draft keeps a row in Active
-for ever, and those are precisely the rows that need reaping. Idle time is the
-only clock.
-
-Never reaped, whatever the clock says: a `working` session, one that still
-holds a process, a pin, and a snooze. `failed` is reaped, even though it never
-settles; after a fortnight of not looking at it you never will. A pin or a
-parked snooze is the way to keep a session indefinitely.
-
-Unpushed work is safe. `claude rm` refuses a worktree holding commits that
-aren't pushed, and nothing here ever overrides that refusal. Every reap
-appends a line to `~/.config/claude-inbox/reaped.log`, the last record a
-session existed once its transcript is gone. `CLAUDE_INBOX_NO_REAP=1` turns
-reaping off.
+A snoozed session wakes when its timer runs out, when you press `u`, or when
+it becomes blocked or failed.
+
+Attaching to a needs-you session moves it to Active until its state changes
+again.
+
+A session settles when you press `x` or when all its pull requests are merged
+or closed. A session without a pull request only settles by hand.
+
+The inbox deletes background sessions that have been idle for 14 days, with
+`claude rm`. Working, pinned and snoozed sessions are kept, and `claude rm`
+refuses a worktree with unpushed commits. Each deletion is logged to
+`~/.config/claude-inbox/reaped.log`. Set `CLAUDE_INBOX_NO_REAP=1` to turn it
+off.
 
 ## Remote Control
 
-Every background session has a page at claude.ai/code, where you can follow
-it from a browser or the Claude mobile app; `w` opens it. A session with
-Remote Control on can also be driven from there, the way `claude
---remote-control` and `/rc` allow in a terminal. Its row wears a `⇅` after
-the state. Two kinds of session have it:
-
-- A background session the `n` form started with Remote Control set to yes,
-  or one you ran as `claude --bg "…" --remote-control` yourself. It is a
-  daemon row like any other: `Enter` attaches, `X` stops, and it keeps its
-  Remote Control across a stop and a wake, since the daemon saves the flag.
-- A worker a `claude remote-control` server spawned for a request from your
-  phone. That is how a session started away from the desk lands on this
-  machine. The daemon calls it interactive and can't attach to it, so
-  `Enter` offers to adopt it instead: `y` ends the worker and resumes the
-  conversation as a background session under the same id, with Remote
-  Control on, and attaches. The phone session you were in ends there and a
-  new one takes its place, with the whole conversation; the server keeps
-  running for the next request. A worker nobody has messaged yet has
-  nothing to adopt, and Enter says so.
-
-## Pull request state
-
-The daemon scans each background session's transcript for PR links, so a
-session that only reviews a PR gets it too. Interactive sessions aren't
-scanned; `P` sets the link by hand for those, or to correct a bad scan.
-
-State comes from whatever Claude Code last saw, then `gh pr view` on the
-poller thread, at most once a minute per PR. Without `gh` the cached state is
-all you get. The list goes up before gh is asked, so the inbox is up in under
-a second.
-
-## Setup
-
-The right end of the header shows how much of your Claude subscription's
-5-hour and 7-day rate limit windows you have used, as a ten-cell bar per
-window that turns yellow at 70% and red at 90%, like the context bar many
-status lines draw:
+Sessions with Remote Control show `⇅`, and `w` opens them at claude.ai/code.
+A session started from your phone through `claude remote-control` can't be
+attached directly, so `Enter` offers to adopt it as a background session.
+
+## Starting sessions from your phone
+
+With `--listen-lan`, a phone on your network can start sessions.
+
+![The inbox beside the phone form, pairing and then starting a session](docs/remote-start.gif)
+
+1. Run `claude-inbox --listen-lan`.
+2. Press `N`, then `c` to copy the pairing URL.
+3. Open it on the phone in Safari and tap Share, then Add to Home Screen.
+4. Open the Inbox icon, paste the URL again and tap Pair.
+
+LAN mode is plain HTTP. Use it only on a network you control, and press `r`
+in the `N` dialog if the URL leaks. [docs/remote-start.md](docs/remote-start.md)
+covers ssh, the JSON API and an iOS Shortcut.
+
+## Pull requests
+
+Pull requests show up when a session's transcript links to them. Install
+`gh` to keep their state current. Use `P` to link one by hand.
+
+## Usage bars
+
+The header can show your 5-hour and 7-day rate limit usage:
 
 ```
 session ██░░░░░░░░ 24% · 3h left  week ████░░░░░░ 41% · 2d left
 ```
 
-`session` is the 5-hour window and `week` the 7-day one, as Claude's own
-`/usage` names them; `3h left` is how long until that window resets. It needs
-a Pro or Max account and a one-time setup.
-
-Claude Code passes the numbers to your [status line](https://code.claude.com/docs/en/statusline)
-script every turn, and the inbox reads them from a file that script writes.
-Put these two lines in the script, just after it reads stdin:
+This needs a Pro or Max account. Add these lines to your
+[status line](https://code.claude.com/docs/en/statusline) script, just after
+it reads stdin. Run `/statusline` first if you don't have one.
 
 ```bash
 input=$(cat)
@@ -220,14 +158,6 @@ limits=$(echo "$input" | jq -c '.rate_limits // empty')
 [ -n "$limits" ] && echo "$limits" > ~/.claude/rate_limits.json.tmp && mv ~/.claude/rate_limits.json.tmp ~/.claude/rate_limits.json
 ```
 
-If you have no status line script, run `/statusline` in any session and it
-writes one for you, then add the lines to that. Keep the `-n` check: a
-session's first status line run has no numbers yet, and writing anyway would
-blank the file.
-
-The bars stay off until the file exists, and goes off again once the file
-is more than fifteen minutes old.
-
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).

data/exe/claude-inbox

@@ -8,25 +8,88 @@ if ARGV.include?("--version")
   exit
 end
 
+require "claude_inbox/mod"
+
+# The stable path to the Claude Code pane, for CLAUDE_CODE_PLUGIN_DIRS.
+if ARGV.include?("--mod-dir")
+  puts ClaudeInbox::Mod.link(force: true)
+  exit
+end
+
+if ARGV.first == "install"
+  begin
+    installed = ClaudeInbox::Mod.install(force: ARGV.include?("--force"))
+  rescue JSON::ParserError
+    abort "claude-inbox: ~/.claude/settings.json is not valid JSON, so it was left alone"
+  end
+  installed.removed.each { |dir| puts "Removed #{dir} from ~/.claude/settings.json." }
+  puts "The pane now runs #{ClaudeInbox::Mod::COMMAND || "claude-inbox from your PATH"}." if installed.command_set
+  puts installed.added ? "Added the pane to ~/.claude/settings.json. New Claude Code sessions load it; /inbox opens it." :
+    "The pane is already in ~/.claude/settings.json."
+  exit
+end
+
 require "claude_inbox/app"
+require "claude_inbox/config"
+require "claude_inbox/writer_lock"
+require "tmpdir"
+
+fixture = ARGV.include?("--fixture")
+# A fixture run takes the listen flags, for trying the API with curl, but
+# not the environment or the config file, which are for the real inbox.
+begin
+  argv = fixture ? ARGV : ClaudeInbox::Config.argv(ARGV)
+  listen = ClaudeInbox::Remote::Listener.options(argv, fixture ? {} : ENV)
+rescue ArgumentError => e
+  abort "claude-inbox: #{e.message}"
+end
 
 # Crash traces go here instead of the alt screen when set.
 $stderr.reopen(ENV["CLAUDE_INBOX_STDERR"], "a") if ENV["CLAUDE_INBOX_STDERR"]
 
 opts = {}
-if (i = ARGV.index("--fixture"))
-  agents = ARGV[i + 1]
+if fixture
+  agents = argv[argv.index("--fixture") + 1]
   fixtures = File.dirname(agents)
   opts[:client] = ClaudeInbox::FixtureClient.new(agents, logs: File.binread(File.join(fixtures, "logs_raw.txt")))
   opts[:store] = ClaudeInbox::Store.new(path: nil)
   opts[:pull_requests] = ClaudeInbox::PullRequests.new(cache_path: File.join(fixtures, "gh-pr-status-cache.json"), resolved_path: nil, gh: nil)
+  # Its own token, lock and images, so a test inbox can neither rotate the
+  # token phones are paired with nor hold the real inbox's lock.
+  dir = File.join(Dir.tmpdir, "claude-inbox-fixture")
+  opts[:listen] = listen&.merge(fixture: true, pairing: ClaudeInbox::Remote::Pairing.new(path: File.join(dir, "listen.json")),
+    lock_path: File.join(dir, "listen.lock"), images_dir: File.join(dir, "images"))
 else
   # The only place the reaper is armed. Everything else — tests, --fixture,
-  # anything embedding App — gets one that deletes nothing.
+  # anything embedding App — gets one that deletes nothing. The listener,
+  # likewise, comes only from this file, and only when asked for.
   opts[:client] = ClaudeInbox::AgentsClient.new
   opts[:store] = ClaudeInbox::Store.new
   opts[:reaper] = ClaudeInbox::Reaper.new(opts[:client], opts[:store])
+  opts[:snapshot] = ClaudeInbox::Snapshot.new
+  opts[:switch] = ClaudeInbox::Switch.new
+  opts[:actions] = ClaudeInbox::Actions.new
+  opts[:listen] = listen
+end
+opts[:color] = false if argv.include?("--no-color")
+
+if argv.include?("--headless")
+  abort "claude-inbox: --headless takes no --fixture" if fixture
+  require "claude_inbox/headless"
+  exit(ClaudeInbox::Headless.new(client: opts[:client], store: opts[:store]).run ? 0 : 1)
+end
+
+# The first inbox you can see is the snapshot's writer: a headless one gives
+# way to it, and a second inbox reads along, writing and deleting nothing.
+# Held for the life of this process by this reference.
+writer_lock = fixture ? ClaudeInbox::WriterLock.disabled : ClaudeInbox::WriterLock.new
+unless writer_lock.take(role: "inbox")
+  opts[:store] = ClaudeInbox::Store.new(writable: false, relay: ClaudeInbox::Actions.new)
+  opts[:reaper] = ClaudeInbox::Reaper.disabled
+  opts[:snapshot] = ClaudeInbox::Snapshot.disabled
+  opts[:actions] = ClaudeInbox::Actions.disabled
 end
-opts[:color] = false if ARGV.include?("--no-color")
+# So the pane settings.json names is the installed version's, after a gem update too.
+ClaudeInbox::Mod.link unless fixture
 
 ClaudeInbox::App.new(**opts).run

data/lib/claude_inbox/actions.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module ClaudeInbox
+  # What another front end asks the inbox to do to a session: one file per
+  # request under a directory, taken and applied here, so the triage rules
+  # and the state file have one owner. A request for a session the last
+  # poll did not list waits a little, since it may have just started; one
+  # the store cannot honour after that, or a verb it lacks, is dropped.
+  class Actions
+    DEFAULT_DIR = File.join(Dir.home, ".config", "claude-inbox", "actions")
+    VERBS = %w[settle wake pin snooze acknowledge].freeze
+    SNOOZES = %w[m15 h1 tomorrow_9am until_woken].freeze
+    # A file still being written parses as nothing for milliseconds; a
+    # session not yet polled appears within one poll.
+    GRACE = 10
+
+    def self.disabled = new(dir: nil)
+
+    def initialize(dir: DEFAULT_DIR, clock: -> { Time.now })
+      @dir = dir
+      @clock = clock
+      @sent = 0
+    end
+
+    # Leaves one request for the writer, as the pane does; `from` names the
+    # asker, and a count keeps two requests in one millisecond apart.
+    def request(action, id, choice: nil, from: "inbox-#{Process.pid}")
+      return unless @dir
+      FileUtils.mkdir_p(@dir)
+      at = (@clock.call.to_f * 1000).to_i
+      request = {"action" => action, "id" => id, "at" => at}
+      request["choice"] = choice if choice
+      @sent += 1
+      File.write(File.join(@dir, "#{from}-#{at}-#{@sent}.json"), JSON.generate(request))
+    end
+
+    # Applies every request on disk to `store` and returns how many it took.
+    def drain(store)
+      return 0 unless @dir && File.directory?(@dir)
+      keys = store.sessions.select(&:actionable?).map(&:key)
+      Dir.glob(File.join(@dir, "*.json")).sort.count { |path| take(path, store, keys) }
+    end
+
+    private
+
+    # One file: false when it is left for a later pass or dropped, true once
+    # applied. Another drainer may take it first, which is nothing to report.
+    def take(path, store, keys)
+      request = parse(path)
+      return false if request.nil?
+      return false if !keys.include?(request["id"]) && young?(request)
+      File.delete(path)
+      apply(store, request, keys)
+    rescue Errno::ENOENT
+      false
+    end
+
+    # Nil leaves the file for the next pass: it is torn or early, and young.
+    def parse(path)
+      request = JSON.parse(File.read(path))
+      request = {} unless request.is_a?(Hash)
+      return request if File.mtime(path) < @clock.call - GRACE
+      (request.key?("id") && request.key?("action")) ? request : nil
+    rescue JSON::ParserError
+      (File.mtime(path) < @clock.call - GRACE) ? {} : nil
+    end
+
+    def young?(request)
+      at = request["at"].to_i / 1000
+      at.positive? && Time.at(at) >= @clock.call - GRACE
+    end
+
+    def apply(store, request, keys)
+      id = request["id"]
+      return false unless keys.include?(id) && VERBS.include?(request["action"])
+      case request["action"]
+      when "settle" then store.settle(id)
+      when "wake" then store.wake(id)
+      when "pin" then store.toggle_pin(id)
+      when "acknowledge" then store.acknowledge(id)
+      when "snooze"
+        return false unless SNOOZES.include?(request["choice"])
+        store.snooze(id, request["choice"].to_sym)
+      end
+      true
+    end
+  end
+end