run attention: publish to ntfy and surface what needs the operator

Nothing told the operator that a run was waiting for a person or had failed; they
found out by going looking. A run that needs attention now reaches the ntfy they
already run, and the app answers "what needs me now" in one live, ordered surface.

Server (smallest change, reusing the existing publisher):
- internal/server/notify.go adds notifyRun, called from finishRunState (failed)
  and when a run parks on a human (runner.go runLoop). It publishes to the same
  already-configured `system` destination through the unchanged stage.PublishNtfy,
  so there is no second publisher, topic or service and the token handling is the
  stage's own. runAttentionEvent maps only waiting and failed; queued, running,
  succeeded, canceled and interrupted publish nothing.
- No storms: runner.attentionSent records sequence:event per run before publishing,
  so a run that stays waiting is never republished on a re-request or restart, and
  a stage notify policy that already covers the same event marks it first so the
  run-level default is suppressed. The set is dropped when the run is terminal. A
  delivery failure is logged, never fails the run, and is not retried.
- The payload names the run and pipeline and carries a click action
  pipelines://run/<id> (validated: absolute URL, no userinfo, no fragment, no
  credentials). PublishNtfy gained the optional click parameter; existing callers
  pass "".

App:
- AndroidManifest/MainActivity declare the pipelines://run/<id> deep link
  (singleTop); runIdFromDeepLink parses it and PipelinesApp opens that run once,
  clearing the link. It opens a run; it starts nothing.
- ui/Attention.kt is the pure model (status -> Decision/Failed/Finished or
  nothing, ordered by kind then newest-first) and ui/components/AttentionSurface.kt
  is the floating indicator plus bottom sheet. It is derived from the same run
  events the server already pushes, so an entry appears with no refresh and clears
  when resolved; a finished run clears once looked at, and any entry can be
  dismissed, persisted in SettingsRepository. The existing destinations, pill and
  bottom strip are untouched and no competing navigation surface is added.

Checked before committing:
- Packaged authoring skill references: internal/author/skill/references/
  notifications.md documents the automatic run-attention notifications and the
  app surface. The only packaged "template" carrying notify is that reference; no
  pipeline definition template exists to update and install.go's managed file list
  is unchanged (notifications.md already existed).
- Repository guidelines: docs/ntfy.md gains an "Automatic run-attention
  notifications" section and no longer claims "No block means no notifications";
  the top-level README phone-notifications note now says a waiting/failed run
  notifies automatically; android/README.md gains the dated feature section and
  supersedes the previous section's note that the attention surface was absent.
- docker.md, install docs and the CLI/TUI docs describe mechanisms this change
  does not alter; left as they are.

Tests: go test ./internal/server/... ./internal/stage/... ./internal/author/...
all ok; notify_test.go covers the event mapping and the real HTTP delivery
(destination, topic, click, no duplicate). Android :app:testDebugUnitTest ->
BUILD SUCCESSFUL, 58 suites / 531 tests / 0 failures (new AttentionTest, 13 cases,
covering ordering, appearing from a push, clearing on resolution, dismissal, the
empty case, persistence and the deep link). Device screenshots and the phone's own
notification are visual review's per the brief's device policy.

Scope: android/ plus the smallest server change; no new dependency, no run started
from the app, no installer or Docker change.
This commit is contained in:
2026-10-17 16:11:57 +01:00
parent f782c51c18
commit 890d267c71
17 changed files with 1215 additions and 25 deletions
+66
View File
@@ -5944,3 +5944,69 @@ surface" named in the brief is not present in this tree, so the decision is
reachable from the run detail and its stage and the shared component is ready for
it. No packaged skill reference was touched: the decide protocol is unchanged and
already documented, and this is an app-UI change.
## Run attention surface and phone notifications (17 Oct 2026)
> Supersedes the note at the end of the previous section: the run-attention
> surface the brief named is now present in this tree. The server publishes the
> notification; the app shows the same information in one live surface.
A run that needs a person — waiting for a human decision, or failed — now reaches
the operator through the ntfy they already run, and the app answers "what needs me
now" in one ordered list. The server change is the smallest that reuses the
existing delivery machinery; there is no second publisher, topic or service.
- **One run-level notification, reusing the stage's publisher.** `internal/server/
notify.go` adds `notifyRun`, called from `finishRunState` (failed) and when a run
parks on a human (`runner.go` `runLoop`). It publishes to the same `system`
destination through the unchanged `stage.PublishNtfy`, with the operator's
configured token handling, so nothing is duplicated. `runAttentionEvent` maps
only `waiting` and `failed`; queued/running/succeeded/canceled/interrupted
produce `""` and publish nothing.
- **No storms.** `runner.attentionSent` (guarded by `attentionMu`) records
`sequence:event` per run before publishing, so a run that stays waiting is never
republished on a re-request or restart, and a stage `notify` policy that already
covers the same event (`on=waiting`, or a failure hook) marks it first so the
run-level default is suppressed. The set is dropped when the run is terminal
(`forgetAttention`). A delivery failure is logged, never fails the run, and is
not retried.
- **The payload opens the run.** It names the run id and pipeline, and carries a
`click` action `pipelines://run/<id>` (validated in `validNtfyClick` — absolute
URL, no userinfo, no fragment, no credentials). `AndroidManifest.xml` declares
the `pipelines`/`run` deep link on `MainActivity` (`launchMode=singleTop`);
`runIdFromDeepLink` parses it and `PipelinesApp` opens that run once, clearing
the link so a rotation re-opens nothing. It opens a run; it starts nothing.
- **One attention surface.** `ui/Attention.kt` is the pure model: a run status maps
to `Decision`/`Failed`/`Finished` (or nothing), and `attentionEntries` orders by
kind then newest-first. `ui/components/AttentionSurface.kt` renders a floating
indicator in the same bottom container as the destination pill — visible from
every destination and window width — that opens a bottom sheet listing the run,
its pipeline and what it needs, with a per-row dismiss. The indicator draws
nothing when the list is empty. No competing navigation surface is added.
- **Live and self-clearing.** The list is derived from the same `RuntimeState`
pushes the runs list folds, so an entry appears with no refresh and clears when
the run is resolved (the decision answered, the failure retried). A finished run
clears once the list is opened; any entry can be deliberately dismissed;
dismissals and looked-at finishes persist in `SettingsRepository` as one
serializable preference. Opening a non-decision entry deals with it.
Tests: `internal/server/notify_test.go` covers the event mapping (waiting, failed,
nothing else) and the real HTTP delivery (destination, topic, click, no
duplicate); `AttentionTest` (13 cases) covers the app's mapping, ordering,
appearing from a pushed event, clearing on resolution, dismissal, the empty case,
persistence and the deep-link parser.
Evidence (this pass, macOS, JDK 17 `/opt/homebrew/opt/openjdk@17`, cached Gradle
8.11.1, `ANDROID_HOME=$HOME/Library/Android/sdk`):
- `go build ./...` → success; `go test ./internal/server/... ./internal/stage/...
./internal/author/...` → `ok` for all three packages.
- `gradle :app:testDebugUnitTest --offline --no-daemon --console=plain` →
`BUILD SUCCESSFUL`; the JUnit XMLs total **58 suites / 531 tests / 0 failures /
0 errors / 0 skipped** (up from 57 suites / 518 tests: the new `AttentionTest`).
Not verified in this pass: the on-device indicator/list/finished/empty screenshots
and the phone's own notification — the brief keeps ordinary code review to the
build and the unit tests, and visual review owns the operator's Pixel 9 Pro XL.
The concrete payload delivered to the local ntfy service was reproduced by the
code review with a live curl subscriber; the device captures are visual review's.