jackherd 1.15.1 → 1.16.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 What changed for people who use jackherd, newest first.
 
+## 1.16.0
+
+- **Sources of your own.** A source that belongs to you alone, such as your calendar, goes into `~/.jackherd/sources.json` instead of the repository's config: same shape as `watch.sources`. Its command runs in `~/.jackherd/`, not in the repository, in every repository where you start the watcher, and for nobody else. The watcher, the herd and `jh watch source <name> --dry-run` take it up after the repository's sources. If the repository has a source of the same name, the repository's wins and yours is skipped with a note. A broken personal file never stops the watcher. The file has a JSON schema, `schemas/sources.schema.json`.
+- **Secrets in the keychain: `jh secret`.** A source lists the variables it needs in its `"secrets"` field. `jh secret set <NAME>` asks for the value hidden, from a terminal only, and keeps it in the system keychain; `jh secret list` shows which names your sources need and whether each is set, never a value; `jh secret delete <NAME>` removes one. A repository source, which anyone with a commit can change, gets only the watcher's environment, never a keychain value. A value reaches the environment of its source's command and nowhere else: no argument, output, state or log. A missing one fails the run with `secret missing: <NAME>` before the command starts.
+- **Sources change without a restart.** The watcher reads the repository's config and your personal file again when one of them changed; a new source runs at once, a removed one stops. A changed file that does not read keeps the sources as they were and says so once. The herd takes the sources from the running watcher, so a new one shows there too without restarting either.
+- **Entries in a block of their own.** `"show": "entries"` opens a source's entries in a block under "Your turn", headed by its label, in its colour and linked where an entry has an address. Together such blocks show at most five rows, at least one per block, and `+<n>` opens the rest of a block. The source's status stays in the `Sources` line.
+- **`/jh-follow` asks where a source belongs.** It asks whether the source is yours or the repository's and writes exactly that file. For a personal source with a secret, you set the value with `jh secret set` in a terminal of your own; the skill then checks it with `jh secret list` and dry-runs the source by name.
+- **A recipe for today's appointments.** The Google Calendar recipe shows the day's appointments of one or more calendars from their secret iCal addresses, kept in the keychain, recurring events included, each linked to the calendar's day view. No Google login and no API project. A failed request prints nothing of the address.
+- **`[done]` hides its row at once.** A click on `[done]` in "Your turn" removes the row right away instead of at the next read; if the write fails, the row stays and the footer says why.
+- **A cut activity line opens on a click.** The `↳` line of a working lane or subagent that did not fit unfolds when you click it.
+- **The merge guard says why it asks.** An approved merge passes without a question only as a plain `gh pr merge <n>` standing alone. When it asks anyway, the question now says why: run a chained or piped merge alone, and a merge with other flags is let through only in its plain form.
+
+## 1.15.2
+
+- **The installer no longer crashes on macOS.** `install.sh` redirected `jh init --global` from `/dev/tty`, which the macOS kqueue that Bun reads input through rejects (`EINVAL: invalid argument, kqueue`) at the first question. It now names the terminal's own device (such as `/dev/ttys003`) first, through `tty` on its input or, since macOS prints `/dev/tty` for `tty </dev/tty`, through `ps`, and reads from that.
+- **An unreadable terminal takes the default.** If the terminal cannot be read during a question, `jh init` prints one note on stderr and takes the default answer instead of stopping with an error.
+
+- **The herd recognises an older herd on macOS.** The herd view found out whether an earlier view of the same terminal was still running by reading `/proc`, which macOS does not have, so it never took one over and two herds could draw into one terminal. It now asks `ps` there and keeps `/proc` on Linux.
+- **Copying env files into a lane works on macOS.** The copy command in the lane setup used `cp --parents` and `grep -z`, which only the GNU tools know. It now uses `git ls-files` with an exclude pattern and `tar`, which keep folders and file modes (an env file stays `600`) with the tools of both systems. Run `jh sync` to get the new text.
+- **Every `ps` call is bounded.** A `ps` that hangs no longer holds up the herd or the watcher.
+- **The installer refuses a bun under a relative `PATH` entry on macOS too.** `install.sh` asked `command -v` for the path, which bash 3.2 (macOS `/bin/sh`) answers with an absolute path even for a relative entry, so the refusal never fired. It now walks `PATH` itself and names the entry as written.
+
 ## 1.15.1
 
 - **A test with a variable no longer asks.** The merge guard read the `[` of `[ -f $P ]` as a glob program, so any variable after it could be `gh pr merge` and the guard asked, also for a plain grep. `[` and `[[` now count as the test builtin; a merge after a test, and a program from a variable, still ask.

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.15.1/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.16.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)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.15.1/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.16.0/assets/icons/space.svg">
 
 # Jack herds your coding agents.
 
@@ -15,31 +15,31 @@ 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.15.1/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.16.0/assets/icons/space.svg">
 
 <p>
-<img src="https://unpkg.com/jackherd@1.15.1/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.16.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.15.1/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.16.0/assets/icons/space.svg">
 </p>
 
-<p><img src="https://unpkg.com/jackherd@1.15.1/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.16.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.15.1/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.</p>
+<p><img src="https://unpkg.com/jackherd@1.16.0/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.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.15.1/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.16.0/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.15.1/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.16.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.15.1/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.16.0/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.15.1/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.16.0/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.15.1/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.15.1/assets/icons/space.svg"></p>
+<p><img src="https://unpkg.com/jackherd@1.16.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.16.0/assets/icons/space.svg"></p>
 
 ## Quickstart
 
-1. **Install** (Linux and macOS; needs Claude Code and git). → [INSTALL.md](https://unpkg.com/jackherd/INSTALL.md)
+1. **Install** (needs Claude Code and git). → [INSTALL.md](https://unpkg.com/jackherd/INSTALL.md)
 
    ```bash
    curl -fsSL https://unpkg.com/jackherd/install.sh | sh
@@ -71,22 +71,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.15.1/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.16.0/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.15.1/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.16.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: 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.15.1/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.16.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.15.1/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.16.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 |
 | --- | --- | --- |
@@ -121,7 +121,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.15.1/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.16.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 |
 | --- | --- |
@@ -203,7 +203,9 @@ How the herd reads the board:
 
 Jack doesn't watch the terminals himself. `jh watch`, which he starts, wakes him when a lane is blocked or done, a check turns red, a pull request gets feedback, a lane's context fills up, a lane waits for an approval or works for ten minutes without reporting its task; deploys and previews too, when configured.
 
-`/jh-follow PROJ-123` adds anything a command can print as JSON: a ticket, an issue, error logs, a status page. It checks the tool and its login, shows you a dry run and writes the source to `watch.sources` after your yes. A token stays in the environment, read by a small Bun script, never in an argument. Each source runs on its own interval, kept across a restart of the watcher. Recipes for Jira, Linear, GitHub issues and Projects, Sentry and status pages come with it. The reports need herdr; a source can be set up and dry-run without it.
+`/jh-follow PROJ-123` adds anything a command can print as JSON: a ticket, an issue, error logs, a status page. It checks the tool and its login, shows you a dry run and writes the source to `watch.sources` after your yes. A token stays in the environment, read by a small Bun script, never in an argument. Each source runs on its own interval, kept across a restart of the watcher. Recipes for Jira, Linear, GitHub issues and Projects, Sentry, status pages and today's Google Calendar appointments come with it. The reports need herdr; a source can be set up and dry-run without it.
+
+A source that is yours alone, such as your calendar, goes into `~/.jackherd/sources.json` instead: it runs in every repository where you start the watcher, and for nobody else. Its secrets live in the system keychain: `jh secret set <NAME>` asks for the value hidden, and only the command of the source that lists it receives it. The watcher takes up a changed source without a restart, and any source can show its entries in a block of their own under Your turn with `"show": "entries"`.
 
 </details>
 
@@ -225,6 +227,7 @@ Each phase in the plan names its model: the planning model (Opus by default) whe
 | `jh check` | types, lint and tests of what you touched, plus the plan and board checks (`--skip-slow`, `--parallel <plan>`) |
 | `jh herd` | the live view (`--once`, `--lane <name>`) |
 | `jh watch` | the watcher Jack runs |
+| `jh secret` | keeps a personal source's secrets in the system keychain (`set <NAME>`, `list`, `delete <NAME>`); `list` shows which are set, never a value |
 | `jh lane prompt <lane>` | writes a lane's first prompt from its board row and its plan (`--out`, `--handover`); your additions below the marker line at its end stay |
 | `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. Claude Code asks before each call |
 | `jh preview <file>` | renders a Markdown file through the GitHub API into a preview in GitHub and npm style |

package/dist/{chunk-V4HOLGFP.js → chunk-4LUFR7RC.js}

@@ -160,6 +160,23 @@ var classifyStatus = (language, statusText) => {
 var phaseHeading = (language, id, title) => `### ${PLAN_VOCABULARY[language].phase} ${id}: ${title}`;
 var sectionHeading = (language, section) => `## ${PLAN_VOCABULARY[language].sections[section]}`;
 
+// src/plan-format/terminal-text.ts
+var UNSAFE_RANGES = [
+  [0, 31],
+  [127, 159],
+  [1564, 1564],
+  [8206, 8207],
+  [8232, 8233],
+  [8234, 8238],
+  [8294, 8297]
+];
+var escapeCodePoint = (codePoint) => `\\u${codePoint.toString(16).padStart(4, "0")}`;
+var UNSAFE_TERMINAL_TEXT = new RegExp(
+  `[${UNSAFE_RANGES.map(([from, to]) => `${escapeCodePoint(from)}-${escapeCodePoint(to)}`).join("")}]`,
+  "g"
+);
+var terminalSafe = (text) => text.replace(UNSAFE_TERMINAL_TEXT, "");
+
 export {
   PLAN_LANGUAGE,
   LANGUAGE_NAME,
@@ -177,5 +194,6 @@ export {
   PLAN_VOCABULARY,
   classifyStatus,
   phaseHeading,
-  sectionHeading
+  sectionHeading,
+  terminalSafe
 };

package/dist/config.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 
 declare const renderConfigJsonSchema: () => string;
+declare const renderSourcesJsonSchema: () => string;
 
 declare const TERMINAL_ADAPTER: {
     readonly none: "none";
@@ -72,6 +73,8 @@ declare const sourceSchema: z.ZodObject<{
         magenta: "magenta";
     }>>;
     reportOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    show: z.ZodOptional<z.ZodLiteral<"entries">>;
 }, z.core.$strict>;
 declare const jackherdConfigSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
@@ -113,9 +116,9 @@ declare const jackherdConfigSchema: z.ZodObject<{
         lockFile: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     models: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+        review: "review";
         plan: "plan";
         implement: "implement";
-        review: "review";
         explore: "explore";
         orchestrate: "orchestrate";
     }>, z.ZodString>>;
@@ -249,6 +252,8 @@ declare const jackherdConfigSchema: z.ZodObject<{
                 magenta: "magenta";
             }>>;
             reportOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            show: z.ZodOptional<z.ZodLiteral<"entries">>;
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
     guard: z.ZodPrefault<z.ZodPipe<z.ZodObject<{
@@ -338,7 +343,47 @@ type JackherdConfig = z.infer<typeof jackherdConfigSchema>;
 declare const parseJackherdConfig: (raw: unknown) => JackherdConfig;
 /** `parseJackherdConfig` for a file: an invalid one throws with `label` (its path) and the issues in words. */
 declare const parseConfigFile: (raw: unknown, label: string) => JackherdConfig;
+/** The personal sources file (`~/.jackherd/sources.json`): the same entries as `watch.sources`. */
+declare const personalSourcesSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    sources: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        command: z.ZodArray<z.ZodString>;
+        every: z.ZodDefault<z.ZodNumber>;
+        items: z.ZodOptional<z.ZodString>;
+        map: z.ZodObject<{
+            id: z.ZodString;
+            updatedAt: z.ZodOptional<z.ZodString>;
+            title: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodString>;
+            body: z.ZodOptional<z.ZodString>;
+            author: z.ZodOptional<z.ZodString>;
+            status: z.ZodOptional<z.ZodString>;
+            count: z.ZodOptional<z.ZodString>;
+        }, z.core.$catchall<z.ZodString>>;
+        ignoreAuthors: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        reportLimit: z.ZodDefault<z.ZodNumber>;
+        label: z.ZodOptional<z.ZodString>;
+        lane: z.ZodOptional<z.ZodString>;
+        ticket: z.ZodOptional<z.ZodBoolean>;
+        tone: z.ZodOptional<z.ZodEnum<{
+            amber: "amber";
+            teal: "teal";
+            grey: "grey";
+            red: "red";
+            green: "green";
+            blue: "blue";
+            magenta: "magenta";
+        }>>;
+        reportOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        show: z.ZodOptional<z.ZodLiteral<"entries">>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+type PersonalSourcesFile = z.infer<typeof personalSourcesSchema>;
+/** The personal sources file as read from JSON; invalid throws with `label` (its path) and the issues in words. */
+declare const parsePersonalSourcesFile: (raw: unknown, label: string) => PersonalSourcesFile;
 /** One `watch.sources` entry outside the config, such as a draft to try; invalid throws with `label` and the issues. */
 declare const parseSourceDraft: (raw: unknown, label: string) => z.infer<typeof sourceSchema>;
 
-export { COMMAND_KEYS, type CommandKey, DEFAULT_CONTEXT_WINDOW, DEFAULT_MODELS, DEFAULT_SKILL_PREFIX, type JackherdConfig, KIT_CORE, MODEL_ROLE, type ModelRole, SKILL_PREFIX, TERMINAL_ADAPTER, type TerminalAdapter, isModelRole, isTerminalAdapter, jackherdConfigSchema, parseConfigFile, parseJackherdConfig, parseSourceDraft, renderConfigJsonSchema };
+export { COMMAND_KEYS, type CommandKey, DEFAULT_CONTEXT_WINDOW, DEFAULT_MODELS, DEFAULT_SKILL_PREFIX, type JackherdConfig, KIT_CORE, MODEL_ROLE, type ModelRole, type PersonalSourcesFile, SKILL_PREFIX, TERMINAL_ADAPTER, type TerminalAdapter, isModelRole, isTerminalAdapter, jackherdConfigSchema, parseConfigFile, parseJackherdConfig, parsePersonalSourcesFile, parseSourceDraft, personalSourcesSchema, renderConfigJsonSchema, renderSourcesJsonSchema };

package/dist/config.js

@@ -1,7 +1,7 @@
 import {
   PLAN_LANGUAGE,
   RESPONSE_ADDRESS
-} from "./chunk-V4HOLGFP.js";
+} from "./chunk-4LUFR7RC.js";
 
 // src/config/json-schema.ts
 import { z as z3 } from "zod";
@@ -112,6 +112,15 @@ var SKILL_PATH = new RegExp(`^${SKILLS_DIRECTORY}/([^/]+)/(.+)$`);
 var AGENT_PATH = new RegExp(`^${AGENTS_DIRECTORY}/([^/]+)\\.md$`);
 var claudePath = (...segments) => [CLAUDE_DIRECTORY, ...segments].join("/");
 
+// src/version/release.ts
+var CLI_NAME = "jh";
+
+// src/secrets/options.ts
+var SECRET_NAME = /^[A-Z][A-Z0-9_]*$/;
+var SECRET_USAGE = `Usage: ${CLI_NAME} secret set <NAME>     store a value in the keychain, typed hidden in a terminal
+       ${CLI_NAME} secret list           the names the sources need, set or missing, never a value
+       ${CLI_NAME} secret delete <NAME>  remove the value from the keychain`;
+
 // src/watch/source-fields.ts
 var SOURCE_FIELD = {
   id: "id",
@@ -141,6 +150,38 @@ var pathSteps = (path) => {
 };
 var isSourcePath = (path) => pathSteps(path) !== null;
 
+// src/watch/sources.ts
+import { createHash } from "crypto";
+
+// src/watch/feedback-item.ts
+var FEEDBACK_FORM = { review: "review", inline: "inline", comment: "comment" };
+
+// src/watch/no-finding.ts
+var ROUND_WINDOW_MS = 5 * 6e4;
+
+// src/watch/pull-requests.ts
+var WATCHED_PULL_REQUEST_FIELDS = "number,title,url,headRefName,isDraft,state,headRefOid,mergeCommit";
+var OPEN_PULL_REQUEST_FIELDS = `${WATCHED_PULL_REQUEST_FIELDS},statusCheckRollup,files`;
+
+// src/watch/feedback.ts
+var REVIEW_STATE = {
+  approved: "APPROVED",
+  changesRequested: "CHANGES_REQUESTED",
+  commented: "COMMENTED",
+  dismissed: "DISMISSED"
+};
+var DECISIVE_REVIEW_STATES = [
+  REVIEW_STATE.approved,
+  REVIEW_STATE.changesRequested,
+  REVIEW_STATE.dismissed
+];
+
+// src/watch/previews.ts
+var PREVIEW_SOURCE = { deployment: "deployment", comment: FEEDBACK_FORM.comment };
+
+// src/watch/sources.ts
+var SOURCE_SHOW = { entries: "entries" };
+
 // src/watch/watch-defaults.ts
 var CLEAN_REVIEW_TEXT = "## Code review\n\nNo issues found. Checked for bugs and CLAUDE.md compliance.";
 var BUN_FAILED_TEST_PATTERN = "^\\(fail\\) (.+?)(?: \\[[\\d.]+m?s\\])?$";
@@ -434,13 +475,23 @@ var sourceSchema = z2.strictObject({
    * The mapped fields whose change reports, with the old and the new value, in place of the content of `title`,
    * `author`, `body` and `url`; without it a change of that content reports.
    */
-  reportOn: z2.array(z2.string().min(1)).min(1).max(10).optional()
+  reportOn: z2.array(z2.string().min(1)).min(1).max(10).optional(),
+  /**
+   * Names of secrets the command needs, handed to it as environment variables of the same name; each is looked up
+   * in the keychain, then in the watcher's environment.
+   */
+  secrets: z2.array(z2.string().regex(SECRET_NAME, "capital letters, digits and `_`, starting with a letter")).max(10).refine((names) => new Set(names).size === names.length, "secret names must be unique").optional(),
+  /** `entries` shows the source's entries open, in a herd block of its own; not for a ticket source, whose entries are badges. */
+  show: z2.literal(SOURCE_SHOW.entries).optional()
 }).refine(canChange, {
   message: "map needs updatedAt, a content field (title, author, body, url) or reportOn",
   path: ["map"]
 }).refine((source) => source.ignoreAuthors.length === 0 || source.map.author !== void 0, {
   message: "ignoreAuthors needs map.author",
   path: ["ignoreAuthors"]
+}).refine((source) => source.show === void 0 || source.ticket !== true, {
+  message: "show cannot be set on a ticket source",
+  path: ["show"]
 }).refine((source) => !source.reportOn?.includes(SOURCE_FIELD.id), {
   message: "reportOn cannot name id",
   path: ["reportOn"]
@@ -648,11 +699,18 @@ ${z2.prettifyError(parsed.error)}`);
   return parsed.data;
 };
 var parseConfigFile = (raw, label) => parseLabelled(jackherdConfigSchema, raw, label);
+var personalSourcesSchema = z2.strictObject({
+  $schema: z2.string().optional(),
+  sources: z2.array(sourceSchema).refine(hasUniqueNames, "source names must be unique").default([])
+});
+var parsePersonalSourcesFile = (raw, label) => parseLabelled(personalSourcesSchema, raw, label);
 var parseSourceDraft = (raw, label) => parseLabelled(sourceSchema, raw, label);
 
 // src/config/json-schema.ts
-var renderConfigJsonSchema = () => `${JSON.stringify(z3.toJSONSchema(jackherdConfigSchema, { io: "input" }), null, 2)}
+var renderJsonSchema = (schema) => `${JSON.stringify(z3.toJSONSchema(schema, { io: "input" }), null, 2)}
 `;
+var renderConfigJsonSchema = () => renderJsonSchema(jackherdConfigSchema);
+var renderSourcesJsonSchema = () => renderJsonSchema(personalSourcesSchema);
 export {
   COMMAND_KEYS,
   DEFAULT_CONTEXT_WINDOW,
@@ -667,6 +725,9 @@ export {
   jackherdConfigSchema,
   parseConfigFile,
   parseJackherdConfig,
+  parsePersonalSourcesFile,
   parseSourceDraft,
-  renderConfigJsonSchema
+  personalSourcesSchema,
+  renderConfigJsonSchema,
+  renderSourcesJsonSchema
 };

package/dist/plan-format.js

@@ -15,29 +15,13 @@ import {
   classifyStatus,
   isPlanLanguage,
   phaseHeading,
-  sectionHeading
-} from "./chunk-V4HOLGFP.js";
+  sectionHeading,
+  terminalSafe
+} from "./chunk-4LUFR7RC.js";
 
 // src/plan-format/lanes.ts
 import { posix } from "path";
 
-// src/plan-format/terminal-text.ts
-var UNSAFE_RANGES = [
-  [0, 31],
-  [127, 159],
-  [1564, 1564],
-  [8206, 8207],
-  [8232, 8233],
-  [8234, 8238],
-  [8294, 8297]
-];
-var escapeCodePoint = (codePoint) => `\\u${codePoint.toString(16).padStart(4, "0")}`;
-var UNSAFE_TERMINAL_TEXT = new RegExp(
-  `[${UNSAFE_RANGES.map(([from, to]) => `${escapeCodePoint(from)}-${escapeCodePoint(to)}`).join("")}]`,
-  "g"
-);
-var terminalSafe = (text) => text.replace(UNSAFE_TERMINAL_TEXT, "");
-
 // src/plan-format/markdown.ts
 var SECTION_END = /^##\s/;
 var TABLE_SEPARATOR = /^\|[\s|:-]+\|$/;

package/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.15.1"
+version = "1.16.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,11 +9,14 @@ 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.15.1}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.16.0}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.
 JACKHERD_TEST_TTY="${JACKHERD_TEST_TTY:-/dev/tty}"
+# Test seam: a packed tarball (absolute path) installed instead of the published package, so CI can prove a build
+# before it is released. Unset in every real run.
+JACKHERD_TEST_PACKAGE="${JACKHERD_TEST_PACKAGE:-}"
 BUN_INSTALLER_URL='https://bun.com/install'
 BUN_MIN_MAJOR=1
 BUN_MIN_MINOR=3
@@ -55,10 +58,29 @@ bun_bin_dir() {
   printf '%s/bin\n' "${BUN_INSTALL:-$HOME/.bun}"
 }
 
+# The first executable bun along PATH, spelled the way PATH names it. Walked here and not asked of
+# 'command -v', which some shells (bash 3.2 as sh on macOS) answer with an absolute path even for a
+# relative entry, so the check for a relative one in main would never fire. An empty entry means the
+# current directory and counts as relative.
+bun_on_path() {
+  rest="$PATH:"
+  while [ -n "$rest" ]; do
+    entry=${rest%%:*}
+    rest=${rest#*:}
+    [ -n "$entry" ] || entry=.
+    if [ -f "$entry/bun" ] && [ -x "$entry/bun" ]; then
+      printf '%s/bun\n' "$entry"
+      return 0
+    fi
+  done
+  return 1
+}
+
 # The bun on PATH, else the one the official installer leaves in ~/.bun/bin; empty when there is none.
 find_bun() {
-  if command -v bun >/dev/null 2>&1; then
-    command -v bun
+  found=$(bun_on_path) || found=''
+  if [ -n "$found" ]; then
+    printf '%s\n' "$found"
   elif [ -x "$(bun_bin_dir)/bun" ]; then
     printf '%s\n' "$(bun_bin_dir)/bun"
   fi
@@ -111,10 +133,32 @@ terminal_available() {
   (: <"$JACKHERD_TEST_TTY") 2>/dev/null
 }
 
+# The controlling terminal's own device node, else the path as given. macOS kqueue, which Bun reads stdin through,
+# rejects /dev/tty with EINVAL but accepts the real device (/dev/ttys003). On macOS 'tty </dev/tty' prints
+# /dev/tty itself, so the device comes from 'tty' on the inherited stdin when that is a terminal, else from the
+# shell's own TTY column of 'ps' (ttys003 on macOS, pts/3 on Linux; ? or ?? when there is none).
+terminal_device() {
+  device=$(tty 2>/dev/null) || device=''
+  if [ "$device" = /dev/tty ] || [ ! -c "$device" ]; then
+    name=$(ps -o tty= -p $$ 2>/dev/null) || name=''
+    # shellcheck disable=SC2086 # word splitting trims the padding ps puts around the column
+    set -- $name
+    case ${1:-} in
+      '' | '?' | '??') device='' ;;
+      *) device="/dev/$1" ;;
+    esac
+  fi
+  if [ -c "$device" ] && [ "$device" != /dev/tty ]; then
+    printf '%s\n' "$device"
+  else
+    printf '%s\n' "$JACKHERD_TEST_TTY"
+  fi
+}
+
 run_setup() {
   if terminal_available; then
     say "starting the setup: jh init --global"
-    "$1" init --global <"$JACKHERD_TEST_TTY" || fail "jh init --global failed"
+    "$1" init --global <"$(terminal_device)" || fail "jh init --global failed"
   else
     say "no terminal to ask questions on, setting up with the defaults: jh init --global --yes"
     "$1" init --global --yes </dev/null || fail "jh init --global --yes failed"
@@ -145,6 +189,7 @@ main() {
   export PATH
 
   spec="$JACKHERD_PACKAGE@$JACKHERD_VERSION"
+  [ -z "$JACKHERD_TEST_PACKAGE" ] || spec="$JACKHERD_TEST_PACKAGE"
   say "installing $spec: bun add -g --ignore-scripts $spec"
   "$bun" add -g --ignore-scripts "$spec" || fail "bun add -g failed"
 

package/kit/hooks/hooks/merge-guard/decision.ts

@@ -46,7 +46,8 @@ export type GuardPolicy = {
  * A guarded command the script runs or could run, and the pull request a merge names, when it names one plainly; or
  * the shell alias or function that may run one (`definition`, whose name is then the `command`).
  */
-type Finding = { command: string; merge: PlainMerge | undefined; definition?: ShellDefinitionHit }
+/** A guarded command found in the script; `sole` where it was the one command of the call, read as written by `gh`. */
+type Finding = { command: string; merge: PlainMerge | undefined; definition?: ShellDefinitionHit; sole?: boolean }
 
 /** What the search looks for: the guarded commands, and the shell definitions that may stand for one of them. */
 type Search = { commands: readonly string[]; definitions: () => ShellDefinitions }
@@ -326,7 +327,7 @@ const findingOf = (command: string, words: SimpleCommand, index: number, sole: b
   if (!namesCommandWords(words, index, command) || isReading(words, index, command)) return undefined
   if (!isGuardedUse(command, words, index)) return undefined
   const plain = sole && words[index].literal && words[index].value === GH
-  return { command, merge: plain ? plainMerge(words.slice(index), commandWords(command)) : undefined }
+  return { command, sole: plain, merge: plain ? plainMerge(words.slice(index), commandWords(command)) : undefined }
 }
 
 const programsOf = (commands: readonly string[]): string[] => [
@@ -447,6 +448,19 @@ const guardedListSentence = (commands: string[]): string[] =>
         `${commands.map((command) => `\`${command}\``).join(' and ')} is on the project's guarded list (guard.commands in .jackherd/config.json), so the user confirms it.`,
       ]
 
+const SOLE_MERGE_SENTENCE = `A \`${MERGE_COMMAND}\` is checked against the approval and the checks only as a plain \`${MERGE_COMMAND} <number>\` that is the one command of its Bash call: no pipe, \`;\`, \`&&\`, wrapper or substitution around it. Run it alone, then read the result with \`gh pr view\`.`
+
+const PLAIN_MERGE_SENTENCE = `A \`${MERGE_COMMAND}\` is checked against the approval and the checks only in its plain form: the number, merge-method and delete-branch flags and at most one \`--match-head-commit <full sha>\`; any other flag or a word the shell expands is confirmed by the user.`
+
+/** Why an unchecked merge was not checked: it did not stand alone in its call, or it did but not in its plain form. */
+const soleMergeSentence = (findings: Finding[]): string[] => {
+  const unchecked = findings.filter(
+    ({ command, merge, definition }) => command === MERGE_COMMAND && merge === undefined && definition === undefined,
+  )
+  if (unchecked.some(({ sole }) => !sole)) return [SOLE_MERGE_SENTENCE]
+  return unchecked.length > 0 ? [PLAIN_MERGE_SENTENCE] : []
+}
+
 const askBecause = (findings: Finding[], notes: string[], script: string): MergeGuardDecision => {
   const guarded = findings.filter(({ definition }) => definition === undefined).map(({ command }) => command)
   const definitions = [
@@ -462,6 +476,7 @@ const askBecause = (findings: Finding[], notes: string[], script: string): Merge
         (definition) =>
           `${shellDefinitionHint(definition)} It may run a command of guard.commands in .jackherd/config.json, so the user confirms it.`,
       ),
+      ...soleMergeSentence(findings),
       ...notes,
       expandingHereDocumentAdvice(script),
     ]