jackherd 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 What changed for people who use jackherd, newest first.
 
+## 1.2.0
+
+- **A running session hears about a new release.** The watcher asks npm once a day, on the timestamp of the `SessionStart` hook, and prints `=== update available <old> → <new>` once per version when there is a newer one; with nothing new it prints nothing. The `orchestrate` skill asks you (update now / not now) and runs `jh update` only after a yes.
+- **The hook also runs after `/clear`, `/resume` and compaction.** Its matcher is now `startup|resume|clear|compact`; `jh sync --global` moves a hook that matches `startup` only, exactly as an older install wrote it, and touches no other entry in `~/.claude/settings.json`.
+- **A silent npm is asked again after an hour.** Before, one unanswered question paused the check for a day. Nothing is printed on a failure.
+- **No `questions:` line for an empty section.** A `## Questions` section that only says "Keine." or "None." counts as no question, and the report keeps its full head.
+- **README.** Three badges at the top: npm version, license, dependencies.
+
 ## 1.1.0
 
 - **Questions in a lane's report reach you.** The watcher cut a new report to its first 15 lines, and the questions, which stand at the end, fell away. It now shows a `## Questions` section (also `## Fragen`, any level, any text after the word) whole, wherever it stands, under a `questions: <n>` line, within a budget of 20 lines and 1500 characters (over it, each question keeps the start of its first line and a closing line says how many were left out). A report with such a section gets a shorter head (8 lines, 900 characters: the diff stat and the checks), so the message stays about as long as before. The `orchestrate` skill makes every question a duty in the same wake-up: answered in the lane, or put to you, and a question the lane answered is reported to you in one line.

package/README.md

@@ -6,6 +6,8 @@
 <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)
+
 **Plan. Delegate. Ship.** Your agents do the work. Jack keeps them together.
 
 Large tasks outgrow one chat, the context fills up, parallel sessions edit the same files, and
@@ -260,10 +262,12 @@ A running `plans` view restarts itself with the new code, and a running `watch`
 `jh sync --global --if-changed` is meant to run at the start of every session. It syncs `~/.claude` only when the installed package is not the version the global lock was written by, so after `bun add -g jackherd@<version>` the next session brings the skills up to date. Once a day it asks npm for the newest release and, when there is one, prints a single line of this form:
 
 ```text
-jh 1.1.0 is on npm, 1.0.0 is installed. Ask the user with AskUserQuestion whether to run `jh update` now (update now / not now), and run it only after a yes.
+jh 1.2.0 is on npm, 1.1.0 is installed. Ask the user with AskUserQuestion whether to run `jh update` now (update now / not now), and run it only after a yes.
 ```
 
-It never installs anything itself: the session asks you, and `jh update` runs only after your yes. With nothing to do it prints nothing and exits 0; without a global install it syncs nothing. The time of the last npm question is kept in `~/.jackherd/update-check.json`.
+It never installs anything itself: the session asks you, and `jh update` runs only after your yes. With nothing to do it prints nothing and exits 0; without a global install it syncs nothing. The time of the last npm question is kept in `~/.jackherd/update-check.json`. If npm does not answer (3 seconds), the question is asked again after an hour, not after a day, and nothing is printed meanwhile.
+
+The hook runs when a session starts, resumes, is cleared or is compacted (`startup|resume|clear|compact`), so a hand-over by `/clear` sees the line too; the daily timestamp makes the extra runs free. A session that runs for days is covered by [the watcher](#user-content-the-watcher), which looks at npm once a day on the same timestamp. `jh sync --global` moves a hook that still reads `startup` only, exactly as an older install wrote it, to the new matcher; a hook of your own, or one with another command or extra keys, stays as it is.
 
 `init --global` asks once whether to add this hook to `~/.claude/settings.json`, appends it as a group of its own beside your other hooks, and does nothing when it is there already. A file it cannot read or merge into, or a symlink, stays as it is; the entry to add by hand:
 
@@ -271,7 +275,7 @@ It never installs anything itself: the session asks you, and `jh update` runs on
 {
   "hooks": {
     "SessionStart": [
-      { "matcher": "startup", "hooks": [{ "type": "command", "command": "jh sync --global --if-changed" }] }
+      { "matcher": "startup|resume|clear|compact", "hooks": [{ "type": "command", "command": "jh sync --global --if-changed" }] }
     ]
   }
 }
@@ -528,6 +532,7 @@ Why it exists: the coordinator is a chat, and it only acts when something arrive
 - a deploy preview for a lane's new head commit, with its link (`watch.previews`)
 - a new or changed entry of an external service, such as a ticket comment, read by a command the config names (`watch.sources`)
 - `gh` became unreachable
+- npm has a newer jackherd than the one running: `=== update available <old> → <new>`, one line, once per version. The watcher asks npm once a day on the timestamp the `SessionStart` hook uses (`~/.jackherd/update-check.json`), so the two never ask twice a day or report twice; with nothing newer it prints nothing. The coordinator asks you and runs `jh update` only after your yes
 - a lane's context fill rose to `warn` or `alert` (`=== lane <name> alert 47 %`, with a duty line at `alert`: request the lane's hand-over at its next phase boundary), against the lanes' thresholds in `plans.context`
 - the coordinator's own context fill rose to `warn` or `alert`, so it hands itself over in time
 - `lane added` / `lane removed` when a worktree with an agent or a board row appears or goes

package/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.1.0"
+version = "1.2.0"
 min_herdr_version = "0.8.2"
 description = "Show the plans 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.1.0}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.2.0}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

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

@@ -277,7 +277,7 @@ not fire), when a lane's PR merges, its checks turn red or green, the same for o
 PRs on a branch no lane has (`=== checks failed #<n> (branch <name>)`, found by `--author @me`: a
 documentation or `chore` PR you opened yourself; act on it like on a lane's, a merge makes every
 lane rebase), a deploy run ends (after such a merge `(push, #<n>)`), the
-heartbeat falls due, `gh` becomes unreachable, the installed kit changes version (`=== kit updated <old> → <new>`, then the watcher ends), or your own fill rises to `warn` or `alert`
+heartbeat falls due, `gh` becomes unreachable, the installed kit changes version (`=== kit updated <old> → <new>`, then the watcher ends), npm names a newer release (`=== update available <old> → <new>`, once a day at most and once per version), or your own fill rises to `warn` or `alert`
 (`=== coordinator <level> <share>`). Every report prints the event blocks, then `status:` with one
 line per lane: its status, its branch, its PR with checks, and its open phase with the starts-after
 entry (or that the plan is finished, or that there is no plan). One more line holds your own fill,
@@ -370,6 +370,7 @@ On wake-up:
 | `lane added: <name>` | Nothing: the lane is watched. Check that it has its row (§ 2 step 5) |
 | `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, 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), 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 |
+| `update available <old> → <new>` | A newer jackherd is on npm. Ask the user with `AskUserQuestion` (update now / not now) and run `jh update` only after a yes; the watcher then ends with `kit updated`, handle it as that row and start the stream again. After a no, nothing: the watcher does not mention this version again |
 | monitor expired | Start the stream again |
 | `superseded by <pid>` / `stopped by SIGTERM` | Nothing for `superseded`: it is no event, 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.1.0",
+  "version": "1.2.0",
   "keywords": [
     "claude-code",
     "coding-agents",

package/src/sync/if-changed.ts

@@ -15,6 +15,9 @@ export type UpdateCheck = { now: () => number; latestVersion: () => Promise<stri
 
 export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
 
+/** How soon npm is asked again after it gave no answer: an hour, so an offline morning does not cost the day. */
+export const UPDATE_RETRY_INTERVAL_MS = 60 * 60 * 1000
+
 const REGISTRY_LATEST = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`
 const REGISTRY_TIMEOUT_MS = 3_000
 const UPDATE_STATE_FILE = 'update-check.json'
@@ -78,22 +81,29 @@ const stampUpdateCheck = async (home: string, now: number): Promise<boolean> =>
   }
 }
 
+/** The stamp that makes the check due again after `UPDATE_RETRY_INTERVAL_MS`, as if npm had been asked that long ago. */
+const retryStampFor = (now: number): number => now - UPDATE_CHECK_INTERVAL_MS + UPDATE_RETRY_INTERVAL_MS
+
 /**
- * The update line, when the daily check is due and npm has a newer release. The check is stamped before npm is
- * asked, so a registry that does not answer is asked again tomorrow, not in every session.
+ * The newest version npm names, when the daily check is due; null when it is not due or npm gave no answer. The
+ * check is stamped before npm is asked, so sessions starting together ask once. An unanswered question is
+ * restamped as if it had been asked `UPDATE_RETRY_INTERVAL_MS` before it is due again: the state file keeps its
+ * one field, and the hook and the watcher share it.
  */
-export const dailyUpdateNotice = async (
-  home: string,
-  installed: string,
-  check: UpdateCheck,
-): Promise<string | null> => {
+export const latestVersionIfDue = async (home: string, check: UpdateCheck): Promise<string | null> => {
   const path = join(home, TOOL_DIRECTORY, UPDATE_STATE_FILE)
   const now = check.now()
   if (!updateCheckDue(await readUpdateState(path), now)) return null
   if (!(await stampUpdateCheck(home, now))) return null
-  return updateNotice(await check.latestVersion(), installed)
+  const latest = await check.latestVersion()
+  if (latest === null) await stampUpdateCheck(home, retryStampFor(now))
+  return latest
 }
 
+/** The update line, when the daily check is due and npm has a newer release. */
+export const dailyUpdateNotice = async (home: string, installed: string, check: UpdateCheck): Promise<string | null> =>
+  updateNotice(await latestVersionIfDue(home, check), installed)
+
 /** Asks the npm registry for the `latest` tag; null on any failure, after a few seconds at most. */
 const registryLatestVersion = async (): Promise<string | null> => {
   try {

package/src/sync/settings-migration.ts

@@ -7,6 +7,8 @@ import {
   isObject,
   readSettingsOffer,
   SESSION_HOOK_COMMAND,
+  SESSION_HOOK_MATCHER,
+  SESSION_START,
   type SettingsObject,
   type SettingsOffer,
 } from './settings-offer'
@@ -41,7 +43,7 @@ const migrateGroup = (group: unknown): unknown =>
 
 const sessionStartOf = (settings: SettingsObject): unknown[] | null => {
   const hooks = settings.hooks
-  return isObject(hooks) && Array.isArray(hooks.SessionStart) ? hooks.SessionStart : null
+  return isObject(hooks) && Array.isArray(hooks[SESSION_START]) ? hooks[SESSION_START] : null
 }
 
 /** Our `SessionStart` hook as the old CLI ran it becomes the `jh` command; every other event, group and handler stays. */
@@ -53,7 +55,42 @@ export const LEGACY_HOOK_MIGRATION: SettingsOffer = {
     if (JSON.stringify(migrated) === JSON.stringify(groups)) return { kind: 'present' }
     return {
       kind: 'add',
-      next: { ...settings, hooks: { ...(settings.hooks as SettingsObject), SessionStart: migrated } },
+      next: { ...settings, hooks: { ...(settings.hooks as SettingsObject), [SESSION_START]: migrated } },
+    }
+  },
+}
+
+/** The matcher older installs wrote: the hook ran at `startup` only, so a `/clear` handover never saw its line. */
+export const LEGACY_SESSION_HOOK_MATCHER = 'startup'
+
+const sameKeys = (value: SettingsObject, keys: readonly string[]): boolean =>
+  Object.keys(value).sort().join() === [...keys].sort().join()
+
+/** Exactly the group an older install wrote: the `startup` matcher and our one handler, nothing else on either. */
+const isLegacyMatcherGroup = (group: unknown): boolean => {
+  if (!isObject(group) || !sameKeys(group, ['matcher', 'hooks'])) return false
+  if (group.matcher !== LEGACY_SESSION_HOOK_MATCHER || !Array.isArray(group.hooks) || group.hooks.length !== 1)
+    return false
+  const [handler] = group.hooks
+  return (
+    isObject(handler) &&
+    sameKeys(handler, ['type', 'command']) &&
+    handler.type === 'command' &&
+    handler.command === SESSION_HOOK_COMMAND
+  )
+}
+
+/** Our `SessionStart` hook written for `startup` only also runs after `resume`, `clear` and `compact`; any other group stays. */
+export const SESSION_MATCHER_MIGRATION: SettingsOffer = {
+  find: (settings) => {
+    const groups = sessionStartOf(settings)
+    if (!groups?.some(isLegacyMatcherGroup)) return { kind: 'present' }
+    const widened = groups.map((group) =>
+      isLegacyMatcherGroup(group) ? { ...(group as SettingsObject), matcher: SESSION_HOOK_MATCHER } : group,
+    )
+    return {
+      kind: 'add',
+      next: { ...settings, hooks: { ...(settings.hooks as SettingsObject), [SESSION_START]: widened } },
     }
   },
 }
@@ -90,5 +127,10 @@ export const migrateGlobalSettings = async (home: string, cliOnPath: boolean): P
           `Changed the SessionStart hook in ${SHOWN_SETTINGS} to \`${SESSION_HOOK_COMMAND}\`.`,
         )
       : HOOK_WAITS
-  return [statusLine, hook].filter((line): line is string => line !== null)
+  const matcher = await migrate(
+    path,
+    SESSION_MATCHER_MIGRATION,
+    `Widened the SessionStart hook in ${SHOWN_SETTINGS} to startup, resume, clear and compact.`,
+  )
+  return [statusLine, hook, matcher].filter((line): line is string => line !== null)
 }

package/src/sync/settings-offer.ts

@@ -29,9 +29,15 @@ export type SettingsWrite = { kind: 'written' } | { kind: 'notWritten'; reason:
 /** What the `SessionStart` hook runs: a global sync only when the installed kit changed. */
 export const SESSION_HOOK_COMMAND = `${CLI_NAME} sync --global --if-changed`
 
-const SESSION_START = 'SessionStart'
+export const SESSION_START = 'SessionStart'
 
-const SESSION_HOOK_GROUP = { matcher: 'startup', hooks: [{ type: 'command', command: SESSION_HOOK_COMMAND }] }
+/** Every way a session starts; the daily timestamp makes the extra runs free. */
+export const SESSION_HOOK_MATCHER = 'startup|resume|clear|compact'
+
+const SESSION_HOOK_GROUP = {
+  matcher: SESSION_HOOK_MATCHER,
+  hooks: [{ type: 'command', command: SESSION_HOOK_COMMAND }],
+}
 
 /** Claude Code creates `settings.json` world-readable; an existing file keeps its own mode. */
 const NEW_FILE_MODE = 0o644

package/src/watch/command.ts

@@ -6,7 +6,8 @@
  * with `watch.sources`), a gh outage, a lane's or the coordinator's own context fill rising to warn or alert, or the
  * heartbeat. A blocked lane adds one duty line, a merge one per lane, a lane at alert one, and every report ends with one status line
  * per lane and one for the coordinator, in the words of `responseLanguage`. When the installed kit changes version
- * it prints `=== kit updated <old> → <new>` and ends. The coordinator is the agent in the
+ * it prints `=== kit updated <old> → <new>` and ends; once a day it asks npm and prints `=== update available <old> → <new>`
+ * for a newer release, once per version. The coordinator is the agent in the
  * watcher's own herdr pane unless `--coordinator` names it, else `orchestrator-<repository>`. A new start replaces a running watcher of the same
  * repository; one in another repository keeps running.
  *
@@ -26,6 +27,7 @@
  *   jh watch source <name|draft.json|-> --dry-run
  */
 import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
 import { basename, dirname, join, relative } from 'node:path'
 import { readResolvedConfig } from '../config/read-config'
 import type { JackherdConfig } from '../config/schema'
@@ -42,6 +44,7 @@ import { mainCheckout, worktreeNames, worktreeRoot } from '../plans/git'
 import { discoverLanes, isUnchanged, laneSetChange, laneSetLines } from '../plans/lane-discovery'
 import { clockLocaleOf, type PlansSettings, plansSettingsOf, worktreeOf } from '../plans/settings'
 import { boardTexts } from '../plans/texts'
+import { defaultUpdateCheck } from '../sync/if-changed'
 import { herdrLaneStatusSource } from '../terminal/herdr'
 import { startedKit } from '../version/started-kit'
 import {
@@ -135,6 +138,7 @@ import {
 } from './sources'
 import { streamHeartbeatLine } from './stream-output'
 import { WATCH_TEXTS, type WatchTexts } from './texts'
+import { updateAnnouncer } from './update-available'
 import {
   coordinatorWatchEvent,
   deployEvents,
@@ -846,9 +850,11 @@ const watchLanes = async (watch: Watch) => {
   const kit = await startedKit()
   const skillSnapshot = kit ? readOrchestrateSkill(kit.packageRoot) : null
   const skillLine = () => skillLineFor(kit, skillSnapshot, dirname(watch.files.state))
+  const announceUpdate = kit ? updateAnnouncer(homedir(), kit.version, defaultUpdateCheck(), console.log) : null
   while (await pollOnce(watch, watching)) {
     await Bun.sleep(POLL_MS)
     pollLanes(watch, watching)
+    await announceUpdate?.()
     if (endedByKitUpdate(kit, { saveState: () => saveState(watch, watching), log: console.log, skillLine })) return
   }
 }

package/src/watch/report-questions.ts

@@ -7,6 +7,9 @@ const ANY_HEADING = /^(#{1,6})\s/
 const CODE_FENCE = /^\s*(```|~~~)/
 const LIST_ITEM = /^(?:\d+[.)]|[-*])\s/
 const CONTINUATION_LINE = /^\s/
+const LIST_MARKER = /^(?:\d+[.)]|[-*])\s*/
+/** What a section writes when it has nothing to ask: "Keine.", "None.", "Keine offenen Fragen.", a dash. */
+const NO_QUESTIONS = /^(?:(?:keine|none|no|nein)(?:\s+(?:offenen\s+)?(?:fragen?|questions?))?\.?|n\/a|[—–])$/i
 
 /** What the questions part of a message may take: whole up to these limits, else cut question by question. */
 const QUESTION_LINES = 20
@@ -24,13 +27,24 @@ const headings = (lines: readonly string[]): { index: number; level: number; isQ
   })
 }
 
-/** The questions sections of a report, in order: from the heading to the next heading of the same or a higher level. */
+/** True when every line of the body, ignoring blank lines, a list marker and bold, says there is nothing to ask. */
+const asksNothing = (body: readonly string[]): boolean =>
+  body
+    .map((line) => line.trim().replace(LIST_MARKER, '').replaceAll('**', '').trim())
+    .filter((text) => text !== '')
+    .every((text) => NO_QUESTIONS.test(text))
+
+/**
+ * The questions sections of a report, in order: from the heading to the next heading of the same or a higher level.
+ * A section that is empty or only says "Keine." / "None." asks nothing and is left out.
+ */
 export const questionSections = (lines: readonly string[]): QuestionSection[] => {
   const all = headings(lines)
   return all.flatMap((heading, position) => {
     if (!heading.isQuestion) return []
     const next = all.slice(position + 1).find((other) => other.level <= heading.level)
-    return [{ start: heading.index, end: next?.index ?? lines.length }]
+    const end = next?.index ?? lines.length
+    return asksNothing(lines.slice(heading.index + 1, end)) ? [] : [{ start: heading.index, end }]
   })
 }
 

package/src/watch/update-available.ts

@@ -0,0 +1,26 @@
+import { latestVersionIfDue, type UpdateCheck } from '../sync/if-changed'
+import { isNewerVersion } from '../version/release'
+
+/** The one line that wakes the coordinator when npm has a newer release; the orchestrate skill asks the user. */
+export const updateAvailableLine = (installed: string, latest: string): string =>
+  `=== update available ${installed} → ${latest}`
+
+/**
+ * The watcher's daily look at npm, on the hook's timestamp and check, so a day holds one registry question across
+ * both. Prints a line only for a newer plain release it has not announced yet; otherwise nothing, so a quiet
+ * day costs no tokens. Call it on every poll: the timestamp decides whether npm is asked at all.
+ */
+export const updateAnnouncer = (
+  home: string,
+  installed: string,
+  check: UpdateCheck,
+  log: (line: string) => void,
+): (() => Promise<void>) => {
+  let announced: string | null = null
+  return async () => {
+    const latest = await latestVersionIfDue(home, check)
+    if (latest === null || latest === announced || !isNewerVersion(latest, installed)) return
+    announced = latest
+    log(updateAvailableLine(installed, latest))
+  }
+}