jackherd 1.25.0 → 1.26.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 What changed for people who use jackherd, newest first.
 
+## 1.26.0
+
+- **"Your turn" clears what is obsolete, and says why.** A closed entry now keeps the reason it was closed (`jh waiting close <id> --reason "<text>"`, `jh waiting --closed` lists the last 24 hours). The watcher closes an older sent file by itself when the same file was sent again (`newer version: <id>`, whoever sent it) or its lane's worktree is gone (`lane removed: <name>`), and reports it as `waiting closed`. What only looks obsolete is proposed once as `waiting obsolete?`: a send whose lane's pull request was merged or closed, a board row naming such a pull request or a removed lane, a question a later dialog answered in nearly the same words (`superseded`) and a question whose session ended (`session ended`). Nothing but a send is ever closed without you. A refusal by another hook is no longer recorded as an open question. New hook `question-session-end` (on `SessionEnd`) marks the ending session's open questions. The orchestrate skill's `waiting.md` and `events.md` say how to work through a proposal. Run `jh sync` to get the hook and the texts.
+
 ## 1.25.0
 
 - **Every plan phase says in one sentence what it is about.** The plan template puts a line directly under each `### Phase` heading, `**What it is about:** <sentence>` (German: `**Worum es geht:** <Satz>`): what is different afterwards and for whom, or "nothing visible". `jh check` fails a phase the change adds that has tasks and no such line; phases a plan already had are not read, so older plans stay green. `jh plan check` prints a sixth line, `purpose: present` or `purpose: missing <file>:<line> no purpose line in P2, P3`; like the head it is a note and never changes the exit code. In an opened lane the herd shows the sentence dimmed under the head of each phase it draws; the folded row and the sidebar title stay as they are. The plan skill (§ structure), the herd reference and `docs/plan-contract.md` describe it. Run `jh sync` to get the template and the skill text.

package/INSTALL.md

@@ -55,7 +55,7 @@ When `init` creates a new config, it asks:
 | Use it when | the team shares the kit through the repository | the repository must stay untouched, not even untracked files |
 | Lives in | the project's `.claude/` | `~/.claude/` |
 | Skill names | `/plan`, `/implement`, `/orchestrate`, … | `/jh-plan`, `/jh-implement`, `/jh-orchestrate`, … |
-| Hooks | `git-guard`, `watch-guard`, `lane-start-guard`, `merge-guard`, `approval-gate`, `model-gate`, `model-log`, `ask-hint`, `open-question`, `plain-question`, `sent-file`, `browser-guard`, `format-on-edit` | none; `init --global` offers only a `SessionStart` update notice |
+| Hooks | `git-guard`, `watch-guard`, `lane-start-guard`, `merge-guard`, `approval-gate`, `model-gate`, `model-log`, `ask-hint`, `open-question`, `question-session-end`, `plain-question`, `sent-file`, `browser-guard`, `format-on-edit` | none; `init --global` offers only a `SessionStart` update notice |
 | Config | `.jackherd/config.json` | `~/.jackherd/config.json`, used where a repository has none |
 | Update | `jh sync` | `jh update` |
 

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.25.0/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.26.0/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) [![macOS](https://img.shields.io/badge/macOS-supported-brightgreen?logo=apple)](https://unpkg.com/jackherd/INSTALL.md) [![Linux](https://img.shields.io/badge/Linux-supported-brightgreen?logo=linux&logoColor=white)](https://unpkg.com/jackherd/INSTALL.md)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.25.0/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) [![macOS](https://img.shields.io/badge/macOS-supported-brightgreen?logo=apple)](https://unpkg.com/jackherd/INSTALL.md) [![Linux](https://img.shields.io/badge/Linux-supported-brightgreen?logo=linux&logoColor=white)](https://unpkg.com/jackherd/INSTALL.md)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.26.0/assets/icons/space.svg">
 
 # Jack herds your coding agents.
 
@@ -15,29 +15,29 @@ 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.25.0/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.26.0/assets/icons/space.svg">
 
 <p>
-<img src="https://unpkg.com/jackherd@1.25.0/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.26.0/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.25.0/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.26.0/assets/icons/space.svg">
 </p>
 
-<p><img src="https://unpkg.com/jackherd@1.25.0/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.26.0/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.25.0/assets/icons/decide.svg" width="24" height="34" align="middle" alt=""> <b>You make the calls.</b><br>Commits, pushes and merges wait for your approval. Jack merges on green checks only where you said so: one pull request, or a plan's for up to 24 hours. The guards catch mistakes, not intent; a hard boundary takes branch protection.</p>
+<p><img src="https://unpkg.com/jackherd@1.26.0/assets/icons/decide.svg" width="24" height="34" align="middle" alt=""> <b>You make the calls.</b><br>Commits, pushes and merges wait for your approval. Jack merges on green checks only where you said so: one pull request, or a plan's for up to 24 hours. The guards catch mistakes, not intent; a hard boundary takes branch protection.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.25.0/assets/icons/bark.svg" width="24" height="34" align="middle" alt=""> <b>Jack barks.</b><br>A lane gets stuck, a check goes red, a decision needs you: Jack steps in and brings you only what's yours to decide. The herd view shows where every lane stands.</p>
+<p><img src="https://unpkg.com/jackherd@1.26.0/assets/icons/bark.svg" width="24" height="34" align="middle" alt=""> <b>Jack barks.</b><br>A lane gets stuck, a check goes red, a decision needs you: Jack steps in and brings you only what's yours to decide. The herd view shows where every lane stands.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.25.0/assets/icons/skills.svg" width="24" height="34" align="middle" alt=""> <b>Works with your skills.</b><br>Keep your own skills: a lane builds with whichever one you pick. Plans written elsewhere run too, once Jack fills in what they're missing.</p>
+<p><img src="https://unpkg.com/jackherd@1.26.0/assets/icons/skills.svg" width="24" height="34" align="middle" alt=""> <b>Works with your skills.</b><br>Keep your own skills: a lane builds with whichever one you pick. Plans written elsewhere run too, once Jack fills in what they're missing.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.25.0/assets/icons/ear.svg" width="24" height="34" align="middle" alt=""> <b>Jack listens.</b><br>Review comments on a lane's pull request go back to that lane, which fixes them with a test. <code>/jh-follow</code> brings in anything a CLI or an API can read as JSON: tickets, error logs, status pages.</p>
+<p><img src="https://unpkg.com/jackherd@1.26.0/assets/icons/ear.svg" width="24" height="34" align="middle" alt=""> <b>Jack listens.</b><br>Review comments on a lane's pull request go back to that lane, which fixes them with a test. <code>/jh-follow</code> brings in anything a CLI or an API can read as JSON: tickets, error logs, status pages.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.25.0/assets/icons/model.svg" width="24" height="34" align="middle" alt=""> <b>The right model for each phase.</b><br>Every phase names its model: the stronger one where a mistake is expensive (data, security, a migration), the cheaper one for the rest. Lanes start on it, and a hook refuses to start a phase's subagent on a weaker one.</p>
+<p><img src="https://unpkg.com/jackherd@1.26.0/assets/icons/model.svg" width="24" height="34" align="middle" alt=""> <b>The right model for each phase.</b><br>Every phase names its model: the stronger one where a mistake is expensive (data, security, a migration), the cheaper one for the rest. Lanes start on it, and a hook refuses to start a phase's subagent on a weaker one.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.25.0/assets/icons/bowl.svg" width="24" height="34" align="middle" alt=""> <b>A crash or a full context doesn't cost you the work.</b><br>Plan, board and a hand-over file hold the state, not the chat: the next session picks up where the last one stopped.</p>
+<p><img src="https://unpkg.com/jackherd@1.26.0/assets/icons/bowl.svg" width="24" height="34" align="middle" alt=""> <b>A crash or a full context doesn't cost you the work.</b><br>Plan, board and a hand-over file hold the state, not the chat: the next session picks up where the last one stopped.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.25.0/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.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.25.0/assets/icons/space.svg"></p>
+<p><img src="https://unpkg.com/jackherd@1.26.0/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.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.26.0/assets/icons/space.svg"></p>
 
 ## Quickstart
 
@@ -68,22 +68,22 @@ Then `/jh-start` in a repository, and Jack offers your first plan. → [Quicksta
    /jh-orchestrate docs/plans/board-<name>/board.md
    ```
 
-Linux and macOS are supported (Windows through WSL); the requirements are in [INSTALL.md](https://unpkg.com/jackherd/INSTALL.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.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.25.0/assets/icons/space.svg">
+Linux and macOS are supported (Windows through WSL); the requirements are in [INSTALL.md](https://unpkg.com/jackherd/INSTALL.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.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.26.0/assets/icons/space.svg">
 
 ## Follow anything you can query
 
 Tickets, error logs, status pages: if a command or an API call can read it as JSON with your login, Jack can watch it. Recipes cover Jira, Linear, GitHub issues and Projects, Sentry, Google Calendar and status pages; for anything else, `/jh-follow` writes the command with you. One yes, and every change shows up like this:
 
-<img src="https://unpkg.com/jackherd@1.25.0/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.26.0/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: new entries per source, or its last run, red while it fails; opened, a click opens an entry. One that needs you lands in Your turn under the source's label, [ask] has Jack look at it, and a ticket shows on the lane that works it.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.25.0/assets/icons/space.svg">
+The herd sums up your sources in one `Sources` line: new entries per source, or its last run, red while it fails; opened, a click opens an entry. One that needs you lands in Your turn under the source's label, [ask] has Jack look at it, and a ticket shows on the lane that works it.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.26.0/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.25.0/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.26.0/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 |
 | --- | --- | --- |
@@ -118,7 +118,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, and under each phase heading one sentence on what is different afterwards and for whom. 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.25.0/docs/skills-dark.svg" alt="Your own plan or an issue is adopted (Jack adds what is missing, you see the diff) and goes to /jh-orchestrate; /jh-grill hands decisions to /jh-plan; /jh-plan feeds /jh-orchestrate or a single /jh-implement, which your own skill can replace; /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.26.0/docs/skills-dark.svg" alt="Your own plan or an issue is adopted (Jack adds what is missing, you see the diff) and goes to /jh-orchestrate; /jh-grill hands decisions to /jh-plan; /jh-plan feeds /jh-orchestrate or a single /jh-implement, which your own skill can replace; /jh-implement ends in /jh-pre-commit, which runs the reviewers; /jh-diagnose hands a red command to /jh-implement.">
 
 | Skill | Does |
 | --- | --- |
@@ -232,7 +232,7 @@ jackherd sets the model, not the effort and not the advisor: those come from Cla
 | `jh lane close <lane>` | removes a finished lane: agent, worktree, herdr workspace and branch, and marks the board; first checks that nothing is lost, and refuses with every reason; `--dry-run` only checks. Runs without a prompt. |
 | `jh backend` | the shared backend of the lanes (`lanes.backend`, one pane in the main checkout that the watcher keeps): shows its pane, command and handed-over services; `restart`; `release <service> --lane <lane>` stops it and starts it without that service, naming the port the lane starts it on; `return <service>`. Works from any worktree. A busy service port stops a start, nothing frees a port |
 | `jh preview <file>` | renders a Markdown file through the GitHub API into a preview in GitHub and npm style |
-| `jh waiting` | the files and Artifacts sent to you that you have not answered yet (`close <id>…` or `close --all` once you have) |
+| `jh waiting` | the files and Artifacts sent to you that you have not answered yet (`close <id>… [--reason "<text>"]` or `close --all` once you have; `--closed` lists what closed in the last 24 hours with its reason). The watcher closes an older send by itself once the same file was sent again or its lane is gone, and proposes the rest (a merged pull request, a question that looks answered, a session that ended) as `waiting obsolete?` |
 | `jh brief` | three lines for each open lane of the board: its goal, its status and what it needs from you, read from the head of its plan (`--board <board.md>` names the board); after `plans.briefAfterMinutes` (default 60, 0 is off) without a prompt, the `return-brief` hook asks Jack to show it first |
 | `jh context` | how full an agent's context is, as JSON; `--usage [--since 24h\|7d\|<date>]` the tokens a lane used instead (Jack's with `--coordinator`) |
 | `jh config` | the commands and the base branch the repository uses; a missing value goes to stderr with the line to set, and `jh config <key>` for an unset value exits 3 |

package/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.25.0"
+version = "1.26.0"
 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.25.0}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.26.0}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

package/kit/hooks/hooks/open-question/record.ts

@@ -13,8 +13,20 @@ export type QuestionRecord = {
   cwd: string
   session: string
   closedAt: number | null
+  /** Who closed the record and why; absent or null on a record that predates the field or is open. */
+  closedReason?: string | null
+  /** A later dialog's question that probably answered this one in other words; null or absent when none did. */
+  supersededBy?: SupersededBy | null
+  /** When the session that asked this question ended with it still open (the `SessionEnd` hook); null or absent while it runs. */
+  sessionEndedAt?: number | null
 }
 
+/** A later dialog's question that answered a record's question, and when. */
+export type SupersededBy = AnsweredQuestion
+
+const isSupersededBy = (value: unknown): value is SupersededBy =>
+  isRecord(value) && typeof value.question === 'string' && typeof value.answeredAt === 'number'
+
 export type QuestionContext = {
   cwd: string
   session: string
@@ -76,6 +88,26 @@ const resultsOf = (entries: readonly JsonObject[]): Map<string, JsonObject | nul
   return results
 }
 
+/** How the client words the result of a dialog that a `PreToolUse` hook sent back: the user never saw it. */
+const HOOK_REFUSAL = new RegExp(`^PreToolUse:${ASK_USER_QUESTION_TOOL} hook error`)
+
+const resultTextOf = (block: JsonObject): string => {
+  if (typeof block.content === 'string') return block.content
+  if (!Array.isArray(block.content)) return ''
+  return block.content.map((part) => (isRecord(part) && typeof part.text === 'string' ? part.text : '')).join('\n')
+}
+
+/** The ids of the dialog calls a hook refused: the user was never asked, so they leave nothing open. */
+const refusedByHookOf = (entries: readonly JsonObject[]): Set<string> =>
+  new Set(
+    entries.flatMap((entry) =>
+      contentOf(entry)
+        .filter((block) => block.type === CONTENT_BLOCK_TYPE.toolResult && block.is_error === true)
+        .filter((block) => HOOK_REFUSAL.test(resultTextOf(block)))
+        .flatMap((block) => (typeof block.tool_use_id === 'string' ? [block.tool_use_id] : [])),
+    ),
+  )
+
 /** Whether the transcript went on after the call, other than with the rest of the message that made it. */
 const wentOnAfter = (ask: Ask, entries: readonly JsonObject[]): boolean =>
   entries
@@ -102,6 +134,49 @@ export const answeredSince = (
   at: number,
 ): AnsweredQuestion | undefined => answered.find((done) => done.question === question && done.answeredAt > at)
 
+/** The reason a record carries when a later dialog answered its question; the package's `closeReasonOf` spells it the same (contract test). */
+export const ANSWERED_REASON = 'user: answered in a dialog'
+
+/** Fewest words the shorter of two questions has to carry before one can be taken for a rewording of the other. */
+const MIN_REWORDED_WORDS = 3
+/** Share of the longer question's words the shorter one has to keep, with no word of its own besides. */
+const MIN_REWORDED_SHARE = 0.7
+
+/** Most words the longer question may add: one more word can be a restriction (`lane A`), two or more are another question. */
+const MAX_EXTRA_WORDS = 1
+/** A word that turns a question around: adding one is no rewording (`run it` against `do not run it`). */
+const NEGATIONS: ReadonlySet<string> = new Set(['nicht', 'kein', 'keine', 'keinen', 'nie', 'not', 'no', 'never'])
+
+const wordsOf = (question: string): Set<string> =>
+  new Set(question.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((word) => word !== ''))
+
+/**
+ * Whether two different questions read as one asked twice: all the words of the shorter one are in the longer one,
+ * and they are most of it. A word that only one side has and the other lacks (`A` against `B`, `export` against
+ * `import`) makes them two questions.
+ */
+export const isRewording = (left: string, right: string): boolean => {
+  const [short, long] = [wordsOf(left), wordsOf(right)].sort((first, second) => first.size - second.size)
+  if (short.size < MIN_REWORDED_WORDS || short.size / long.size < MIN_REWORDED_SHARE) return false
+  if (![...short].every((word) => long.has(word))) return false
+  const extra = [...long].filter((word) => !short.has(word))
+  return extra.length <= MAX_EXTRA_WORDS && !extra.some((word) => NEGATIONS.has(word))
+}
+
+/**
+ * The record with `supersededBy` set to the first dialog after it that answered a different question that reads as the
+ * same one reworded; the record itself when none did or one is set already. Only a suspicion for the coordinator to
+ * weigh: it never closes the record.
+ */
+export const withSupersededBy = (record: QuestionRecord, answered: readonly AnsweredQuestion[]): QuestionRecord => {
+  if (record.closedAt !== null || record.supersededBy) return record
+  const later = answered.find(
+    ({ question, answeredAt }) =>
+      answeredAt > record.askedAt && question !== record.question && isRewording(question, record.question),
+  )
+  return later ? { ...record, supersededBy: { question: later.question, answeredAt: later.answeredAt } } : record
+}
+
 /**
  * The questions of the main thread that stand open: their dialog was rejected or interrupted, or answered with "later",
  * and no dialog answered the same text since. A call that carries its own answers asked nobody; a sidechain is no dialog
@@ -110,7 +185,9 @@ export const answeredSince = (
 export const openQuestionsOf = (entries: readonly unknown[], context: QuestionContext): QuestionRecord[] => {
   const thread = mainThread(entries)
   const results = resultsOf(thread)
+  const refused = refusedByHookOf(thread)
   return asksOf(thread)
+    .filter((ask) => !refused.has(ask.toolUseId))
     .filter((ask) => endedUnanswered(ask, results, thread))
     .map((ask) => ({ ask, question: questionTextOf(ask.question) }))
     .filter(({ ask, question }) => question !== '' && !answeredSince(context.answered, question, ask.askedAt))
@@ -133,4 +210,7 @@ export const isQuestionRecord = (value: unknown): value is QuestionRecord =>
   typeof value.askedAt === 'number' &&
   typeof value.cwd === 'string' &&
   typeof value.session === 'string' &&
-  (value.closedAt === null || typeof value.closedAt === 'number')
+  (value.closedAt === null || typeof value.closedAt === 'number') &&
+  (value.closedReason == null || typeof value.closedReason === 'string') &&
+  (value.supersededBy == null || isSupersededBy(value.supersededBy)) &&
+  (value.sessionEndedAt == null || typeof value.sessionEndedAt === 'number')

package/kit/hooks/hooks/open-question/run.ts

@@ -1,6 +1,13 @@
 import { ASK_USER_QUESTION_TOOL, parseTranscript } from '../shared/dialog-answers'
 import { isRecord } from '../shared/json'
-import { answeredQuestionsOf, answeredSince, openQuestionsOf, type QuestionRecord } from './record'
+import {
+  ANSWERED_REASON,
+  answeredQuestionsOf,
+  answeredSince,
+  openQuestionsOf,
+  type QuestionRecord,
+  withSupersededBy,
+} from './record'
 
 /** Everything with a side effect, passed in so a test reaches the flow without git, files or a clock. */
 export type OpenQuestionDependencies = {
@@ -42,14 +49,21 @@ export const runOpenQuestion = (input: unknown, dependencies: OpenQuestionDepend
     const answered = answeredQuestionsOf(entries)
     for (const record of stored.filter(({ closedAt }) => closedAt === null)) {
       const answer = answeredSince(answered, record.question, record.askedAt)
-      if (answer) dependencies.writeRecord(main, { ...record, closedAt: answer.answeredAt })
+      if (answer) {
+        dependencies.writeRecord(main, { ...record, closedAt: answer.answeredAt, closedReason: ANSWERED_REASON })
+        continue
+      }
+      if (record.session !== session) continue
+      const marked = withSupersededBy(record, answered)
+      if (marked !== record) dependencies.writeRecord(main, marked)
+      else if (record.sessionEndedAt != null) dependencies.writeRecord(main, { ...record, sessionEndedAt: null })
     }
     const known = new Set(stored.map(({ id }) => id))
     const openTexts = new Set(stored.filter(({ closedAt }) => closedAt === null).map(({ question }) => question))
     for (const record of openQuestionsOf(entries, { cwd, session, answered, idOf: dependencies.idOf })) {
       if (known.has(record.id) || openTexts.has(record.question)) continue
       openTexts.add(record.question)
-      dependencies.writeRecord(main, record)
+      dependencies.writeRecord(main, withSupersededBy(record, answered))
     }
   } catch {
     // A failed record is no record; the herd shows no question.

package/kit/hooks/hooks/question-session-end/index.ts

@@ -0,0 +1,18 @@
+// SessionEnd hook of Claude Code, shipped by jackherd: marks the still open question records that the ending session
+// asked (`sessionEndedAt` in `.jackherd/questions/` of the main checkout), also on `/clear`, so the watcher can propose
+// them as `session ended`. It marks only its own session's records, prints nothing, never blocks and always exits 0.
+import { mainCheckoutOf } from '../shared/checkout'
+import { readQuestionRecords, writeQuestionRecord } from '../open-question/store'
+import { runQuestionSessionEnd } from './run'
+
+try {
+  runQuestionSessionEnd(JSON.parse(await Bun.stdin.text()), {
+    mainCheckoutOf,
+    readRecords: readQuestionRecords,
+    writeRecord: writeQuestionRecord,
+    now: Date.now,
+  })
+} catch {
+  // Unreadable input marks nothing.
+}
+process.exit(0)

package/kit/hooks/hooks/question-session-end/run.ts

@@ -0,0 +1,37 @@
+import { isRecord } from '../shared/json'
+import type { QuestionRecord } from '../open-question/record'
+
+/** Everything with a side effect, passed in so a test reaches the flow without git, files or a clock. */
+export type SessionEndDependencies = {
+  mainCheckoutOf: (cwd: string) => string
+  readRecords: (main: string) => QuestionRecord[]
+  writeRecord: (main: string, record: QuestionRecord) => void
+  now: () => number
+}
+
+/**
+ * The open question records that `session` asked and that carry no end mark yet, marked `sessionEndedAt`. Only the
+ * records of the ending session: another session in the same directory is not touched.
+ */
+export const endedRecords = (records: readonly QuestionRecord[], session: string, now: number): QuestionRecord[] =>
+  records
+    .filter((record) => record.session === session && record.closedAt === null && record.sessionEndedAt == null)
+    .map((record) => ({ ...record, sessionEndedAt: now }))
+
+/**
+ * Marks the ending session's still open questions. Claude Code's `SessionEnd` hook input: `session_id`, `cwd`, `reason`
+ * (`clear`, `logout`, `prompt_input_exit`, `resume`, `other`); every reason ends the session's own questions, the mark
+ * is only a suspicion for the watcher to propose. Writes nothing on any failure.
+ */
+export const runQuestionSessionEnd = (input: unknown, dependencies: SessionEndDependencies): void => {
+  try {
+    if (!isRecord(input)) return
+    const { cwd, session_id: session } = input
+    if (typeof cwd !== 'string' || typeof session !== 'string') return
+    const main = dependencies.mainCheckoutOf(cwd)
+    for (const record of endedRecords(dependencies.readRecords(main), session, dependencies.now()))
+      dependencies.writeRecord(main, record)
+  } catch {
+    // A failed mark is no mark; the question stays open as before.
+  }
+}

package/kit/hooks/hooks/sent-file/record.ts

@@ -15,6 +15,8 @@ export type SentRecord = {
   session: string
   agentId: string | null
   closedAt: number | null
+  /** Who closed the record and why; absent or null on a record that predates the field or is open. */
+  closedReason?: string | null
 }
 
 export type SentCall = {
@@ -125,4 +127,5 @@ export const isSentRecord = (value: unknown): value is SentRecord =>
   typeof value.cwd === 'string' &&
   typeof value.session === 'string' &&
   (value.agentId === null || typeof value.agentId === 'string') &&
-  (value.closedAt === null || typeof value.closedAt === 'number')
+  (value.closedAt === null || typeof value.closedAt === 'number') &&
+  (value.closedReason == null || typeof value.closedReason === 'string')

package/kit/hooks/hooks.json

@@ -96,6 +96,14 @@
       "timeout": 10
     }
   },
+  "question-session-end": {
+    "event": "SessionEnd",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/question-session-end/index.ts",
+      "timeout": 5
+    }
+  },
   "return-brief": {
     "event": "UserPromptSubmit",
     "handler": {

package/kit/workflow/skills/orchestrate/references/waiting.md

@@ -1,6 +1,6 @@
 # § 4 Waiting for you: the rows beyond the basic one
 
-Read when `jh waiting` or the heartbeat's `for you (<n>)` names this file, a lane waits on the user's answer,
+Read when a watcher line `waiting closed` or `waiting obsolete?`, `jh waiting` or the heartbeat's `for you (<n>)` names this file, a lane waits on the user's answer,
 or something you sent the user needs no row of its own.
 
 - **A lane waits on the answer:** add its name as in the lanes table (a phase may follow) to the optional
@@ -14,3 +14,17 @@ or something you sent the user needs no row of its own.
   the user's. A dialog that ended without an answer (declined, cut off, or answered "later") needs none
   either: the kit hook `open-question` records it, and it closes once the same question is answered in a
   dialog.
+- **The watcher closes a send by itself** when a newer send has the same first entry (`newer version: <id>`,
+  whoever sent it) or its lane's worktree stayed gone for two heartbeats (`lane removed: <name>`), and reports
+  `waiting closed <n>: <id> <reason>; …`. `jh waiting --closed` lists the last 24 hours with reasons.
+- **A proposal `waiting obsolete? <key> <reason> "<text>"`** closes nothing and comes once per reason. Check
+  it against the thing itself. A key `row-…` is a board row (find it by the quoted text): set its status cell to
+  `done` (`erledigt` in a German board) with `(<you> <DD.MM.> <HH:MM>: <why>)`; the table is yours alone, no
+  code writes into it. Any other key is a record id: `jh waiting close <id> --reason "<why>"`. A thing still
+  wanted stays open. Reasons: `pr #<n> merged|closed`,
+  `lane removed: <name>`, `superseded: <question>` (a later dialog answered it in nearly the same words),
+  `session ended`.
+- **A decision the hooks cannot see** (made in the chat or in a lane's report, written into the board by you):
+  close the records it settles in the same turn, `jh waiting close <id> --reason "decided: <decision>"`.
+- **A board row's key is a hash of its item text:** a reworded row gets a new key and can raise its proposal
+  again, as can an unreadable `.jackherd/sent`; close it then.

package/package.json

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

package/src/check/skill-budget-defaults.ts

@@ -71,7 +71,9 @@ export const KIT_SKILL_TARGETS: Readonly<Record<string, number>> = {
   // The dev server restart by PID and `herdr pane run`, the form the merge guard passes (+54).
   '.claude/skills/orchestrate/references/start-lane.md': 766,
   // Core cut: § 4 waiting rows beyond the basic one, moved out of the core.
-  '.claude/skills/orchestrate/references/waiting.md': 216,
+  // What the watcher closes by itself, how to work through a `waiting obsolete?` proposal, and the rule for a
+  // decision the hooks cannot see: the coordinator's only text for the closing flow.
+  '.claude/skills/orchestrate/references/waiting.md': 450,
   '.claude/skills/orchestrate/references/watch-without-monitor.md': 154,
   // Prose cut, round 2: cut to its mandatory rules, measured size plus 5 %.
   // Language split: the note that a template renders in the language of its file name and that a heading in any other language carries a marker (+27).

package/src/plans/closable-records.ts

@@ -1,16 +1,16 @@
 import { join } from 'node:path'
 import { readRecords, writeRecordAtomically } from '../shared/private-records'
 
-/** A record that waits on the user until something sets `closedAt`. */
-export type ClosableRecord = { id: string; closedAt: number | null }
+/** A record that waits on the user until something sets `closedAt`; `closedReason` says who closed it and why. */
+export type ClosableRecord = { id: string; closedAt: number | null; closedReason?: string | null }
 
 export type ClosableRecordLog<T extends ClosableRecord> = {
   /** Every record of the log in the main checkout, oldest first; nothing when the directory is missing or unreadable. */
   read: (root: string) => T[]
-  /** Marks the named records `closedAt` and returns how many it closed; one closed already, or unknown, counts for nothing. */
-  close: (root: string, ids: readonly string[], now: number) => number
-  /** Marks every open record `closedAt` and returns how many it closed. */
-  closeAll: (root: string, now: number) => number
+  /** Marks the named records `closedAt` with `reason` and returns how many it closed; one closed already, or unknown, counts for nothing. */
+  close: (root: string, ids: readonly string[], now: number, reason: string) => number
+  /** Marks every open record `closedAt` with `reason` and returns how many it closed. */
+  closeAll: (root: string, now: number, reason: string) => number
 }
 
 /** The log of `.jackherd/<directoryName>/`: records the `guard` accepts, ordered by `timeOf`. */
@@ -21,14 +21,15 @@ export const closableRecordLog = <T extends ClosableRecord>(
 ): ClosableRecordLog<T> => {
   const directoryOf = (root: string): string => join(root, '.jackherd', directoryName)
   const read = (root: string): T[] => readRecords(directoryOf(root), guard, timeOf)
-  const closeWhere = (root: string, isChosen: (record: T) => boolean, now: number): number => {
+  const closeWhere = (root: string, isChosen: (record: T) => boolean, now: number, reason: string): number => {
     const open = read(root).filter((record) => record.closedAt === null && isChosen(record))
-    for (const record of open) writeRecordAtomically(directoryOf(root), { ...record, closedAt: now })
+    for (const record of open)
+      writeRecordAtomically(directoryOf(root), { ...record, closedAt: now, closedReason: reason })
     return open.length
   }
   return {
     read,
-    close: (root, ids, now) => closeWhere(root, (record) => ids.includes(record.id), now),
-    closeAll: (root, now) => closeWhere(root, () => true, now),
+    close: (root, ids, now, reason) => closeWhere(root, (record) => ids.includes(record.id), now, reason),
+    closeAll: (root, now, reason) => closeWhere(root, () => true, now, reason),
   }
 }

package/src/plans/close-reason.ts

@@ -0,0 +1,19 @@
+import { ellipsize, terminalSafe } from '../plan-format/terminal-text'
+
+/** Who or what closes a record: the user (a click), the coordinator, a newer send of the same file, a removed lane. */
+export const CLOSE_REASON = {
+  user: 'user',
+  coordinator: 'coordinator',
+  newerVersion: 'newer version',
+  laneRemoved: 'lane removed',
+} as const
+
+export type CloseReasonKind = (typeof CLOSE_REASON)[keyof typeof CLOSE_REASON]
+
+const MAX_DETAIL = 200
+
+/** The reason a record carries: the kind, then a free detail on one line without control characters (`coordinator: decided …`). */
+export const closeReasonOf = (kind: CloseReasonKind, detail = ''): string => {
+  const text = ellipsize(terminalSafe(detail.replace(/\s+/g, ' ')).trim(), MAX_DETAIL)
+  return text === '' ? kind : `${kind}: ${text}`
+}

package/src/plans/live.ts

@@ -10,6 +10,7 @@ import { closeWaiting } from '../waiting/command'
 import { isWatcherRunning } from '../watch/watcher-lock'
 import { ASKING_NOTICE, type AskDependencies, askCoordinator } from './ask-coordinator'
 import type { AskTarget } from './ask-target'
+import { CLOSE_REASON, closeReasonOf } from './close-reason'
 import { errorText } from './error-text'
 import { focusedScreen } from './focus-overlay'
 import { noPullRequests } from './github'
@@ -513,7 +514,7 @@ const applyBlockClick = (live: Live, outcome: BlockClick): void => {
       sprintFile: live.source.sprintFile,
       language: live.source.settings.boardLanguage,
       now: new Date(),
-      closeRecords: (ids) => closeWaiting(live.source.root, ids, Date.now()),
+      closeRecords: (ids) => closeWaiting(live.source.root, ids, Date.now(), closeReasonOf(CLOSE_REASON.user)),
     })
     if (closed) live.closing = [...live.closing, outcome.done]
     live.notice = notice

package/src/plans/question-records.ts

@@ -12,8 +12,23 @@ export type QuestionRecord = {
   cwd: string
   session: string
   closedAt: number | null
+  /** Who closed the record and why (`closeReasonOf`); absent or null on a record that predates the field or is open. */
+  closedReason?: string | null
+  /** The later dialog that probably answered this question in other words; null or absent when none did. */
+  supersededBy?: SupersededBy | null
+  /** When the session that asked this question ended with it still open (the `SessionEnd` hook); null or absent while it runs. */
+  sessionEndedAt?: number | null
 }
 
+/** A later dialog's question that answered this one, and when. */
+export type SupersededBy = { question: string; answeredAt: number }
+
+const isSupersededBy = (value: unknown): value is SupersededBy =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as SupersededBy).question === 'string' &&
+  typeof (value as SupersededBy).answeredAt === 'number'
+
 /** Whether `value` has the shape of a question record's id: twelve lower-case hex digits. */
 export const isQuestionId = isRecordId
 
@@ -28,13 +43,19 @@ export const isQuestionRecord = (value: unknown): value is QuestionRecord => {
     typeof record.askedAt === 'number' &&
     typeof record.cwd === 'string' &&
     typeof record.session === 'string' &&
-    (record.closedAt === null || typeof record.closedAt === 'number')
+    (record.closedAt === null || typeof record.closedAt === 'number') &&
+    (record.closedReason == null || typeof record.closedReason === 'string') &&
+    (record.supersededBy == null || isSupersededBy(record.supersededBy)) &&
+    (record.sessionEndedAt == null || typeof record.sessionEndedAt === 'number')
   )
 }
 
+/** What a row of "Your turn" shows of a question, safe for the terminal. */
+export const questionTextOf = ({ question }: QuestionRecord): string => terminalSafe(question)
+
 const itemOf = (record: QuestionRecord): WaitingItem => ({
   since: clockText(record.askedAt),
-  item: terminalSafe(record.question),
+  item: questionTextOf(record),
   kind: WAITING_KIND.question,
   id: record.id,
   open: true,

package/src/plans/questions-read.ts

@@ -6,8 +6,8 @@ const log = closableRecordLog('questions', isQuestionRecord, ({ askedAt }) => as
 /** Every record of the question log in the main checkout, oldest first; nothing when the directory is missing or unreadable. */
 export const readQuestionRecords = log.read
 
-/** Marks the named records `closedAt` and returns how many it closed; one closed already, or unknown, counts for nothing. */
+/** Marks the named records `closedAt` with a reason and returns how many it closed; one closed already, or unknown, counts for nothing. */
 export const closeQuestionRecords = log.close
 
-/** Marks every open record `closedAt` and returns how many it closed. */
+/** Marks every open record `closedAt` with a reason and returns how many it closed. */
 export const closeAllQuestionRecords = log.closeAll

package/src/plans/sent-files-read.ts

@@ -6,8 +6,8 @@ const log = closableRecordLog('sent', isSentFileRecord, ({ sentAt }) => sentAt)
 /** Every record of the sent-file log in the main checkout, oldest first; nothing when the directory is missing or unreadable. */
 export const readSentRecords = log.read
 
-/** Marks the named records `closedAt` and returns how many it closed; one closed already, or unknown, counts for nothing. */
+/** Marks the named records `closedAt` with a reason and returns how many it closed; one closed already, or unknown, counts for nothing. */
 export const closeSentRecords = log.close
 
-/** Marks every open record `closedAt` and returns how many it closed. */
+/** Marks every open record `closedAt` with a reason and returns how many it closed. */
 export const closeAllSentRecords = log.closeAll