pendingyou 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 0.18.0 (2026-10-05)
+
+- Presence says which terminal: in a Herdr pane (`HERDR_ENV=1` with `HERDR_BIN_PATH` and `HERDR_PANE_ID`), every
+  presence report (`POST /mcp/cli/presence`: each session's start, its 5-minute heartbeat and its end, for Claude Code,
+  Codex, OpenCode and Pi) also says where the session runs: `"terminal": { "app": "herdr", "paneId": "w2:p1", "server":
+  "<16 hex>" }`. `server` names the Herdr server without the path of its socket: the first 16 hex characters of a
+  SHA-256 of the computer's name and `HERDR_SOCKET_PATH`, left out when there's no socket path. Pending You keeps it with
+  the session and lists it with the agent's sessions running now, so the Pending You plugin for Herdr can go from a card
+  to its agent's pane. It goes whether or not the badges are on. Anywhere else a report is exactly as before, with no
+  `terminal`. A Pending You from before it refuses the field (400): the same report goes again without it.
+- This computer's key: Pending You knows a computer by a key, not by its name. The first time `init` (or `login`) signs
+  anything in, it makes a P-256 key pair in `~/.config/pendingyou/machine.json` (0600, in the 0700 folder with its
+  `.gitignore`), shared by every Pending You address. The private key never leaves the computer and is never printed or
+  logged; Pending You keeps only its public key's RFC 7638 thumbprint. One that can't be read is never replaced: `init`
+  says so and signs in without it.
+  - Every device sign-in it starts (`POST /oauth/device`) carries `machine_attestation`: a JWS the key signs (ES256,
+    `typ` `pendingyou-machine+jwt`, the public key in its header) for `<origin>/oauth/device`, the client signing in and
+    the computer's name, good for 5 minutes and once (`jti`). It's dated by Pending You's own clock (its answer's
+    `Date`), so a computer whose clock is off still proves its key. Whoever allows the sign-in enrolls the computer, and
+    the connections it makes belong to it. A client registered again (a forgotten one) gets a new attestation of its
+    own.
+  - On the next `init`, each agent already signed in proves the key with its own sign-in (`POST /mcp/cli/machine`,
+    `{ "attestation": … }` for `<origin>/mcp/cli/machine`): nothing to approve and no new sign-in, and the agents'
+    sign-ins stay exactly as they were. That's how a computer set up before 0.18.0 gets its key; until then its hooks
+    keep running the copy `init` installed, and nothing changes on it. A Pending You from before machines answers 404,
+    taken quietly.
+  - `pendingyou machine status` says whether Pending You knows each agent's connection by this key (from
+    `/mcp/cli/answers`' `for.machineKey`), and exits 0 only when it knows every one. `machine attest --client-id <id>`
+    (`--cnf <thumbprint>`, `--name`) prints an attestation for an app's own device sign-in, and nothing else.
+    `machine rotate` makes a new key, after a yes (`--yes`, or at the terminal).
+
+## 0.17.0 (2026-10-05)
+
+- Herdr: an agent running in a Herdr pane (`HERDR_ENV=1` with `HERDR_BIN_PATH` and `HERDR_PANE_ID`) marks its pane with
+  what it's waiting on you for, as display-only metadata (`src/herdr.ts`): `"$HERDR_BIN_PATH" pane report-metadata
+  "$HERDR_PANE_ID" --source pendingyou` with `py_app`, `py_agent` (the name the session goes by with Pending You),
+  `py_waiting` (how many cards wait on you), `py_card` (the most pressing one's title, redacted as permission cards' words
+  are and cut to 80 characters), `py_cards` (their request ids, as many as fit in 80 characters), `py_urgency`
+  (`blocking`, else `now`, `today` or `whenever`) and `py_asked` (those also asked in the conversation), and the state
+  labels `idle` and `done` read "waiting on you" while something waits (`--agent` keeps them to the pane's own agent).
+  Cleared when nothing waits and as the session ends. Herdr's program is run with an argument list, given one second,
+  its outcome never thrown, and a hook only starts it in the background; `--seq` (the moment, in milliseconds) keeps a
+  late write from winning, and `--ttl-ms 900000` lets tokens nobody repeats expire. Herdr's limits are kept: one source,
+  7 tokens a report, its token names, 80 characters a value.
+  - Claude Code: init's copy of the wake mod writes them whenever they change and every 5 minutes, through the hooks'
+    script (`herdr report --app claude-code`, the session's cards on stdin), learning how pressing each card is from
+    post_request and update_request; the session-start hook names the session in the background (from its transcript);
+    the SessionEnd hook clears them in the background.
+  - Codex: its card hook (`posted`) marks the thread as the pane's and writes them in the background; the thread's
+    keeper writes them with each live (it now starts in Herdr even without a connection here, and keeps on for them when
+    Pending You won't take its presence) and clears them as Codex quits; the listener writes them once a card is
+    answered.
+  - OpenCode and Pi: through what their plugin and extension already run: `posted` after each card call, `presence
+    --state live` (the heartbeat) and `closed`, and the listener. A pane's badges are every session of the app marked
+    there: OpenCode runs several in one pane.
+  - `<app>-threads.json` remembers each card's urgency, whether it blocks and whether it was asked in the conversation,
+    and the Herdr pane each session runs in; `herdr.json` whether the badges are off here.
+- `pendingyou herdr <what>`: the Pending You plugin for Herdr's commands (`src/herdr/`), which its manifest runs through
+  the hooks' script. `next` focuses the next pane waiting on you (blocking first, then by urgency); `open` is the popup
+  that lists them (Enter opens the card in Pending You through a terminal hyperlink, `t` takes you to the pane; `--demo`
+  shows made-up cards); `popup <pane>` opens one of the plugin's popups; `setup` checks Herdr's toasts, offers the
+  sidebar row (`$py_card`) as a managed block in Herdr's `config.toml`, written only with a yes and checked with `herdr
+  config check`, and prints the keybindings to add yourself; `doctor` says what's set up (also by hand in a terminal);
+  `view` turns the plugin's Agents view on or off; `watch` is the watcher (one per Herdr server, held by a lease) that
+  raises Herdr's toast when a pane gains a card, never for the tab you're looking at, cards that arrive together in one,
+  a card also asked in the conversation after 3 minutes; `event` makes sure it runs; `unconfigure` stops it, takes the
+  badges off every pane and turns them off here, clears the view, and takes the block out. Read-only: nothing asks
+  Pending You anything. Herdr's socket API through `HERDR_SOCKET_PATH`.
+- Tests never reach a real Herdr: the test setup drops every `HERDR_*` variable from their environment.
+
 ## 0.16.0 (2026-10-05)
 
 - A word on one of your own cards that's neither an answer nor your person's (guide 2.32): `/mcp/cli/answers` marks it

package/README.md

@@ -284,6 +284,34 @@ It's never in your way: the hooks only start it in the background, each send giv
 You from before presence is taken quietly. A sign-in that only hears (`--oauth`) sends nothing. `npx pendingyou status`
 has a Presence line for each agent.
 
+Since 0.18.0, a session in a [Herdr](https://herdr.dev) pane also says which pane (`HERDR_PANE_ID`, such as `w2:p1`)
+and which Herdr server (16 hex characters of a hash of the computer's name and Herdr's socket path, never the path
+itself), so Pending You can list where each of an agent's running sessions is and the Pending You plugin for Herdr can
+take you to it. Anywhere else nothing of the kind is sent.
+
+## In Herdr
+
+Since 0.17.0, an agent running in a [Herdr](https://herdr.dev) pane marks its pane with what it's waiting on you for,
+so Herdr's sidebar and Agents panel can show it: display-only metadata Herdr keeps on this computer (`herdr agent list`
+shows it), written with Herdr's own command line:
+
+- `py_app` and `py_agent`: the app and the name the session goes by with Pending You;
+- `py_waiting`: how many of its cards wait on you; `py_card` the most pressing one's title (anything that looks like a
+  secret taken out, at most 80 characters); `py_cards` their request ids; `py_urgency` how pressing (`blocking`, `now`,
+  `today`, `whenever`); `py_asked` the ones it also asked you in its conversation;
+- and its state reads "waiting on you" instead of idle or done while something waits.
+
+Claude Code's wake mod writes them whenever they change, Codex's card hook and keeper, OpenCode's plugin and Pi's
+extension through the commands they already run; every 5 minutes again, and they're taken off when nothing waits and as
+the session ends. Herdr is given one second for each, never through a shell, and never waited on by a hook; it forgets
+them after 15 minutes unless told again.
+
+The Pending You plugin for Herdr puts them to use: the card on each waiting agent's row in the sidebar, a toast when a
+pane gains one, a key to the next pane waiting on you, a popup that lists them (Enter opens the card in Pending You), and
+an Agents view with them first. Its commands are this command line's: `npx pendingyou herdr doctor` says what's set
+up. Its `unconfigure` takes the badges off every pane and stops writing them on this computer; its setup turns them on
+again.
+
 ## How Claude Code hears your answer
 
 **Claude Code 2.1.287 or later: the wake mod.** There's nothing to run. In each session the mod learns the cards
@@ -378,6 +406,29 @@ Only want this command's own sign-in (for `watch`, below)? `npx pendingyou login
 hearing answers only, and adds no connection. Your phone asks "Let build-01 hear your answers for the assistants
 running on it?", with no choice of assistant.
 
+## This computer's key
+
+The first time `init` (or `login`) signs anything in, it makes this computer a key pair, kept in
+`~/.config/pendingyou/machine.json`: readable only by you, beside your sign-ins. Pending You knows the computer by that
+key, not by its name: two computers called "MacBook Pro" are two computers, and one you rename is still one. The
+private key never leaves this computer and is never printed; Pending You keeps only its public key's fingerprint.
+
+Every sign-in with a code proves the key, for that sign-in only and only once, so pressing Allow adds this computer,
+by its key, with the agents' connections it makes. A computer set up before 0.18.0 gets its key the next time you run
+`npx -y pendingyou@latest init`: each agent already signed in proves it with its own sign-in, with nothing to approve,
+and its sign-ins stay exactly as they are. Until then nothing changes on it. Pending You uses the key to keep your
+computers apart: an app you sign in on one computer later (such as the Pending You plugin for Herdr) sees only that
+computer's agents.
+
+- `npx pendingyou machine status` says whether Pending You knows each agent's connection here by this key.
+- `npx pendingyou machine rotate` makes a new key (it asks first; `--yes` doesn't). Pending You then knows this
+  computer as a new one, and its agents' connections stay with the old key until you remove that computer from your
+  account; the next `init` then proves the new one.
+- `npx pendingyou machine attest --client-id <id>` prints a proof of this computer for an app's own sign-in with a code
+  (`--cnf <thumbprint>` for that app's own key, `--name` for another name). It never prints the key.
+
+`uninstall` leaves the key: it names the computer and grants nothing on its own.
+
 ## Always-on scripts
 
 `watch` runs a command each time an answer is ready, for a script on your assistant's own machine:
@@ -407,6 +458,8 @@ its environment. A failing command is tried twice more, then skipped. `--once` s
 | `stopcheck` | The Stop hook: items for you left only in chat (`--app`) |
 | `uninstall` | Remove what `init` added, and sign out (`--app`) |
 | `mcp --app <app>` | The stdio bridge: a local MCP server for an agent that can't run a headers helper (OpenCode, Pi), which passes each message on to Pending You with that agent's own sign-in here (`--check`) |
+| `herdr doctor` | Pending You in Herdr: the badges, the plugin, its toasts and its sidebar row. The plugin runs `herdr next`, `open`, `setup`, `view` and `unconfigure`; the agents' writers `herdr report` |
+| `machine status` / `attest` / `rotate` | This computer's key: whether Pending You knows each agent's connection by it (exits 0 when it does), a proof of it for an app's own sign-in (`--client-id`, `--cnf`, `--name`), or a new key (`--yes`) |
 
 Every command takes `--origin` (default `https://www.pendingyou.com`, or `$PENDINGYOU_ORIGIN`). `--app` takes
 `claude-code`, `codex`, `opencode` or `pi` (several with commas where a command sets up or reports several); with none,
@@ -422,7 +475,8 @@ answer or change anything, and doesn't show up as an assistant. They're stored i
 (readable only by you, in a folder with a `.gitignore` of `*` so a dotfiles repository never takes it), refresh
 themselves, and end after 30 days or on `logout`. The headers helper hands an agent's token only to that agent's
 Pending You (Claude Code says which server it's for; Codex's is the one `init` wrote). `clients.json` remembers which
-sign-in each agent's connection used, so signing in again keeps it.
+sign-in each agent's connection used, so signing in again keeps it. `machine.json` (0.18.0) holds this computer's key
+pair, private like the rest; only its proofs leave the computer, each for one sign-in, once.
 
 `state.json` beside them remembers which answers were already handed over (ids only) and how many session starts
 reminded an unfinished setup, and when; `permission-cards/` each Claude Code session's (and Codex thread's) prompts
@@ -434,7 +488,11 @@ Pi session waits on, and (0.14.0) the names it went by and its folder, kept 12 h
 (ids, names, folders and titles: never an answer or a note); `pi/` Pi's extension; and `cli/` the hooks' copy of the
 command line. `init`, `status` and the hooks read `~/.claude.json` (and a folder's `.mcp.json`, and
 `~/.claude/settings.json`'s enabled plugins), `~/.codex/config.toml`, OpenCode's config and Pi's `mcp.json` only to see
-whether the agent has a `pendingyou` MCP server and where it points. With a sign-in that only hears, the hooks and
+whether the agent has a `pendingyou` MCP server and where it points. In a Herdr pane (0.17.0) the agents' writers hand
+Herdr's own command line, on this computer, the badges above: a card's title (redacted, 80 characters at most) and its
+request id, never an answer or a note; `<app>-threads.json` remembers the pane each session runs in, and `herdr.json`
+whether the badges are off. Presence there (0.18.0) also sends Pending You the pane's id and the hash that names its
+Herdr server. With a sign-in that only hears, the hooks and
 listeners tell this computer's handed questions from another's by its names: its hostname, the names its sign-ins by
 code were given, a Mac's own name (`scutil --get ComputerName`) and, outside a hook, Tailscale's (`tailscale status`). For a permission prompt's card, the worker reads
 the end of the Claude Code session's transcript only for the name the session gave Pending You, and `git remote

package/dist/api.js

@@ -127,7 +127,13 @@ function either(signal, ms) {
     timeout.addEventListener('abort', abort, { once: true });
     return controller.signal;
 }
-export async function getJson(io, origin, path, timeoutMs, signal, options = {}) {
+export function getJson(io, origin, path, timeoutMs, signal, options = {}) {
+    return callJson(io, origin, path, null, timeoutMs, signal, options);
+}
+export function sendJson(io, origin, path, body, timeoutMs, options = {}) {
+    return callJson(io, origin, path, { body }, timeoutMs, undefined, options);
+}
+async function callJson(io, origin, path, send, timeoutMs, signal, options = {}) {
     const app = options.app ?? DEFAULT_APP;
     for (let attempt = 0;; attempt++) {
         let token;
@@ -147,7 +153,12 @@ export async function getJson(io, origin, path, timeoutMs, signal, options = {})
         let response;
         try {
             response = await io.fetch(`${origin}${path}`, {
-                headers: { authorization: `Bearer ${token}`, accept: 'application/json' },
+                ...(send ? { method: 'POST', body: JSON.stringify(send.body), redirect: 'manual' } : {}),
+                headers: {
+                    authorization: `Bearer ${token}`,
+                    accept: 'application/json',
+                    ...(send ? { 'content-type': 'application/json' } : {}),
+                },
                 signal: either(signal, timeoutMs),
             });
         }

package/dist/apps/codex-wake.js

@@ -7,6 +7,7 @@ import { connectionMachine, readCredential } from "../credentials.js";
 import { configDir, readJson, withLock, writeWhole } from "../files.js";
 import { clip, delegatedOf, isClosed, noticeOf } from "../format.js";
 import { chooseThread, goesBy, HANDED_FOR_MS, handedCard, handedMessage, namesAnotherComputer, } from "../handed.js";
+import { clearHerdr, herdrTarget, isUrgency, PANE_ID, reportCommand, writeHerdr, } from "../herdr.js";
 import { macName, tailscaleName } from "../remote.js";
 import { claimHanded, markHanded, momentOf, releaseHanded, wasHanded } from "../state.js";
 import { findCodex } from "./codex-app.js";
@@ -55,6 +56,7 @@ function threadOf(value) {
         at: value.at,
         ...(names.length ? { names: names.slice(-NAMES) } : {}),
         ...(typeof value.cwd === 'string' && value.cwd ? { cwd: value.cwd } : {}),
+        ...(typeof value.herdr === 'string' && PANE_ID.test(value.herdr) ? { herdr: value.herdr } : {}),
     };
 }
 async function load(io, app) {
@@ -155,6 +157,7 @@ export async function posted(io, options) {
         const requestId = [output?.requestId, args.requestId].find((id) => typeof id === 'string' && REQUEST_ID.test(id));
         const cwd = text(input.cwd, 1000);
         const now = io.now();
+        const pane = await herdrTarget(io);
         await change(io, app, (state) => {
             if (turn && call !== 'cancel_request') {
                 const record = state.turns[turn] ?? { at: now, cards: [] };
@@ -171,19 +174,29 @@ export async function posted(io, options) {
                     const before = waiting.cards[requestId];
                     const name = nameOf(args) ?? before?.name;
                     const title = text(args.title, 400) ?? text(reopen?.title, 400) ?? before?.title;
+                    const urgency = isUrgency(args.urgency) ? args.urgency : before?.urgency;
+                    const blocking = typeof args.blocking === 'boolean' ? args.blocking : before?.blocking;
+                    const askedFirst = call === 'post_request' ? askedIn(args) : before?.askedFirst;
                     waiting.cards[requestId] = {
                         ...(name ? { name } : {}),
                         ...(title ? { title } : {}),
                         at: now,
+                        ...(urgency ? { urgency } : {}),
+                        ...(blocking ? { blocking } : {}),
+                        ...(askedFirst ? { askedFirst } : {}),
                     };
                 }
             }
             if (cwd)
                 waiting.cwd = cwd;
+            if (pane)
+                waiting.herdr = pane.pane;
             waiting.origin = options.origin;
             waiting.at = now;
             state.threads[thread] = waiting;
         });
+        if (pane)
+            io.background(reportCommand(app, { session: thread, at: now }));
         if (app === 'codex')
             await keepListening(io, options.origin, thread);
         return 0;
@@ -192,6 +205,60 @@ export async function posted(io, options) {
         return 0;
     }
 }
+function askedIn(args) {
+    let asked = args.askedFirst;
+    if (typeof asked === 'string')
+        try {
+            asked = JSON.parse(asked);
+        }
+        catch {
+            return false;
+        }
+    return isObject(asked);
+}
+export async function reportThreads(io, app, options) {
+    try {
+        const pane = await herdrTarget(io);
+        if (!pane)
+            return 'off';
+        const session = options.session && THREAD.test(options.session) ? options.session : null;
+        let state = await load(io, app);
+        const known = session ? state.threads[session] : undefined;
+        if (session && known) {
+            const wanted = options.closed
+                ? known.herdr === pane.pane
+                    ? undefined
+                    : known.herdr
+                : pane.pane;
+            if (wanted !== known.herdr)
+                state = await change(io, app, (next) => {
+                    const thread = next.threads[session];
+                    if (!thread)
+                        return;
+                    if (wanted)
+                        thread.herdr = wanted;
+                    else
+                        delete thread.herdr;
+                });
+        }
+        const here = Object.values(state.threads).filter((thread) => thread.herdr === pane.pane);
+        if (here.length === 0 && options.closed)
+            return await clearHerdr(io, options.at, pane);
+        const newest = [...here].sort((a, b) => b.at - a.at)[0];
+        const cards = here.flatMap((thread) => Object.entries(thread.cards).map(([requestId, card]) => ({
+            requestId,
+            ...(typeof card.title === 'string' ? { title: card.title } : {}),
+            ...(isUrgency(card.urgency) ? { urgency: card.urgency } : {}),
+            ...(card.blocking === true ? { blocking: true } : {}),
+            ...(card.askedFirst === true ? { askedFirst: true } : {}),
+            at: typeof card.at === 'number' ? card.at : 0,
+        })));
+        return await writeHerdr(io, { app, agent: newest?.names?.at(-1) ?? null, cards, at: options.at }, pane);
+    }
+    catch {
+        return 'failed';
+    }
+}
 export async function touchThread(io, app, thread, cwd) {
     try {
         if (!THREAD.test(thread) || !(await load(io, app)).threads[thread])
@@ -532,9 +599,12 @@ export async function listen(io, options) {
                 else
                     ready.push({ heard, card });
             }
-            const gone = () => change(io, app, (state) => {
-                delete state.threads[thread];
-            });
+            const gone = async () => {
+                await change(io, app, (state) => {
+                    delete state.threads[thread];
+                });
+                await reportThreads(io, app, { at: io.now() });
+            };
             const message = wakeMessage(ready);
             if (message) {
                 if (!(await deliver(message, ready.map(({ heard }) => heard.requestId)))) {
@@ -556,13 +626,15 @@ export async function listen(io, options) {
             for (const heard of requests)
                 if (cards[heard.requestId] && isClosed(heard) && !done.includes(heard.requestId))
                     done.push(heard.requestId);
-            if (done.length)
+            if (done.length) {
                 await change(io, app, (state) => {
                     const waiting = state.threads[thread];
                     if (waiting)
                         for (const id of done)
                             delete waiting.cards[id];
                 });
+                await reportThreads(io, app, { at: io.now() });
+            }
             if (io.now() - started > PATIENT_AFTER_MS)
                 await io.sleep(PATIENT_PAUSE_MS, signal);
         }

package/dist/args.js

@@ -1,7 +1,21 @@
-import { APP_IDS, APP_NAMES, isAppId } from "./apps/ids.js";
+import { APP_IDS, APP_NAMES, DEFAULT_APP, isAppId } from "./apps/ids.js";
 export const DEFAULT_ORIGIN = 'https://www.pendingyou.com';
 export const DEFAULT_TIMEOUT_MS = 4 * 60 * 60 * 1000;
 const MAX_TIMEOUT_MS = 24 * 60 * 60 * 1000;
+export const MACHINE_SUBS = ['status', 'attest', 'rotate'];
+export const HERDR_SUBS = [
+    'report',
+    'next',
+    'open',
+    'setup',
+    'doctor',
+    'unconfigure',
+    'watch',
+    'event',
+    'view',
+    'popup',
+];
+export const HERDR_POPUPS = ['cards', 'setup', 'doctor', 'demo'];
 export class UsageError extends Error {
     name = 'UsageError';
 }
@@ -66,6 +80,8 @@ const COMMANDS = new Set([
     'notify',
     'permission-card',
     'presence',
+    'herdr',
+    'machine',
 ]);
 const FLAGS = {
     help: {},
@@ -121,6 +137,20 @@ const FLAGS = {
     refresh: { origin: true, force: false, app: true },
     'mcp-headers': { origin: true, check: false, app: true },
     mcp: { origin: true, app: true, check: false },
+    herdr: {
+        origin: true,
+        app: true,
+        session: true,
+        transcript: true,
+        name: true,
+        state: true,
+        at: true,
+        demo: false,
+        yes: false,
+        wait: false,
+        ensure: false,
+    },
+    machine: { origin: true, 'client-id': true, cnf: true, name: true, yes: false },
 };
 const VALUE_OPTIONS = new Set([
     'origin',
@@ -135,6 +165,8 @@ const VALUE_OPTIONS = new Set([
     'transcript',
     'pid',
     'at',
+    'client-id',
+    'cnf',
 ]);
 function splitCommand(argv) {
     let index = 0;
@@ -381,6 +413,10 @@ export function parseArgs(argv, env = {}) {
         case 'mcp':
             none();
             return { name: 'mcp', origin, ...app(), check: flags.has('check') };
+        case 'herdr':
+            return herdrCommand(origin, positional, flags, app);
+        case 'machine':
+            return machineCommand(origin, positional, flags, machine);
         case 'init':
             none();
             return {
@@ -415,6 +451,124 @@ export function parseArgs(argv, env = {}) {
     }
     throw new UsageError(`There’s no “${first}” command.`);
 }
+function herdrCommand(origin, positional, flags, app) {
+    const [sub, target, ...extra] = positional;
+    if (sub === undefined)
+        throw new UsageError('herdr needs what to do, like: pendingyou herdr doctor');
+    if (!HERDR_SUBS.includes(sub))
+        throw new UsageError(`herdr has no “${sub}”. Use ${HERDR_SUBS.join(', ')}.`);
+    const allowed = {
+        report: ['app', 'session', 'transcript', 'name', 'state', 'at'],
+        next: [],
+        open: ['demo'],
+        setup: ['yes'],
+        doctor: ['wait'],
+        unconfigure: [],
+        watch: ['ensure'],
+        event: [],
+        view: [],
+        popup: [],
+    };
+    for (const key of flags.keys())
+        if (key !== 'origin' && !allowed[sub].includes(key))
+            throw new UsageError(`herdr ${sub} has no --${key} option.`);
+    const command = { name: 'herdr', origin, sub: sub };
+    const takes = (choices) => {
+        if (extra.length || (target !== undefined && !choices?.includes(target)))
+            throw new UsageError(choices
+                ? `herdr ${sub} takes ${choices.join(' or ')}.`
+                : `herdr ${sub} takes no “${target ?? extra[0]}”.`);
+    };
+    const text = (key) => {
+        const value = flags.get(key);
+        return typeof value === 'string' ? value : undefined;
+    };
+    switch (command.sub) {
+        case 'report': {
+            takes(null);
+            const session = text('session');
+            if (session !== undefined && !THREAD.test(session))
+                throw new UsageError('herdr report needs a session id, like: --session 0199a1b2-…');
+            const state = text('state');
+            if (state !== undefined && state !== 'live' && state !== 'closed')
+                throw new UsageError('--state is live or closed.');
+            const at = text('at');
+            if (at !== undefined && !/^\d{1,16}$/.test(at))
+                throw new UsageError('--at needs a number.');
+            const transcript = text('transcript');
+            const agentName = text('name');
+            return {
+                ...command,
+                app: app().app ?? DEFAULT_APP,
+                ...(session ? { session } : {}),
+                ...(transcript ? { transcript } : {}),
+                ...(agentName ? { agentName } : {}),
+                closed: state === 'closed',
+                ...(at ? { at: Number(at) } : {}),
+            };
+        }
+        case 'popup':
+            if (target === undefined)
+                throw new UsageError(`herdr popup needs a pane: ${HERDR_POPUPS.join(', ')}.`);
+            takes(HERDR_POPUPS);
+            return { ...command, target };
+        case 'view':
+            takes(['on', 'off']);
+            return target ? { ...command, target } : command;
+        case 'open':
+            takes(null);
+            return { ...command, demo: flags.has('demo') };
+        case 'setup':
+            takes(null);
+            return { ...command, yes: flags.has('yes') };
+        case 'doctor':
+            takes(null);
+            return { ...command, wait: flags.has('wait') };
+        case 'watch':
+            takes(null);
+            return { ...command, ensure: flags.has('ensure') };
+        default:
+            takes(null);
+            return command;
+    }
+}
+const CLIENT_ID = /^[\x21-\x7e]{1,2048}$/;
+const THUMBPRINT = /^[A-Za-z0-9_-]{43}$/;
+function machineCommand(origin, positional, flags, machine) {
+    const [sub, ...extra] = positional;
+    if (sub === undefined)
+        throw new UsageError('machine needs what to do, like: pendingyou machine status');
+    if (!MACHINE_SUBS.includes(sub))
+        throw new UsageError(`machine has no “${sub}”. Use ${MACHINE_SUBS.join(', ')}.`);
+    if (extra.length)
+        throw new UsageError(`machine ${sub} takes no “${extra[0]}”.`);
+    const allowed = {
+        status: [],
+        attest: ['client-id', 'cnf', 'name'],
+        rotate: ['yes'],
+    };
+    for (const key of flags.keys())
+        if (key !== 'origin' && !allowed[sub].includes(key))
+            throw new UsageError(`machine ${sub} has no --${key} option.`);
+    if (sub === 'status')
+        return { name: 'machine', origin, sub };
+    if (sub === 'rotate')
+        return { name: 'machine', origin, sub, yes: flags.has('yes') };
+    const clientId = flags.get('client-id');
+    if (typeof clientId !== 'string' || !CLIENT_ID.test(clientId))
+        throw new UsageError('machine attest needs the client the app signs in with, like: --client-id <its client id>');
+    const cnf = flags.get('cnf');
+    if (cnf !== undefined && (typeof cnf !== 'string' || !THUMBPRINT.test(cnf)))
+        throw new UsageError('--cnf is the app’s own key’s RFC 7638 thumbprint: 43 base64url characters.');
+    return {
+        name: 'machine',
+        origin,
+        sub: 'attest',
+        clientId,
+        ...(typeof cnf === 'string' ? { cnf } : {}),
+        ...machine(),
+    };
+}
 export const USAGE = `pendingyou: Pending You for your coding agents (Claude Code, Codex, OpenCode and Pi)
 
   npx -y pendingyou@latest init
@@ -440,6 +594,14 @@ export const USAGE = `pendingyou: Pending You for your coding agents (Claude Cod
   npx pendingyou mcp --app <app>
                                A stdio MCP server for an agent that can't run a headers helper: it
                                passes each message on to Pending You with that agent's sign-in here
+  npx pendingyou herdr doctor  Pending You in Herdr: the badges on your agents' panes, the plugin, its
+                               toasts and its sidebar row. The plugin runs herdr next, open, setup,
+                               view and unconfigure
+  npx pendingyou machine status | attest | rotate
+                               This computer's key, which Pending You knows it by (init makes it; it
+                               never leaves the computer): whether Pending You knows each agent's
+                               connection by it, a proof of it for an app's own sign-in
+                               (--client-id, --cnf), or a new key (--yes: without asking)
 
 Apps (for --app): ${APP_IDS.map((app) => `${app} (${APP_NAMES[app]})`).join(', ')}.