jackherd 1.12.2 → 1.12.3

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 What changed for people who use jackherd, newest first.
 
+## 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.
+- **A report shows at once.** `jh task start`, an open question or a sent file wakes the reader through the records under `.jackherd/`, without waiting for the next refresh.
+- **Rows on the full width.** A point of "Your turn" and an entry under "Sources" take the whole pane and are cut only at its edge (in "Your turn" before the time, which stays flush right). `[ask]`, `[done]` and the other buttons no longer keep room beside every row: they show only at the row under the selection or the mouse, flush right at the edge, laid over the end of its text (in "Your turn" over its time too), in one colour, teal, in both blocks. A point of "Your turn" cut off at the edge opens on a click, like an entry of a source, its text under its first line.
+- **"Your turn" shows only what waits on you.** The lines of the board's next section no longer stand in it as `◷ … time open`; they carried no action and repeated what waited.
+- **A source's own time.** An entry under "Sources" shows the time the source gives for it (`map.updatedAt`), no longer the time the watcher read it, so entries read in one run keep their own times. Without `updatedAt`, or without a date in it, it shows the last change as before.
+- **A lighter read of the board.** A session whose own log has rested for more than a day is no longer searched for running subagents, so a read no longer checks the logs of every past session (about 2,000 in a busy project).
+- **Fewer git calls.** The commits a lane is ahead of the base are counted only when its worktree, its commits or the base moved, like `git status` before, not on every refresh.
+- **The `plan-format` export:** a phase's `touched` and `merged` are now one field `work` (`PHASE_WORK`). `touched` and `merged` stay, derived from it and marked deprecated, until the next minor release.
+
 ## 1.12.2
 
 - **The merge guard no longer asks about a plain script run.** A command like `timeout 170 bun --cpu-prof-dir=$S $S/profile-refresh.ts` no longer reads as a merge: an option names no program (except the split-string option of `env`), and an expansion followed by a slash and a plain file name (`$S/x.ts`, `$DIR/gh`) names that program like a plain word. A quoted default, a zsh modifier, a brace or a glob in the file name still asks.

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.2/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.3/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.2/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.3/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.2/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.3/assets/icons/space.svg">
 
 <p>
-<img src="https://unpkg.com/jackherd@1.12.2/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.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.">
 <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.2/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.3/assets/icons/space.svg">
 </p>
 
-<p><img src="https://unpkg.com/jackherd@1.12.2/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/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.2/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/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.2/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/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.2/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/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.2/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/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.2/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.2/assets/icons/space.svg"></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>
 
 ## 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.2/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.3/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.2/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.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.">
 
-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.2/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.3/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.2/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.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.">
 
 | 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.2/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.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.">
 
 | Skill | Does |
 | --- | --- |

package/dist/plan-format.d.ts

@@ -199,19 +199,33 @@ type MisplacedDeferral = {
     target: string;
     corrected: string;
 };
+/** What the worktree did to a phase, against the base branch: its ticks differ (`touched`), and the base already carries a tick of it (`merged`): a run of it was merged. */
+declare const PHASE_WORK: {
+    readonly touched: "touched";
+    readonly merged: "merged";
+};
+type PhaseWork = (typeof PHASE_WORK)[keyof typeof PHASE_WORK];
+/** `work` with the flags it replaced, which published readers of `PlanPhase` and `PhaseProgress` may still read. */
+type PhaseWorkFields = {
+    work: PhaseWork;
+    /** @deprecated Read `work`: set exactly when `work` is. Removed in the next minor release. */
+    touched?: true;
+    /** @deprecated Read `work === PHASE_WORK.merged`. Removed in the next minor release. */
+    merged?: true;
+};
 /**
- * `touched` is set by the phase source when the worktree's ticks differ from the base branch's, `merged` beside it
- * when the base branch already carries a tick of the phase: a run of it was merged. `deferred` holds the checkboxes
- * moved to another phase; they are not among `items`, so they count neither as open nor as done.
+ * `work` is set by the phase source and says nothing for a phase the worktree left as the base has it; a merged phase
+ * is touched as well. `deferred` holds the checkboxes moved to another phase; they are not among `items`, so they
+ * count neither as open nor as done.
  */
 type PlanPhase = {
     id: string;
     title: string;
     items: ChecklistItem[];
     deferred?: DeferredItem[];
-    touched?: true;
-    merged?: true;
-};
+} & Partial<PhaseWorkFields>;
+/** The fields a phase's `work` sets, the deprecated `touched` and `merged` derived from it. */
+declare const phaseWorkFields: (work: PhaseWork) => PhaseWorkFields;
 /** A phase heading with its 1-based line, the lower-case id and the title. */
 type PhaseHeading = {
     line: number;
@@ -455,7 +469,7 @@ declare const mergedPhasesWithOpenBoxes: (markdown: string, base: string, langua
 declare const boardRowsWithoutPhase: (markdown: string, language: PlanLanguage, previousLines: ReadonlySet<string>) => RowWithoutPhase[];
 
 /**
- * `title` is null when the sprint names a phase the plan does not have; `touched`, `merged` and `deferred` carry the
+ * `title` is null when the sprint names a phase the plan does not have; `work` and `deferred` carry the
  * plan phase's own, and the deferred checkboxes are in neither `done` nor `total`.
  */
 type PhaseProgress = {
@@ -465,9 +479,7 @@ type PhaseProgress = {
     total: number;
     items: ChecklistItem[];
     deferred?: DeferredItem[];
-    touched?: true;
-    merged?: true;
-};
+} & Partial<PhaseWorkFields>;
 type StepProgress = {
     step: PlanStep;
     phases: PhaseProgress[];
@@ -579,4 +591,4 @@ declare const readSprintDocument: (markdown: string, language: PlanLanguage) =>
  */
 declare const readPhaseDependencies: (planMarkdown: string, language: PlanLanguage) => Record<string, string>;
 
-export { ADDRESS_FORM, APPOINTMENT_VOCABULARY, APPROVAL_TEXTS, type ChecklistItem, type ColumnModel, type DeferredItem, type DriftFinding, LANE_PROMPT_OPENING, LANGUAGE_NAME, type LaneProgress, type LongPhaseTitle, type MergedPhaseWithOpenBoxes, type MisplacedDeferral, NEXT_VOCABULARY, PHASE_CELL_LIMIT, PHASE_ID_PREFIX, PHASE_TITLE_LIMIT, PLAN_LANGUAGE, PLAN_STATUS, PLAN_VOCABULARY, PROSE_REASON, type PhaseDependency, type PhaseHeading, type PhaseProgress, type PhaseSchedule, type PhaseTally, type PhaseWithoutGate, type PhaseWithoutRow, type PlanHeader, type PlanLanguage, type PlanPhase, type PlanStatus, type PlanStep, type PlanVocabulary, type PlansByHref, type ProseReason, RESPONSE_ADDRESS, type ResponseAddress, type RowWithProse, type RowWithoutPhase, SELF_MERGE_LABEL, SHORT_NAME_LIMIT, SHORT_NAME_PROBLEM, STANDING_APPROVAL_TEXTS, type ShortNameFinding, type ShortNameProblem, type SprintDocument, type SprintLane, type SprintPlanRow, type SprintPlanTable, type StatusWord, type StepProgress, WAITING_VOCABULARY, activeItem, boardRowsWithProse, boardRowsWithoutPhase, classifyStatus, columnModels, countDecisions, criticalPath, currentPhase, currentPhaseOf, deferralTarget, differsFromColumn, endsPhase, findDrift, hasLanesTable, isCheckboxLine, isDocumentationGateItem, isOpenCheckboxLine, isPhaseFinished, isPhaseOpen, isPlanLanguage, isReviewGateLine, isTickedUnmerged, laneNameOf, laneProgress, longPhaseTitles, mergedPhasesWithOpenBoxes, misplacedDeferrals, newPhasesWithoutReviewGate, onlyDocumentationOpen, parallelGroups, parallelGroupsOfPlan, parseDependencyTable, parsePlanPhases, parseSprintLanes, phaseHeading, phaseHeadingPattern, phaseHeadings, phaseIdsOfCell, phaseIdsOfPlan, phaseLabel, phaseLabels, phaseProgress, phaseWaves, phasesText, phasesWithoutDependencyRow, readPhaseDependencies, readPlanHeader, readSprintDocument, resolvePlanPath, sectionHeading, shortNameFindings, shortTitle, sprintTitleOf, sumPhases, tallyPhases, wavesOfPlan, withoutRepeats };
+export { ADDRESS_FORM, APPOINTMENT_VOCABULARY, APPROVAL_TEXTS, type ChecklistItem, type ColumnModel, type DeferredItem, type DriftFinding, LANE_PROMPT_OPENING, LANGUAGE_NAME, type LaneProgress, type LongPhaseTitle, type MergedPhaseWithOpenBoxes, type MisplacedDeferral, NEXT_VOCABULARY, PHASE_CELL_LIMIT, PHASE_ID_PREFIX, PHASE_TITLE_LIMIT, PHASE_WORK, PLAN_LANGUAGE, PLAN_STATUS, PLAN_VOCABULARY, PROSE_REASON, type PhaseDependency, type PhaseHeading, type PhaseProgress, type PhaseSchedule, type PhaseTally, type PhaseWithoutGate, type PhaseWithoutRow, type PhaseWork, type PhaseWorkFields, type PlanHeader, type PlanLanguage, type PlanPhase, type PlanStatus, type PlanStep, type PlanVocabulary, type PlansByHref, type ProseReason, RESPONSE_ADDRESS, type ResponseAddress, type RowWithProse, type RowWithoutPhase, SELF_MERGE_LABEL, SHORT_NAME_LIMIT, SHORT_NAME_PROBLEM, STANDING_APPROVAL_TEXTS, type ShortNameFinding, type ShortNameProblem, type SprintDocument, type SprintLane, type SprintPlanRow, type SprintPlanTable, type StatusWord, type StepProgress, WAITING_VOCABULARY, activeItem, boardRowsWithProse, boardRowsWithoutPhase, classifyStatus, columnModels, countDecisions, criticalPath, currentPhase, currentPhaseOf, deferralTarget, differsFromColumn, endsPhase, findDrift, hasLanesTable, isCheckboxLine, isDocumentationGateItem, isOpenCheckboxLine, isPhaseFinished, isPhaseOpen, isPlanLanguage, isReviewGateLine, isTickedUnmerged, laneNameOf, laneProgress, longPhaseTitles, mergedPhasesWithOpenBoxes, misplacedDeferrals, newPhasesWithoutReviewGate, onlyDocumentationOpen, parallelGroups, parallelGroupsOfPlan, parseDependencyTable, parsePlanPhases, parseSprintLanes, phaseHeading, phaseHeadingPattern, phaseHeadings, phaseIdsOfCell, phaseIdsOfPlan, phaseLabel, phaseLabels, phaseProgress, phaseWaves, phaseWorkFields, phasesText, phasesWithoutDependencyRow, readPhaseDependencies, readPlanHeader, readSprintDocument, resolvePlanPath, sectionHeading, shortNameFindings, shortTitle, sprintTitleOf, sumPhases, tallyPhases, wavesOfPlan, withoutRepeats };

package/dist/plan-format.js

@@ -229,6 +229,8 @@ var boardRowsWithProse = (markdown, language, previousLines) => {
 };
 
 // src/plan-format/phases.ts
+var PHASE_WORK = { touched: "touched", merged: "merged" };
+var phaseWorkFields = (work) => work === PHASE_WORK.merged ? { work, touched: true, merged: true } : { work, touched: true };
 var REVIEW_GATE = /^\s*\*\*review[- ]gate\b/i;
 var PHASE_END = /^#{1,3}\s/;
 var CHECKBOX = /^\s*[-*]\s+\[([ xX])\]\s+(.*)$/;
@@ -391,8 +393,7 @@ var phaseProgress = (phases, id) => {
     total: items.length,
     items,
     ...phase?.deferred ? { deferred: phase.deferred } : {},
-    ...phase?.touched ? { touched: true } : {},
-    ...phase?.merged ? { merged: true } : {}
+    ...phase?.work ? phaseWorkFields(phase.work) : {}
   };
 };
 var isPhaseFinished = ({ items }) => items.length > 0 && items.every(({ done }) => done);
@@ -400,7 +401,7 @@ var isPhaseOpen = (phase) => phase.items.length > 0 && !isPhaseFinished(phase);
 var isWritten = ({ total }) => total > 0;
 var newestWrittenStepIndex = (steps) => steps.reduce((last, { phases }, index) => phases.some(isWritten) ? index : last, -1);
 var newestRowIndex = (steps) => steps.reduce((last, { step }, index) => step.withoutRow ? last : index, -1);
-var isTouched = (phase) => phase.touched === true && isWritten(phase);
+var isTouched = (phase) => phase.work !== void 0 && isWritten(phase);
 var isTickedUnmerged = (phase) => isTouched(phase) && isPhaseFinished(phase);
 var newestStepWith = (steps, pick) => {
   for (let stepIndex = steps.length - 1; stepIndex >= 0; stepIndex--) {
@@ -913,6 +914,7 @@ export {
   PHASE_CELL_LIMIT,
   PHASE_ID_PREFIX,
   PHASE_TITLE_LIMIT,
+  PHASE_WORK,
   PLAN_LANGUAGE,
   PLAN_STATUS,
   PLAN_VOCABULARY,
@@ -966,6 +968,7 @@ export {
   phaseLabels,
   phaseProgress,
   phaseWaves,
+  phaseWorkFields,
   phasesText,
   phasesWithoutDependencyRow,
   readPhaseDependencies,

package/herdr-plugin/herdr-plugin.toml

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

package/package.json

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

package/src/context/session-log.ts

@@ -2,6 +2,7 @@ import { closeSync, existsSync, fstatSync, openSync, readdirSync, readSync, stat
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { CLAUDE_DIRECTORY, SESSION_LOGS_DIRECTORY } from '../claude/paths'
+import { boundedMemo } from '../shared/bounded-memo'
 import { isRecord } from '../shared/is-record'
 
 /** A tail read before: the file as it was (inode, size, modification time), its lines and the byte offset each starts at. */
@@ -222,18 +223,15 @@ export const parseLogEntry = (line: string): Record<string, unknown> | null => {
 /** How many parsed lines `keptLogEntry` holds: the answers and last entries of the few dozen logs the herd follows. */
 export const KEPT_LOG_ENTRIES = 4096
 
-const keptEntries = new Map<string, Record<string, unknown> | null>()
+const keptEntries = boundedMemo<string, Readonly<Record<string, unknown>> | null>(KEPT_LOG_ENTRIES)
 
 /**
  * `parseLogEntry` kept per line text, for logs read again every few seconds: a line read before is not parsed again,
  * also when a re-read hands it back as a new string. The entry is shared, so a caller must not change it. Past
  * `KEPT_LOG_ENTRIES` lines the store starts over.
  */
-export const keptLogEntry = (line: string): Record<string, unknown> | null => {
+export const keptLogEntry = (line: string): Readonly<Record<string, unknown>> | null => {
   const kept = keptEntries.get(line)
   if (kept !== undefined) return kept
-  const entry = parseLogEntry(line)
-  if (keptEntries.size >= KEPT_LOG_ENTRIES) keptEntries.clear()
-  keptEntries.set(line, entry)
-  return entry
+  return keptEntries.set(line, parseLogEntry(line))
 }

package/src/plan-format/phases.ts

@@ -12,19 +12,35 @@ export type DeferredItem = { text: string; target: string }
 /** An open checkbox whose phase arrow is not at the end of its line (1-based), with the form the parser reads. */
 export type MisplacedDeferral = { line: number; target: string; corrected: string }
 
+/** What the worktree did to a phase, against the base branch: its ticks differ (`touched`), and the base already carries a tick of it (`merged`): a run of it was merged. */
+export const PHASE_WORK = { touched: 'touched', merged: 'merged' } as const
+
+export type PhaseWork = (typeof PHASE_WORK)[keyof typeof PHASE_WORK]
+
+/** `work` with the flags it replaced, which published readers of `PlanPhase` and `PhaseProgress` may still read. */
+export type PhaseWorkFields = {
+  work: PhaseWork
+  /** @deprecated Read `work`: set exactly when `work` is. Removed in the next minor release. */
+  touched?: true
+  /** @deprecated Read `work === PHASE_WORK.merged`. Removed in the next minor release. */
+  merged?: true
+}
+
 /**
- * `touched` is set by the phase source when the worktree's ticks differ from the base branch's, `merged` beside it
- * when the base branch already carries a tick of the phase: a run of it was merged. `deferred` holds the checkboxes
- * moved to another phase; they are not among `items`, so they count neither as open nor as done.
+ * `work` is set by the phase source and says nothing for a phase the worktree left as the base has it; a merged phase
+ * is touched as well. `deferred` holds the checkboxes moved to another phase; they are not among `items`, so they
+ * count neither as open nor as done.
  */
 export type PlanPhase = {
   id: string
   title: string
   items: ChecklistItem[]
   deferred?: DeferredItem[]
-  touched?: true
-  merged?: true
-}
+} & Partial<PhaseWorkFields>
+
+/** The fields a phase's `work` sets, the deprecated `touched` and `merged` derived from it. */
+export const phaseWorkFields = (work: PhaseWork): PhaseWorkFields =>
+  work === PHASE_WORK.merged ? { work, touched: true, merged: true } : { work, touched: true }
 
 /** A phase heading with its 1-based line, the lower-case id and the title. */
 export type PhaseHeading = { line: number; id: string; title: string }

package/src/plan-format/progress.ts

@@ -1,8 +1,8 @@
 import { type PlanStep, phaseLabel, type SprintLane } from './lanes'
-import type { ChecklistItem, DeferredItem, PlanPhase } from './phases'
+import { type ChecklistItem, type DeferredItem, type PhaseWorkFields, type PlanPhase, phaseWorkFields } from './phases'
 
 /**
- * `title` is null when the sprint names a phase the plan does not have; `touched`, `merged` and `deferred` carry the
+ * `title` is null when the sprint names a phase the plan does not have; `work` and `deferred` carry the
  * plan phase's own, and the deferred checkboxes are in neither `done` nor `total`.
  */
 export type PhaseProgress = {
@@ -12,9 +12,7 @@ export type PhaseProgress = {
   total: number
   items: ChecklistItem[]
   deferred?: DeferredItem[]
-  touched?: true
-  merged?: true
-}
+} & Partial<PhaseWorkFields>
 
 export type StepProgress = { step: PlanStep; phases: PhaseProgress[] }
 
@@ -49,8 +47,7 @@ export const phaseProgress = (phases: readonly PlanPhase[], id: string): PhasePr
     total: items.length,
     items,
     ...(phase?.deferred ? { deferred: phase.deferred } : {}),
-    ...(phase?.touched ? { touched: true as const } : {}),
-    ...(phase?.merged ? { merged: true as const } : {}),
+    ...(phase?.work ? phaseWorkFields(phase.work) : {}),
   }
 }
 
@@ -75,7 +72,7 @@ const newestWrittenStepIndex = (steps: readonly StepProgress[]): number =>
 const newestRowIndex = (steps: readonly StepProgress[]): number =>
   steps.reduce((last, { step }, index) => (step.withoutRow ? last : index), -1)
 
-const isTouched = (phase: PhaseProgress): boolean => phase.touched === true && isWritten(phase)
+const isTouched = (phase: PhaseProgress): boolean => phase.work !== undefined && isWritten(phase)
 
 /**
  * A phase the lane ticked to the end in its worktree while the base branch does not carry those ticks yet: still

package/src/plans/command.ts

@@ -9,6 +9,7 @@ import { mainCheckout, worktreeRoot } from './git'
 import { fetchPullRequests } from './github'
 import { claimOwnTerminal, startExclusive } from './herd-claim'
 import { recallLanes, rememberLanes } from './herd-memory'
+import { publishedKey } from './herd-state'
 import { runLive } from './live'
 import { parseOptions } from './options'
 import { isSupervisedChild } from './restart-decision'
@@ -25,7 +26,11 @@ const printOnce = async (source: Source): Promise<void> => {
   const memories = recallLanes(source.root)
   const snapshot = await loadSnapshot(source, await fetchPullRequests(source.root), memories)
   rememberLanes(source.root, memories, snapshot.documents.laneOrder)
-  const screen = renderSnapshot(snapshot, startSelection(snapshot, source.options), snapshot.errors, paneWidth())
+  const screen = renderSnapshot(snapshot, {
+    selection: startSelection(snapshot, source.options),
+    errors: snapshot.errors,
+    width: paneWidth(),
+  })
   console.log(frameText(screen, Boolean(process.stdout.isTTY)))
 }
 
@@ -59,8 +64,10 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
     }
     const source: Source = { root, sprintFile: picked.file, options, settings, terminal, ...agentListOf(settings) }
     if (options.once || !process.stdout.isTTY) await printOnceWithNotice(source, picked.notice)
-    else if (isSupervisedChild(process.env)) await startExclusive(claimOwnTerminal, () => runLive(source))
-    else process.exit(await superviseView(args, await startedKit()))
+    else if (isSupervisedChild(process.env)) {
+      const kit = await startedKit()
+      await startExclusive(claimOwnTerminal, () => runLive(source, kit && publishedKey(source, kit)))
+    } else process.exit(await superviseView(args, await startedKit()))
     return 0
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error))

package/src/plans/current-task.ts

@@ -1,5 +1,6 @@
 import { keptLogEntry } from '../context/session-log'
 import type { PlanPhase } from '../plan-format'
+import { boundedMemo } from '../shared/bounded-memo'
 import { isRecord } from '../shared/is-record'
 
 /**
@@ -67,16 +68,11 @@ const wordsOf = (text: string): Set<string> => new Set(text.toLowerCase().match(
 /** How many task texts keep their words: every open task of the plans a herd shows, a few thousand at most. */
 const KEPT_TASK_WORDS = 8192
 
-const taskWords = new Map<string, string[]>()
+const taskWords = boundedMemo<string, string[]>(KEPT_TASK_WORDS)
 
 /** The distinctive words of a task's text (its first `TASK_TEXT_LENGTH` characters), kept per text across refreshes. */
 const taskWordsOf = (text: string): string[] => {
-  const kept = taskWords.get(text)
-  if (kept) return kept
-  const words = [...wordsOf(text.slice(0, TASK_TEXT_LENGTH))]
-  if (taskWords.size >= KEPT_TASK_WORDS) taskWords.clear()
-  taskWords.set(text, words)
-  return words
+  return taskWords.get(text) ?? taskWords.set(text, [...wordsOf(text.slice(0, TASK_TEXT_LENGTH))])
 }
 
 /**

package/src/plans/focus-overlay.ts

@@ -0,0 +1,80 @@
+import { fit, paint } from '../terminal/text'
+import { type AgentOf, clickHint } from './click-hint'
+import type { Screen } from './layout'
+import { blockRowByKey, boldBracketAt, type FocusHit, focusLine, isFocused, LINKS_KEY_PREFIX } from './row-focus'
+import type { Selection } from './selection'
+import { TEXTS } from './texts'
+
+const NO_ROW = '\0'
+const LEAD = /^ */
+
+/** A selection that focuses no row: the screen drawn with it is the base `focusedScreen` lays the focus on. */
+export const unfocused = (selection: Selection): Selection => ({
+  ...selection,
+  selected: NO_ROW,
+  hovered: null,
+  hoveredFrom: null,
+})
+
+/** The blanks a block puts before a row it holds (`indented`): the focus lies right of them, as narrow as the row. */
+const leadOf = (line: string): number => LEAD.exec(line)?.[0].length ?? 0
+
+/** `lines` with the lines of `hit` (counted from `offset`) changed by `change`, the first line told by its index. */
+const changedHit = (
+  lines: readonly string[],
+  offset: number,
+  hit: FocusHit | undefined,
+  change: (line: string, index: number) => string,
+): string[] =>
+  lines.map((line, at) => {
+    const index = hit ? at + offset - hit.line : -1
+    return hit && index >= 0 && index < hit.lines ? change(line, index) : line
+  })
+
+/**
+ * `screen` with the focus `state` gives laid on one region of `lines`: the focused row on the focus background and
+ * mark, a line of links under the mouse marked alone, and the square-bracket button under the mouse bold.
+ */
+const focusedLines = (lines: readonly string[], offset: number, screen: Screen, state: Selection, width: number) => {
+  const hitOf = (key: string | null | undefined) => (key ? screen.focusHits.find((hit) => hit.key === key) : undefined)
+  const hovered = hitOf(state.hovered)
+  const focusedKey = state.selected !== null && isFocused(state, state.selected) ? state.selected : null
+  const focusedHit = hitOf(focusedKey)
+  const gutter = focusedHit ? leadOf(lines[focusedHit.line - offset] ?? '') : 0
+  const focused = changedHit(
+    lines,
+    offset,
+    focusedHit,
+    (line, index) => `${line.slice(0, gutter)}${focusLine(line.slice(gutter), width - gutter, index === 0)}`,
+  )
+  const links = state.hovered?.startsWith(LINKS_KEY_PREFIX)
+    ? changedHit(focused, offset, hovered, (line, index) => (index === 0 ? focusLine(line, width, true) : line))
+    : focused
+  const from = state.hoveredFrom
+  return from == null
+    ? links
+    : changedHit(links, offset, hovered, (line, index) => (index === 0 ? boldBracketAt(line, from) : line))
+}
+
+/**
+ * The screen a full drawing with `state` gives, laid on `plain` (drawn with `unfocused`) without a new layout: a hover
+ * only moves the focus. Null where it needs the layout: with the help open, or for a row of the blocks on top, whose
+ * buttons stand only at the selection. `agentOf` says a lane's agent, for the footer's click hint.
+ */
+export const focusedScreen = (plain: Screen, state: Selection, width: number, agentOf: AgentOf): Screen | null => {
+  const blocks = [plain.yourTurnBlock, plain.sourceBlock]
+  const isBlockRow = (key: string | null | undefined) => !!key && blockRowByKey(blocks, key) !== null
+  if (state.showLegend || isBlockRow(state.selected) || isBlockRow(state.hovered)) return null
+  const header = focusedLines(plain.header, 0, plain, state, width)
+  const lines = focusedLines(plain.body.lines, plain.header.length, plain, state, width)
+  const selectedHit = plain.focusHits.find(({ key }) => key === state.selected)
+  const cursorLine =
+    selectedHit && selectedHit.line >= plain.header.length ? selectedHit.line - plain.header.length : -1
+  const hint = clickHint(state, (key) => blockRowByKey(blocks, key), agentOf) ?? TEXTS.hint
+  return {
+    ...plain,
+    header,
+    body: { ...plain.body, lines, cursorLine },
+    footer: [...plain.footer.slice(0, -1), fit(paint.dim(hint), width)],
+  }
+}

package/src/plans/git.ts

@@ -1,9 +1,8 @@
 import { existsSync, readdirSync, statSync } from 'node:fs'
 import { dirname } from 'node:path'
-import type { LaneStatus } from './layout'
 import { createProcessSlots } from './process-slots'
 import type { BaseRefInfo } from './sprint-page'
-import type { BranchStatus } from './status-pace'
+import type { BranchStatus, WorktreeStatus } from './status-pace'
 
 /** How many git processes the herd's reads keep in flight; more end together and hold the event loop as one block. */
 const GIT_PROCESSES = 6
@@ -176,33 +175,29 @@ export const branchStatusOf = (output: string | null): BranchStatus => {
   }
 }
 
-/** Reads branch and changed files of a worktree; its git process starts after `pass`. */
-export type BranchStatusReader = (worktree: string, pass: () => Promise<void>) => Promise<BranchStatus>
-
 /**
  * Branch and changed files of a worktree from `git status`, the dearest of the herd's git calls in a large checkout.
  * Without optional locks: the herd never rewrites the index, which would take the lock an agent's git needs and move
  * the index the worktree's stamp watches (`worktreeStamp`).
  */
-export const branchStatusAt: BranchStatusReader = async (worktree, pass) =>
+const branchStatusAt = async (worktree: string, pass: () => Promise<void>): Promise<BranchStatus> =>
   branchStatusOf(await gitAsync(worktree, ['--no-optional-locks', 'status', '--porcelain=v2', '--branch'], pass))
 
 /**
  * Branch, commits ahead of `baseRef` and changed files of a worktree; null and 0 when it does not exist. The two
  * git calls run side by side and without holding the event loop, so a key pressed meanwhile is answered at once;
- * each starts after `pass` (a `SliceGate`), so the starts of many worktrees' calls do not add up to one block.
- * `readBranchStatus` may answer from what it kept instead of asking git (`pacedStatus`).
+ * each starts after `pass` (a `SliceGate`), so the starts of many worktrees' calls do not add up to one block. The
+ * herd keeps the answer while nothing moved (`pacedStatus`).
  */
 export const gitStatusOf = async (
   worktree: string,
   baseRef: string,
   pass: () => Promise<void> = passAtOnce,
-  readBranchStatus: BranchStatusReader = branchStatusAt,
-): Promise<Pick<LaneStatus, 'branch' | 'ahead' | 'dirty'>> => {
+): Promise<WorktreeStatus> => {
   if (!existsSync(worktree)) return { branch: null, ahead: null, dirty: 0 }
   const [count, status] = await Promise.all([
     gitAsync(worktree, ['rev-list', '--count', `${baseRef}..HEAD`], pass),
-    readBranchStatus(worktree, pass),
+    branchStatusAt(worktree, pass),
   ])
   const ahead = Number.parseInt(count ?? '', 10)
   return { ...status, ahead: Number.isNaN(ahead) ? null : ahead }