jackherd 1.12.3 → 1.12.5

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 What changed for people who use jackherd, newest first.
 
+## 1.12.5
+
+- **A lane that stands still is news.** Since 1.12.4 an unchanged heartbeat stays silent, so a working lane whose phase, ticks and subagents do not move would go unnoticed. `jh watch --stream` now reports such a lane once, after three heartbeat intervals without a move (45 minutes at the default 15), as its own line `lane <name> stalled <n> min`, and stays silent until the lane moves again. The orchestrate skill tells the coordinator to read that lane, instead of comparing counts across heartbeats.
+
+## 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.5/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.5/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.5/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.5/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.5/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.5/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.5/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.5/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.5/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.5/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.5/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.5/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.5/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.5/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.5/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.5/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.5/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.5"
 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.5}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

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

@@ -192,16 +192,14 @@ 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
-(`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.
+`=== heartbeat <time> · <lane> <status> · …`, sent only on a change. Each working lane carries its current phase, its ticks
+and the subagents in its worktree (`<lane> working: P12 7/12, 3 subagents`). A working lane whose line stands
+still three heartbeat intervals comes once as `lane <name> stalled <n> min`. `lane added: <name>` and `lane removed: <name>` mark a change.
 An agent is watched from the state it first shows; one that exits fires as `no longer listed`.
 Deploy runs are reported only when the config sets `watch.deploy`.
 
 Something outside GitHub (a ticket, an issue, an error, a status page) the watcher reports only as
-a configured source (`watch.sources`). When the user asks you to follow such an item ("follow X",
-"tell me when X answers"), run `/follow`.
+a configured source (`watch.sources`). When the user asks you to follow such an item, run `/follow`.
 
 A restart is safe: the watcher keeps what it saw between runs. A stop during a report re-delivers that
 report's events on the next arm; vet a repeated event against `gh pr view` or the run before acting
@@ -210,20 +208,20 @@ 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
-  because it has no Monitor tool, unless the provider has none (above). A watcher sent off with a trailing `&` finishes unseen.
+  started again after every wake-up. Tell the user in one sentence that this session watches without a stream,
+  unless the provider has none (above). A watcher sent off with a trailing `&` finishes unseen.
 - **A wake-up is done when every watched lane has a started next action or a named reason to wait**
   (`waiting for merge #<n>`, `waiting for mockup approval`, `plan finished, close the lane?`).
 - **Start the stream again only when it ended:** the monitor expired (its notice after 30 minutes),
   `stopped by SIGTERM` from outside, or `watcher stopped: <reason>`. Start it before answering the
   user. A watcher with named lanes is restarted with every lane still running.
 
-**Herd for the user.** The watcher wakes you; the herd shows the user where every lane stands. The
+**Herd for the user.** The herd shows the user where every lane stands. The
 watcher keeps the herd panes beside your pane and beside each lane of the board and prints a line per
 view it started. On `herd --ensure failed, still watching: <reason>`, fix the cause and run
 `bunx jackherd herd --ensure` from your pane. How the herd picks a lane's phases is in
@@ -248,17 +246,18 @@ 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); 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 |
+| `lane <name> stalled <n> min` | Read its screen: running subagents or moving output are a reason to wait; a stopped lane gets its next step |
 | `approval <name> <id> <tool> · <call>` | A call of the lane waits for the user's approval (**Approvals**, below); the duty line names the question's mark and labels |
 | `coordinator warn` / `coordinator alert` | § 8, for yourself |
 | `lane added: <name>` | Nothing: the lane is watched. Check that it has its row (§ 2 step 5); a name `<lane>-<purpose>` without a worktree is a helper agent of that lane and needs no row. One the lane did not announce goes to the user |
 | `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.5",
   "keywords": [
     "claude-code",
     "coding-agents",

package/src/watch/command.ts

@@ -87,7 +87,7 @@ import {
 import { type FeedbackItem } from './feedback-item'
 import { type FeedbackItemsRead, readCommentItems, readFeedbackItems, readOwnLogin } from './feedback-read'
 import { answered, deployTargetOf, type GithubRead, readGithub, targetText } from './github-read'
-import { currentPhaseCountsOf } from './heartbeat-progress'
+import { currentPhaseCountsOf, type LaneNotes } from './heartbeat-progress'
 import { startHerdPublisher } from './herd-publisher'
 import { agentScreen, listAgents } from './herdr'
 import { endedByKitUpdate } from './kit-update'
@@ -99,7 +99,7 @@ import { boardCheckoutRows, watchedLaneParallel, watchedLaneProgress, watchedPla
 import {
   appointmentEventLine,
   approvalDutyLines,
-  armLine,
+  armNotice,
   blockedDutyLines,
   coordinatorStatusLine,
   feedbackEventLines,
@@ -120,6 +120,7 @@ import {
 import { hasLaneHandover, laneReportPath, readLaneReport, reportMtime } from './lane-report-file'
 import { restNote } from './lane-rest'
 import { branchOf, fetchBaseWhenMoved, fetchPlanHeadsWhenMoved, readMainCheckout } from './lane-sources'
+import { type LaneStalledEvent, laneStalledEvents, STALLED_HEARTBEATS, type StallState } from './lane-stalled'
 import {
   advanceBaseline,
   armBaseline,
@@ -172,7 +173,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,
@@ -306,6 +307,8 @@ type Watching = {
   parallelAutoEnded: string | null
   /** Since when each lane works without a task signal and the phase last reported; persisted like the fingerprints. */
   noTaskSignals: NoSignalState
+  /** The working lanes' positions at the last heartbeat and since when they stand; persisted like the fingerprints. */
+  laneStalls: StallState
   /** The open artifact sends in their grace or already reported as `unlinked artifact`; persisted like the fingerprints. */
   unlinkedArtifacts: UnlinkedState
   /** The approval requests of the last poll; null before the first read, so the stored ids stay. */
@@ -360,6 +363,7 @@ const recordedOf = (watch: Watch, watching: Watching): WatchState => {
     taskParallels: watching.taskParallels,
     parallelAutoEnded: watching.parallelAutoEnded,
     noTaskSignals: watching.noTaskSignals,
+    laneStalls: watching.laneStalls,
     unlinkedArtifacts: watching.unlinkedArtifacts,
     approvals: watching.approvalRequests ? recordApprovals(watching.approvalRequests) : withReads.approvals,
     sources: recordWatchedSources(withReads.sources, watching.sourceRuns, watch.sources, watching.githubReadAt),
@@ -1160,12 +1164,29 @@ const subagentCountsOf = (watch: Watch, now: number): Record<string, number> =>
   }
 }
 
+/**
+ * This heartbeat's `stalled` events: the working lanes whose position (the heartbeat's note) stood still for
+ * `STALLED_HEARTBEATS` heartbeat intervals, each once per stretch; records the state in `watching`.
+ */
+const laneStalledEventsOf = (watch: Watch, watching: Watching, notes: LaneNotes, now: number): LaneStalledEvent[] => {
+  const working = new Set(workingLanes(watching))
+  const readings = Object.fromEntries(
+    watching.lanes.map((lane) => [lane, { working: working.has(lane), position: notes[lane] ?? '' }]),
+  )
+  const limitMinutes = watch.options.heartbeatMinutes * STALLED_HEARTBEATS
+  const { events, state } = laneStalledEvents(watching.laneStalls, readings, now, limitMinutes)
+  watching.laneStalls = state
+  return events
+}
+
 /**
  * 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; a lane whose position stood still for
+ * `STALLED_HEARTBEATS` intervals comes as its own `stalled` event. 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 +1198,17 @@ 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 = [
+    ...laneStalledEventsOf(watch, watching, notes, now),
     ...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 +1261,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)
@@ -1280,6 +1305,7 @@ const initialWatching = (
   taskParallels: start.state.taskParallels,
   parallelAutoEnded: start.state.parallelAutoEnded,
   noTaskSignals: start.state.noTaskSignals,
+  laneStalls: start.state.laneStalls,
   unlinkedArtifacts: start.state.unlinkedArtifacts,
   approvalRequests: null,
   appointments: null,
@@ -1300,10 +1326,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

@@ -11,6 +11,7 @@ import { type FeedbackEvent, firstLine } from './feedback'
 import type { LaneFillEvent } from './lane-fill'
 import type { LaneModelEvent } from './lane-model'
 import type { LaneParallelEvent } from './lane-parallel'
+import { laneStalledLine } from './lane-stalled'
 import { AGENT_STATUS, type LaneSnapshot, NO_AGENT } from './lane-watch'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
 import { SOURCE_FIELD } from './source-fields'
@@ -25,7 +26,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
@@ -150,6 +151,19 @@ export const otherPullRequestsLine = (
   return `${texts.otherPullRequests}: ${[...named, ...(more > 0 ? [`+${more}`] : [])].join(' · ')}`
 }
 
+/** The header line of an event about one lane's agent (fill, model, parallel phases, task signal, standing still); null for any other. */
+const laneEventLine = (event: WatchEvent): string | null => {
+  if (event.kind === WATCH_EVENT.laneFill)
+    return `=== ${event.kind} ${terminalSafe(event.lane)} ${event.level} ${contextLabel(event.share)}`
+  if (event.kind === WATCH_EVENT.laneModel)
+    return `=== ${event.kind} ${terminalSafe(event.lane)} ${terminalSafe(event.model)} · board ${terminalSafe(event.column)}`
+  if (event.kind === WATCH_EVENT.laneParallel)
+    return `=== ${event.kind} ${terminalSafe(event.lane)} ${phasesText(event.phases)}`
+  if (event.kind === WATCH_EVENT.noTaskSignal) return `=== ${terminalSafe(noTaskSignalLine(event))}`
+  if (event.kind === WATCH_EVENT.laneStalled) return `=== ${terminalSafe(laneStalledLine(event))}`
+  return null
+}
+
 /**
  * The header line of one event: `=== merged #<number> (lane)`, `=== checks failed #<number> (lane|branch <name>): <checks> (<k> tests: <names>)`,
  * the checks and tests only when the event carries them,
@@ -167,14 +181,9 @@ export const watchEventLine = (event: WatchEvent, target: string | null): string
   if (event.kind === WATCH_EVENT.ghUnavailable) return `=== ${event.kind}: ${terminalSafe(event.reason)}`
   if (event.kind === WATCH_EVENT.preview)
     return `=== ${event.kind} #${event.number} (${terminalSafe(event.lane)}) ${terminalSafe(event.url)} · ${terminalSafe(event.headCommit.slice(0, SHORT_SHA_LENGTH))}`
-  if (event.kind === WATCH_EVENT.laneFill)
-    return `=== ${event.kind} ${terminalSafe(event.lane)} ${event.level} ${contextLabel(event.share)}`
-  if (event.kind === WATCH_EVENT.laneModel)
-    return `=== ${event.kind} ${terminalSafe(event.lane)} ${terminalSafe(event.model)} · board ${terminalSafe(event.column)}`
-  if (event.kind === WATCH_EVENT.laneParallel)
-    return `=== ${event.kind} ${terminalSafe(event.lane)} ${phasesText(event.phases)}`
+  const laneLine = laneEventLine(event)
+  if (laneLine !== null) return laneLine
   if (event.kind === WATCH_EVENT.taskParallel) return `=== ${terminalSafe(event.line)}`
-  if (event.kind === WATCH_EVENT.noTaskSignal) return `=== ${terminalSafe(noTaskSignalLine(event))}`
   if (event.kind === WATCH_EVENT.unlinkedArtifact) return `=== ${unlinkedArtifactLine(event)}`
   if (event.kind === WATCH_EVENT.approval)
     return `=== ${event.kind} ${terminalSafe(event.lane)} ${event.id} ${terminalSafe(event.tool)} · ${terminalSafe(event.summary)}`
@@ -363,3 +372,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/lane-stalled.ts

@@ -0,0 +1,59 @@
+import { MS_PER_MINUTE } from '../plan-format/clock'
+import { isRecord } from '../shared/is-record'
+
+export const LANE_STALLED_EVENT = 'stalled'
+
+/** How many heartbeat intervals a working lane's position stands still before it is reported. */
+export const STALLED_HEARTBEATS = 3
+
+/** What a heartbeat read of a lane: whether its agent works, and its position as the heartbeat shows it (`P12 7/12, 3 subagents`, `''` without one). */
+export type StallReading = { working: boolean; position: string }
+
+/** Per working lane: the position last read, since when it stands, and whether that stretch was reported. */
+export type StallState = Record<string, { position: string; since: number; reported: boolean }>
+
+export type LaneStalledEvent = { kind: typeof LANE_STALLED_EVENT; lane: string; minutes: number }
+
+type LaneEntry = StallState[string]
+
+const nextEntry = (previous: LaneEntry | undefined, position: string, now: number): LaneEntry =>
+  previous?.position === position ? previous : { position, since: now, reported: false }
+
+const standingMinutes = (entry: LaneEntry, now: number): number => Math.floor((now - entry.since) / MS_PER_MINUTE)
+
+/**
+ * The working lanes whose position (phase, ticks, subagents) stood still for `limitMinutes` or longer, one event per
+ * stretch: a moved position starts the clock again and may be reported again, a lane that stops working or has no
+ * reading drops its clock.
+ */
+export const laneStalledEvents = (
+  previous: StallState,
+  readings: Readonly<Record<string, StallReading>>,
+  now: number,
+  limitMinutes: number,
+): { events: LaneStalledEvent[]; state: StallState } => {
+  const events: LaneStalledEvent[] = []
+  const state: StallState = {}
+  for (const [lane, { working, position }] of Object.entries(readings)) {
+    if (!working) continue
+    const entry = nextEntry(previous[lane], position, now)
+    const minutes = standingMinutes(entry, now)
+    const due = !entry.reported && minutes >= limitMinutes
+    if (due) events.push({ kind: LANE_STALLED_EVENT, lane, minutes })
+    state[lane] = due ? { ...entry, reported: true } : entry
+  }
+  return { events, state }
+}
+
+/** The line the coordinator reads: `lane <name> stalled <n> min`. */
+export const laneStalledLine = ({ lane, minutes }: LaneStalledEvent): string =>
+  `lane ${lane} ${LANE_STALLED_EVENT} ${minutes} min`
+
+const isEntry = (value: unknown): boolean =>
+  isRecord(value) &&
+  typeof value.position === 'string' &&
+  typeof value.since === 'number' &&
+  typeof value.reported === 'boolean'
+
+export const isStallState = (value: unknown): value is StallState =>
+  isRecord(value) && Object.values(value).every(isEntry)

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

@@ -14,6 +14,7 @@ import { emptyFeedbackState, FEEDBACK_EVENT, type FeedbackEvent, type FeedbackSt
 import { isLaneLevels, LANE_FILL_EVENT, type LaneFillEvent, type LaneLevels } from './lane-fill'
 import { isLaneModels, LANE_MODEL_EVENT, type LaneModelEvent, type LaneModels } from './lane-model'
 import { isLaneParallels, LANE_PARALLEL_EVENT, type LaneParallelEvent, type LaneParallels } from './lane-parallel'
+import { isStallState, LANE_STALLED_EVENT, type LaneStalledEvent, type StallState } from './lane-stalled'
 import { type LaneSnapshot, type SeenSeqs, seenSeqsOf } from './lane-watch'
 import { emptyPreviewState, isPreviewState, PREVIEW_EVENT, type PreviewEvent, type PreviewState } from './previews'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
@@ -57,6 +58,7 @@ export const WATCH_EVENT = {
   laneParallel: LANE_PARALLEL_EVENT,
   taskParallel: TASK_PARALLEL_EVENT,
   noTaskSignal: NO_TASK_SIGNAL_EVENT,
+  laneStalled: LANE_STALLED_EVENT,
   unlinkedArtifact: UNLINKED_ARTIFACT_EVENT,
   approval: APPROVAL_EVENT,
   source: SOURCE_EVENT,
@@ -116,6 +118,8 @@ export type WatchState = {
   parallelAutoEnded: string | null
   /** Per watched lane: since when it works without a task signal and the phase last reported as `no task signal`. */
   noTaskSignals: NoSignalState
+  /** Per working lane: its position at the last heartbeat, since when it stands and whether that was reported as `stalled`. */
+  laneStalls: StallState
   /** Per open artifact send no plan or board links: in its grace or already reported as `unlinked artifact`. */
   unlinkedArtifacts: UnlinkedState
   /** The ids of the approval requests on disk when they were last read, each reported once while it is open. */
@@ -128,6 +132,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
 }
@@ -175,6 +183,7 @@ export type WatchEvent =
   | LaneParallelEvent
   | TaskParallelEvent
   | NoTaskSignalEvent
+  | LaneStalledEvent
   | UnlinkedArtifactEvent
   | ApprovalEvent
   | SourceEvent
@@ -213,12 +222,15 @@ export const emptyWatchState = (): WatchState => ({
   taskParallels: {},
   parallelAutoEnded: null,
   noTaskSignals: {},
+  laneStalls: {},
   unlinkedArtifacts: {},
   approvals: [],
   sources: emptySourceState(),
   reportMtimes: {},
   reportQuestions: {},
   statusLines: null,
+  heartbeat: null,
+  armed: null,
   appointments: emptyAppointmentState(),
 })
 
@@ -263,6 +275,7 @@ const isWatchState = (value: Record<string, unknown>): value is WatchState =>
   isTaskParallelFingerprints(value.taskParallels) &&
   (value.parallelAutoEnded === null || typeof value.parallelAutoEnded === 'string') &&
   isNoSignalState(value.noTaskSignals) &&
+  isStallState(value.laneStalls) &&
   isUnlinkedState(value.unlinkedArtifacts) &&
   Array.isArray(value.approvals) &&
   value.approvals.every((id) => typeof id === 'string') &&
@@ -271,6 +284,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)