J2: the tool runner tells a subscribed bundle how its module's consumer stands, as mesh/heartbeat (stdio.OnHeartbeat), at each idle beat and once Missed (ADR 0615, ADR 0621, issue 1966)

Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig

node-tools/internal/launch/event_answer_test.go

@@ -19,6 +19,9 @@ while IFS= read -r line; do
     *'"method":"tools/list"'*)
       printf '{"jsonrpc":"2.0","id":%s,"result":{"tools":[]}}\n' "$id"
       printf '{"jsonrpc":"2.0","id":"s1","method":"mesh/subscribe","params":{"pattern":"#"}}\n' ;;
+    *'"method":"mesh/heartbeat"'*)
+      params=$(printf '%s' "$line" | sed -n 's/.*"params":\(.*\)}$/\1/p')
+      printf '{"jsonrpc":"2.0","id":"h1","method":"mesh/publish","params":%s}\n' "$params" ;;
     *'"method":"mesh/event"'*)
       case "$ANSWER" in
         error) printf '{"jsonrpc":"2.0","id":%s,"error":{"code":-32000,"message":"Unexpected end of JSON input"}}\n' "$id" ;;
@@ -30,11 +33,18 @@ done
 `
 
 type subscribing struct {
-	mu      sync.Mutex
-	deliver func(json.RawMessage) error
+	mu        sync.Mutex
+	deliver   func(json.RawMessage) error
+	beat      func(json.RawMessage)
+	published []json.RawMessage
 }
 
-func (b *subscribing) Publish(json.RawMessage) error                          { return nil }
+func (b *subscribing) Publish(p json.RawMessage) error {
+	b.mu.Lock()
+	b.published = append(b.published, p)
+	b.mu.Unlock()
+	return nil
+}
 func (b *subscribing) Ask(json.RawMessage) (json.RawMessage, error)           { return nil, nil }
 func (b *subscribing) State(string, json.RawMessage) (json.RawMessage, error) { return nil, nil }
 func (b *subscribing) Log(string, json.RawMessage) (json.RawMessage, error)   { return nil, nil }
@@ -53,10 +63,11 @@ func (b *subscribing) BusStateWatch(string, json.RawMessage, func(json.RawMessag
 	return func() {}, nil
 }
 func (b *subscribing) Begin(string) (string, func()) { return "", func() {} }
-func (b *subscribing) Subscribe(d func(json.RawMessage) error) error {
+func (b *subscribing) Subscribe(d func(json.RawMessage) error, beat func(json.RawMessage)) error {
 	b.mu.Lock()
 	defer b.mu.Unlock()
 	b.deliver = d
+	b.beat = beat
 	return nil
 }
 
@@ -104,3 +115,45 @@ func TestAnEventIsTakenByAnyAnswerThatIsNotAnError(t *testing.T) {
 func (b *subscribing) LogWatch(json.RawMessage, func(json.RawMessage) error) (func(), error) {
 	return func() {}, nil
 }
+
+// The runtime's word on the module's consumer between events reaches the child that subscribed as `mesh/heartbeat`,
+// unchanged (stdio.OnHeartbeat reads it in the bundle).
+func TestTheWordOnTheConsumerBetweenEventsReachesTheBundleThatSubscribed(t *testing.T) {
+	entry := filepath.Join(t.TempDir(), "bundle")
+	if err := os.WriteFile(entry, []byte(answeringBundle), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	b := &subscribing{}
+	l, err := Start("plex", entry, append(os.Environ(), "ANSWER=result"), b, t.Logf)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(l.Stop)
+	var beat func(json.RawMessage)
+	for i := 0; beat == nil; i++ {
+		b.mu.Lock()
+		beat = b.beat
+		b.mu.Unlock()
+		if i > 100 {
+			t.Fatal("the bundle never subscribed")
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+	word := json.RawMessage(`{"at":"2026-11-04T13:00:00Z","missed":true,"why":"the bus ended it"}`)
+	beat(word)
+	for i := 0; ; i++ {
+		b.mu.Lock()
+		got := b.published
+		b.mu.Unlock()
+		if len(got) == 1 {
+			if string(got[0]) != string(word) {
+				t.Fatalf("the bundle was told %s, not %s", got[0], word)
+			}
+			return
+		}
+		if i > 100 {
+			t.Fatal("the bundle was told nothing")
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+}

node-tools/internal/launch/launch.go

@@ -80,7 +80,9 @@ type Registration struct {
 // Bus is what a launched bundle reaches the mesh through (novox/hq ADR 0193, ADR 0198): the runtime
 // publishes, asks and subscribes on the module's behalf. Subscribe is asked each time the module's
 // code subscribes; the runtime binds the module's consumer once and calls deliver for every event,
-// acknowledging it on the bus when deliver returns nil.
+// acknowledging it on the bus when deliver returns nil. beat is the runtime's word on that consumer between
+// events (a bus.Beat as JSON), which the launch hands the child that subscribed as `mesh/heartbeat`, so a bundle
+// can tell a silent source from a quiet one (stdio.OnHeartbeat).
 //
 // State and Watch reach the module's state (novox/hq ADR 0201): State answers `get`, `put`, `delete`
 // and `keys`; Watch hands deliver the current values and then every change, and returns once the
@@ -88,7 +90,7 @@ type Registration struct {
 type Bus interface {
 	Publish(params json.RawMessage) error
 	Ask(params json.RawMessage) (json.RawMessage, error)
-	Subscribe(deliver func(envelope json.RawMessage) error) error
+	Subscribe(deliver func(envelope json.RawMessage) error, beat func(heartbeat json.RawMessage)) error
 	State(verb string, params json.RawMessage) (json.RawMessage, error)
 	Watch(params json.RawMessage, deliver func(change json.RawMessage) error) (stop func(), err error)
 	// Log answers a bundle's `append`, `read`, `last` and `info` on its module's log (novox/hq ADR 0297).
@@ -261,6 +263,17 @@ func Start(module, entry string, env []string, mesh Bus, logf func(string, ...an
 		_, err := c.ask(module, "mesh/event", map[string]any{"envelope": envelope}, EventTimeout)
 		return err
 	}
+	// The heartbeat of the module's consumer goes to the child that last subscribed, as a notification: the
+	// bundle answers nothing, and a child not running misses it, as it misses the events it did not take.
+	beat := func(heartbeat json.RawMessage) {
+		mu.Lock()
+		c := subscriber
+		mu.Unlock()
+		if c == nil {
+			return
+		}
+		_ = c.write(map[string]any{"jsonrpc": "2.0", "method": "mesh/heartbeat", "params": heartbeat})
+	}
 	var restart func(after time.Duration)
 	var startedAt time.Time
 	// The restart pauses are read once, here: the exit handling runs on its own goroutine and must not
@@ -344,7 +357,7 @@ func Start(module, entry string, env []string, mesh Bus, logf func(string, ...an
 							mu.Lock()
 							subscriber = c
 							mu.Unlock()
-							err = mesh.Subscribe(deliver)
+							err = mesh.Subscribe(deliver, beat)
 						case "mesh/seat.publish", "mesh/seat.prove", "mesh/seat.record", "mesh/seat.kinds", "mesh/seat.pull", "mesh/seat.settle":
 							var answered json.RawMessage
 							if answered, err = mesh.Seat(strings.TrimPrefix(m.Method, "mesh/seat."), m.Params, nil); err == nil {