jackherd 1.12.3 → 1.12.4

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 What changed for people who use jackherd, newest first.
 
+## 1.12.4
+
+- **A quiet stream when nothing changed.** `jh watch --stream` sends a heartbeat only when its state (lanes, their progress, what waits on you, the main checkout) changed since the last one it sent, so a coordinator's chat no longer fills with identical heartbeats over hours. The events a heartbeat brings (parallel tasks, a lane without a task signal, an unlinked Artifact) come as before.
+- **A quiet restart.** A restart prints its `armed: …` line only when the lanes, their states or the board differ from the last start, or when it replaced a running watcher. The orchestrate skill checks the start by the Monitor call that started the stream, and the coordinator restarts an expired stream without a word to the user.
+
 ## 1.12.3
 
 - **One read for every herd of a board.** A running watcher (`jh watch --stream`) reads the board, its plans and the lanes once and publishes the read; each herd of that board, the lane herds included, takes it, woken by the file, instead of reading everything itself every few seconds. It writes the sprint page as well, so no herd builds it. Without a running watcher, after a read older than a minute, or with a herd that runs other code than the watcher, a herd reads for itself as before. Measured with all lanes idle: a herd that follows the watcher takes about 1 % CPU, the watcher about 4-5 %. One herd plus its watcher costs a little more than in 1.12.2 (~5.6 % against ~4.3 %); from two herds on one watcher on, the whole costs less.

package/README.md

@@ -1,9 +1,9 @@
 <p>
-<img alt="jackherd: a black and white Shih Tzu in a turquoise bandana, three lanes running from him to three agent nodes" src="https://unpkg.com/jackherd@1.12.3/assets/branding/jackherd-logo-outline.svg" width="340">
+<img alt="jackherd: a black and white Shih Tzu in a turquoise bandana, three lanes running from him to three agent nodes" src="https://unpkg.com/jackherd@1.12.4/assets/branding/jackherd-logo-outline.svg" width="340">
 <br>
 </p>
 
-[![npm](https://img.shields.io/npm/v/jackherd)](https://www.npmjs.com/package/jackherd) [![license: MIT](https://img.shields.io/npm/l/jackherd)](https://www.npmjs.com/package/jackherd) [![2 dependencies](https://img.shields.io/badge/dependencies-2-brightgreen)](https://www.npmjs.com/package/jackherd?activeTab=dependencies)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.3/assets/icons/space.svg">
+[![npm](https://img.shields.io/npm/v/jackherd)](https://www.npmjs.com/package/jackherd) [![license: MIT](https://img.shields.io/npm/l/jackherd)](https://www.npmjs.com/package/jackherd) [![2 dependencies](https://img.shields.io/badge/dependencies-2-brightgreen)](https://www.npmjs.com/package/jackherd?activeTab=dependencies)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.4/assets/icons/space.svg">
 
 # Jack herds your coding agents.
 
@@ -15,25 +15,25 @@ For developers who'd rather decide than supervise.
 curl -fsSL https://unpkg.com/jackherd/install.sh | sh
 ```
 
-Then `/jh-start` in a repository, and Jack offers your first plan. → [Quickstart](#quickstart)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.3/assets/icons/space.svg">
+Then `/jh-start` in a repository, and Jack offers your first plan. → [Quickstart](#quickstart)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.4/assets/icons/space.svg">
 
 <p>
-<img src="https://unpkg.com/jackherd@1.12.3/docs/workflow-dark.svg" width="720" alt="jackherd in herdr: a lane hits a question, Jack asks you as a choice, you pick, and the lane works on while the herd view counts its progress.">
+<img src="https://unpkg.com/jackherd@1.12.4/docs/workflow-dark.svg" width="720" alt="jackherd in herdr: a lane hits a question, Jack asks you as a choice, you pick, and the lane works on while the herd view counts its progress.">
 <br>
-<sub>Jack and his lanes in <a href="https://herdr.dev/">herdr</a>, a terminal for coding agents (recommended). Without it, one Claude Code session builds with subagents.</sub><br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.3/assets/icons/space.svg">
+<sub>Jack and his lanes in <a href="https://herdr.dev/">herdr</a>, a terminal for coding agents (recommended). Without it, one Claude Code session builds with subagents.</sub><br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.4/assets/icons/space.svg">
 </p>
 
-<p><img src="https://unpkg.com/jackherd@1.12.3/assets/icons/lanes.svg" width="24" height="34" align="middle" alt=""> <b>Parallel where it pays.</b><br>Phases that don't collide run side by side, each lane on its own branch and worktree. Jack keeps the merge order and has the others rebase.</p>
+<p><img src="https://unpkg.com/jackherd@1.12.4/assets/icons/lanes.svg" width="24" height="34" align="middle" alt=""> <b>Parallel where it pays.</b><br>Phases that don't collide run side by side, each lane on its own branch and worktree. Jack keeps the merge order and has the others rebase.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.12.3/assets/icons/bark.svg" width="24" height="34" align="middle" alt=""> <b>Jack barks.</b><br>A blocked lane, a red check, a review comment: Jack wakes, and the herd view shows where every lane stands.</p>
+<p><img src="https://unpkg.com/jackherd@1.12.4/assets/icons/bark.svg" width="24" height="34" align="middle" alt=""> <b>Jack barks.</b><br>A blocked lane, a red check, a review comment: Jack wakes, and the herd view shows where every lane stands.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.12.3/assets/icons/ear.svg" width="24" height="34" align="middle" alt=""> <b>Jack listens.</b><br>Review comments go to the lane that fixes them, with a test. <code>/jh-follow</code> brings anything with a CLI or an API into the herd: tickets, error logs, status pages, deploys, and whatever else you point it at.</p>
+<p><img src="https://unpkg.com/jackherd@1.12.4/assets/icons/ear.svg" width="24" height="34" align="middle" alt=""> <b>Jack listens.</b><br>Review comments go to the lane that fixes them, with a test. <code>/jh-follow</code> brings anything with a CLI or an API into the herd: tickets, error logs, status pages, deploys, and whatever else you point it at.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.12.3/assets/icons/bowl.svg" width="24" height="34" align="middle" alt=""> <b>Picks up where you left off.</b><br>Plan and board hold the state, not the chat.</p>
+<p><img src="https://unpkg.com/jackherd@1.12.4/assets/icons/bowl.svg" width="24" height="34" align="middle" alt=""> <b>Picks up where you left off.</b><br>Plan and board hold the state, not the chat.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.12.3/assets/icons/plan.svg" width="24" height="34" align="middle" alt=""> <b>Lives in your repository.</b><br>Plans, board and every decision are Markdown, reviewed like code. <code>jh init</code> gives your team the same setup.</p>
+<p><img src="https://unpkg.com/jackherd@1.12.4/assets/icons/plan.svg" width="24" height="34" align="middle" alt=""> <b>Lives in your repository.</b><br>Plans, board and every decision are Markdown, reviewed like code. <code>jh init</code> gives your team the same setup.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.12.3/assets/icons/decide.svg" width="24" height="34" align="middle" alt=""> <b>You make the calls.</b><br>Nothing is committed, pushed or merged without your approval. Jack merges on green checks only where you said so: one pull request, or a plan's for up to 24 hours.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.3/assets/icons/space.svg"></p>
+<p><img src="https://unpkg.com/jackherd@1.12.4/assets/icons/decide.svg" width="24" height="34" align="middle" alt=""> <b>You make the calls.</b><br>Nothing is committed, pushed or merged without your approval. Jack merges on green checks only where you said so: one pull request, or a plan's for up to 24 hours.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.4/assets/icons/space.svg"></p>
 
 ## Quickstart
 
@@ -69,22 +69,22 @@ Then `/jh-start` in a repository, and Jack offers your first plan. → [Quicksta
    /jh-orchestrate docs/plans/board-<name>/board.md
    ```
 
-By hand (Bun 1.3+): `bun add -g jackherd` or `npm install -g jackherd`, then `jh init --global` for yourself, or `jh init` in a repository to give your team the same skills and guard hooks. → [INSTALL.md](https://unpkg.com/jackherd/INSTALL.md)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.3/assets/icons/space.svg">
+By hand (Bun 1.3+): `bun add -g jackherd` or `npm install -g jackherd`, then `jh init --global` for yourself, or `jh init` in a repository to give your team the same skills and guard hooks. → [INSTALL.md](https://unpkg.com/jackherd/INSTALL.md)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.4/assets/icons/space.svg">
 
 ## Follow anything outside GitHub
 
 Whatever you check by hand, Jack can watch: tickets, error logs, status pages, deploys. One `/jh-follow`, one yes, and every change comes to you like this:
 
-<img src="https://unpkg.com/jackherd@1.12.3/docs/follow-dark.svg" width="720" alt="A source (ticket, error log or status page) has a new or changed entry; jh watch reports it to Jack; Jack puts a row into Your turn, prefixed with the source's label; its [ask] button makes Jack ask you, and then a lane works it.">
+<img src="https://unpkg.com/jackherd@1.12.4/docs/follow-dark.svg" width="720" alt="A source (ticket, error log or status page) has a new or changed entry; jh watch reports it to Jack; Jack puts a row into Your turn, prefixed with the source's label; its [ask] button makes Jack ask you, and then a lane works it.">
 
-The herd sums up your sources in one `Sources` line: per source its new entries, or when it last ran, red while it fails; opened, a click on an entry opens it. A ticket shows on the lane that works it, and a row in Your turn that came from a source starts with that source's label.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.3/assets/icons/space.svg">
+The herd sums up your sources in one `Sources` line: per source its new entries, or when it last ran, red while it fails; opened, a click on an entry opens it. A ticket shows on the lane that works it, and a row in Your turn that came from a source starts with that source's label.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.4/assets/icons/space.svg">
 
 ## In detail
 
 <details>
 <summary><b>What Jack does on his own, and what waits for you</b></summary>
 
-<img src="https://unpkg.com/jackherd@1.12.3/docs/lanes-dark.svg" alt="Jack prompts two lanes and asks you for decisions and approvals; the lanes send questions back as text; jh watch reads lane state, pull requests and checks and wakes Jack.">
+<img src="https://unpkg.com/jackherd@1.12.4/docs/lanes-dark.svg" alt="Jack prompts two lanes and asks you for decisions and approvals; the lanes send questions back as text; jh watch reads lane state, pull requests and checks and wakes Jack.">
 
 | On his own | After your approval | Never |
 | --- | --- | --- |
@@ -117,7 +117,7 @@ The guards catch mistakes, not intent; for that, use branch protection. The hook
 
 A **plan** is Markdown with phases, checkbox tasks, a model and a review gate per phase. A **board** lists the lanes of one or more plans: which phases each lane builds, on which model, after what. A **lane** is one agent session in its own git worktree (a second checkout of your repository), and **Jack** is the session in the main checkout that runs `/jh-orchestrate` on a board.
 
-<img src="https://unpkg.com/jackherd@1.12.3/docs/skills-dark.svg" alt="/jh-grill hands decisions to /jh-plan; /jh-plan feeds /jh-orchestrate or a single /jh-implement; /jh-implement ends in /jh-pre-commit, which runs the reviewers; /jh-diagnose hands a red command to /jh-implement.">
+<img src="https://unpkg.com/jackherd@1.12.4/docs/skills-dark.svg" alt="/jh-grill hands decisions to /jh-plan; /jh-plan feeds /jh-orchestrate or a single /jh-implement; /jh-implement ends in /jh-pre-commit, which runs the reviewers; /jh-diagnose hands a red command to /jh-implement.">
 
 | Skill | Does |
 | --- | --- |

package/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.12.3"
+version = "1.12.4"
 min_herdr_version = "0.8.2"
 description = "Show the herd, the state of a board's lanes, in a herdr pane"
 platforms = ["linux", "macos"]

package/install.sh

@@ -9,7 +9,7 @@ set -eu
 
 # The default is the version this file ships with. The release bump changes it together with
 # package.json; install.test.ts fails while the two differ. Overridable, but only by a plain release.
-JACKHERD_VERSION="${JACKHERD_VERSION:-1.12.3}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.12.4}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

package/kit/workflow/skills/orchestrate/SKILL.md

@@ -192,8 +192,8 @@ watcher finds you by the default name of § 0, or by `--coordinator <name>`. In
 arrives as one message, and the watcher keeps running.
 
 The heartbeat (default 15 minutes, due after that long without a report) is one line,
-`=== heartbeat <time> · <lane> <status> · …`. Each working lane carries its current phase and its ticks
-(`<lane> working: P12 7/12`) at every heartbeat, and the subagents running in its worktree
+`=== heartbeat <time> · <lane> <status> · …`, sent only on a change. Each working lane carries its current phase and its ticks
+(`<lane> working: P12 7/12`) and the subagents running in its worktree
 (`P12 7/12, 3 subagents`). A lane whose count stays put with no subagent running is
 one to read yourself. `lane added: <name>` and `lane removed: <name>` mark a change of the found lanes.
 An agent is watched from the state it first shows; one that exits fires as `no longer listed`.
@@ -210,9 +210,9 @@ twice.
 - **The stream runs under the Monitor tool.** A Bash call never ends with it, not even in the
   background, so its reports go unseen; the kit's `watch-guard` hook refuses such a call where the
   project installed it, and this rule holds where it did not.
-- **Check the start.** The first line, `armed: …`, arrives as a Monitor event. When it arrives as
-  the output of a Bash call instead, the start went wrong: stop that task (`TaskStop`) and start the
-  stream under the Monitor tool.
+- **Check the start.** A start under the Monitor tool is right; its first line, `armed: …`, comes
+  only when lanes, states or board changed. A start as a Bash call went wrong: stop that task
+  (`TaskStop`) and start it under the Monitor tool.
 - **Only when the session has no Monitor tool**, even after `ToolSearch`, the watcher runs without
   `--stream` as its own Bash call with `run_in_background: true`. It returns after one report and is
   started again after every wake-up. Tell the user in one sentence that this session watches without a stream
@@ -248,7 +248,7 @@ On wake-up:
 | `checks passed #<n>` | One line to the user: ready to merge, with the board's merge order |
 | `deploy …` | Result and target as the run states them, to the user; a target `unknown (…)` is reported as unknown, never guessed. A failed run goes to the user as an `AskUserQuestion`: read the logs now or later |
 | `due <when> · <action>` | An open appointment fell due (**An agreed time**, below); the action is cut to 160 characters, the board row holds it whole. Carry it out as agreed, under the approvals it needs (§ 5), then write the outcome into its status cell in the same turn |
-| `heartbeat` | One line of status to the user, also when nothing changed; a resting lane carries `waits on: <question>, <n> open questions` from its report, and `for you (<n>): …` names what still waits on the user (**Anything that waits on the user's answer**, below): the `for you` part of that line is the count only (`3 wait for you, see the herd`, in the language of the replies); the herd shows the items, and no reply of yours ends with a list of the rows of the board section |
+| `heartbeat` | One line of status to the user; a resting lane carries `waits on: <question>, <n> open questions` from its report, and `for you (<n>): …` names what still waits on the user (**Anything that waits on the user's answer**, below): the `for you` part of that line is the count only (`3 wait for you, see the herd`, in the language of the replies); the herd shows the items, and no reply of yours ends with a list of the rows of the board section |
 | `gh unavailable` | Tell the user once; herdr watching continues |
 | `lane <name> warn` | One line to the user: the lane's fill and that it hands over at a phase boundary if it rises further; no step in the lane |
 | `lane <name> alert` | § 8: send the lane once the request for its hand-over at the end of its current phase |
@@ -258,7 +258,7 @@ On wake-up:
 | `lane removed: <name>` | Nothing after you closed it (§ 7). Otherwise its agent exited or its worktree is gone: read why, then tell the user |
 | `kit updated <old> → <new>` | The kit was updated under the running watcher, which ended. After the `jh update` call has finished (with `(source changed)` there is none: the kit's source moved under a watcher run from it), read the change of this skill the next line names (`orchestrate skill: § … changed · diff <path>`; the diff shows the kit's placeholders, not your values), and the change of each reference a line names (`orchestrate reference <name> changed · diff <path>`, or `new · read <path>`), so the new text is the one you follow; read this skill file again (`Read` on the file you were given, no session restart) only when the line says `diff unavailable`; `orchestrate skill unchanged` needs no reading. Then start the stream again |
 | an event line ending in `· read <path>` | A rare event (`feedback`, `preview`, `source`, `parallel`, an update, …): read the file it names, mostly [`references/events.md`](references/events.md), and handle the event as it says there; read its `parallel tasks` section also before you switch `watch.parallelTasks.auto` on |
-| monitor expired | Start the stream again |
+| monitor expired | Start the stream again, without a word to the user |
 | `superseded by <pid>` / `stopped by SIGTERM` | Nothing for `superseded`: the newer watcher runs. After `stopped by SIGTERM` from outside, start it again |
 | `watcher stopped: <reason>` | Tell the user, fix the cause (an unreadable state file, say), then start it again |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.12.3",
+  "version": "1.12.4",
   "keywords": [
     "claude-code",
     "coding-agents",

package/src/watch/command.ts

@@ -99,7 +99,7 @@ import { boardCheckoutRows, watchedLaneParallel, watchedLaneProgress, watchedPla
 import {
   appointmentEventLine,
   approvalDutyLines,
-  armLine,
+  armNotice,
   blockedDutyLines,
   coordinatorStatusLine,
   feedbackEventLines,
@@ -172,7 +172,7 @@ import { sourceDryRun } from './source-dry-run-command'
 import { runSource, SOURCE_LIMITS } from './source-run'
 import { recordWatchedSources } from './source-tickets'
 import { isSourceDue, type SourceRun, type SourceSettings, type SourceState, sourceEvents } from './sources'
-import { streamHeartbeatLine } from './stream-output'
+import { heartbeatStateOf, isHeartbeatNews, streamHeartbeatLine } from './stream-output'
 import {
   formatTaskParallelLine,
   TASK_PARALLEL_EVENT,
@@ -1162,10 +1162,11 @@ const subagentCountsOf = (watch: Watch, now: number): Record<string, number> =>
 
 /**
  * The heartbeat of a stream: one line, a working lane with its phase count at every heartbeat and the subagents running
- * in its worktree. The plans are read only when a lane works; a board that cannot be read leaves the lines without a
- * count, and the next report names the failure.
+ * in its worktree, printed only when its state changed since the last one sent. The plans are read only when a lane
+ * works; a board that cannot be read leaves the lines without a count, and the next report names the failure. Returns
+ * the state of the heartbeat it printed, null when it printed none.
  */
-const printStreamHeartbeat = async (watch: Watch, watching: Watching, now: number): Promise<void> => {
+const printStreamHeartbeat = async (watch: Watch, watching: Watching, now: number): Promise<string | null> => {
   const working = workingLanes(watching)
   const progress = await workingProgressOf(watch, watching)
   const counts = currentPhaseCountsOf(progress)
@@ -1177,13 +1178,16 @@ const printStreamHeartbeat = async (watch: Watch, watching: Watching, now: numbe
     }),
   )
   const standing = [waitingLineOf(watch), mainCheckoutLineOf(watch)].filter((line) => line !== null)
-  console.log(streamHeartbeatLine(clock(now), watching.lanes, watching.current, notes, rests, standing))
+  const line = streamHeartbeatLine(clock(now), watching.lanes, watching.current, notes, rests, standing)
+  const sent = isHeartbeatNews(watching.state.heartbeat, line) ? heartbeatStateOf(line) : null
+  if (sent !== null) console.log(line)
   const events = [
     ...taskParallelEventsOf(watch, watching, now),
     ...noTaskSignalEventsOf(watch, watching, progress, now),
     ...unlinkedArtifactEventsOf(watch, watching),
   ]
   for (const event of events) console.log(`${watchEventLine(event, null)}${hintFor(watch, eventReference(event))}`)
+  return sent
 }
 
 /**
@@ -1236,8 +1240,8 @@ const pollOnce = async (watch: Watch, watching: Watching): Promise<boolean> => {
     })
   } else {
     if (heartbeat) {
-      await printStreamHeartbeat(watch, watching, now)
-      next = recordedOf(watch, watching)
+      const sent = await printStreamHeartbeat(watch, watching, now)
+      next = { ...recordedOf(watch, watching), ...(sent !== null && { heartbeat: sent }) }
     }
     if (due) writePrivateFile(watch.files.state, JSON.stringify(next))
     watching.baseline = advanceBaseline(watching.baseline, watching.current)
@@ -1300,10 +1304,11 @@ const watchLanes = async (watch: Watch) => {
   const sprintLanes = watch.options.lanes ? [] : sprintLaneNames(watch, [])
   const lanes = lanesFor(watch, agents, sprintLanes)
   const armed = toSnapshot(agents, lanes)
-  console.log(armLine(lanes, armed, takeOver, relative(watch.root, watch.sprintFile)))
+  const arm = armNotice(state.armed, lanes, armed, takeOver, relative(watch.root, watch.sprintFile))
+  if (arm.line !== null) console.log(arm.line)
   if (watch.boardNotice) console.log(watch.boardNotice)
 
-  const watching = initialWatching(watch, { lanes, sprintLanes, state, armed, agents })
+  const watching = initialWatching(watch, { lanes, sprintLanes, state: { ...state, armed: arm.state }, armed, agents })
   keepViews(watch, watching, { kind: ENSURE_TRIGGER.start })
   process.on('SIGTERM', () => {
     saveState(watch, watching)

package/src/watch/lane-report.ts

@@ -25,7 +25,7 @@ import {
   WATCH_EVENT,
   type WatchEvent,
 } from './watch-events'
-import type { TakeOver } from './watcher-lock'
+import { NO_TAKE_OVER, type TakeOver } from './watcher-lock'
 
 export type LaneReport = {
   lane: string
@@ -363,3 +363,19 @@ export const armLine = (lanes: readonly string[], armed: LaneSnapshot, takeOver:
     'no lanes'
   return `armed: ${states}${takeOverNote(takeOver)} board ${terminalSafe(board)}`
 }
+
+/**
+ * The `armed:` line a start prints, null when it would repeat the last start's (`previous`), and the line to remember:
+ * the one without a take-over note, so a start that replaced a watcher speaks and the one after it compares as usual.
+ */
+export const armNotice = (
+  previous: string | null,
+  lanes: readonly string[],
+  armed: LaneSnapshot,
+  takeOver: TakeOver,
+  board: string,
+): { line: string | null; state: string } => {
+  const state = armLine(lanes, armed, NO_TAKE_OVER, board)
+  const line = armLine(lanes, armed, takeOver, board)
+  return { line: line === previous ? null : line, state }
+}

package/src/watch/stream-output.ts

@@ -35,3 +35,9 @@ export const streamHeartbeatLine = (
     ...standing.map((line) => terminalSafe(line).replaceAll(SEPARATOR, ' / ')),
   ].join(SEPARATOR)
 }
+
+/** A heartbeat line without its head and time: what two heartbeats are compared by. */
+export const heartbeatStateOf = (line: string): string => line.slice(line.indexOf(SEPARATOR) + SEPARATOR.length)
+
+/** Whether a heartbeat brings news against the state of the last one sent (`heartbeatStateOf`); the first one always does. */
+export const isHeartbeatNews = (previous: string | null, line: string): boolean => previous !== heartbeatStateOf(line)

package/src/watch/watch-events.ts

@@ -128,6 +128,10 @@ export type WatchState = {
   reportQuestions: Record<string, string>
   /** The lane lines of the status block last printed; null before the first report. */
   statusLines: string[] | null
+  /** The state of the last heartbeat a stream sent (`heartbeatStateOf`); null before the first one. */
+  heartbeat: string | null
+  /** The `armed:` line of the last start; a start that would print the same line stays silent. Null before the first. */
+  armed: string | null
   /** The board's appointments reported as due and its unreadable appointment rows reported, each once (`appointments.ts`). */
   appointments: AppointmentState
 }
@@ -219,6 +223,8 @@ export const emptyWatchState = (): WatchState => ({
   reportMtimes: {},
   reportQuestions: {},
   statusLines: null,
+  heartbeat: null,
+  armed: null,
   appointments: emptyAppointmentState(),
 })
 
@@ -271,6 +277,8 @@ const isWatchState = (value: Record<string, unknown>): value is WatchState =>
   everyValue(value.reportQuestions, (entry) => typeof entry === 'string') &&
   (value.statusLines === null ||
     (Array.isArray(value.statusLines) && value.statusLines.every((line) => typeof line === 'string'))) &&
+  (value.heartbeat === null || typeof value.heartbeat === 'string') &&
+  (value.armed === null || typeof value.armed === 'string') &&
   isAppointmentState(value.appointments)
 
 /**

package/src/watch/watcher-lock.ts

@@ -18,6 +18,9 @@ export type CommandLineOf = (pid: number) => string | null
 /** What taking the lock did to a watcher that held it: stopped it, or found it still running after the wait. */
 export type TakeOver = { replaced: number | null; stillRunning: number | null }
 
+/** A start that found no watcher to take over from. */
+export const NO_TAKE_OVER: TakeOver = { replaced: null, stillRunning: null }
+
 /** The CLI's entry by source path or bin link (`jh`, and `jackherd` for `bunx jackherd`); `agent-kit` until 2.0.0, so a watcher of the old CLI is replaced. */
 const CLI_ENTRIES = ['cli.ts', CLI_NAME, PACKAGE_NAME, 'agent-kit']
 const WATCH_COMMAND = 'watch'
@@ -165,11 +168,11 @@ export const isWatcherRunning = (lockFile: string, lookUp: CommandLineOf = reade
 export const takeOverLock = async (lockFile: string): Promise<TakeOver> => {
   const previous = supersedeTarget(readPrivateText(lockFile), process.pid, commandLineOf)
   writePrivateFile(lockFile, String(process.pid))
-  if (previous === null || !isAlive(previous)) return { replaced: null, stillRunning: null }
+  if (previous === null || !isAlive(previous)) return NO_TAKE_OVER
   try {
     process.kill(previous, 'SIGTERM')
   } catch {
-    return { replaced: null, stillRunning: null }
+    return NO_TAKE_OVER
   }
   const deadline = Date.now() + STOP_WAIT_MS
   while (isAlive(previous) && Date.now() < deadline) await Bun.sleep(STOP_POLL_MS)