pendingyou 0.37.0 → 0.38.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.38.0 (2026-10-25)
+
+- Show in Herdr: press it on a card in Pending You, at your desk or on your phone, and Herdr moves to the pane of the
+  agent that asked, on every client attached to it. The Pending You plugin for Herdr's watcher listens for your
+  presses once Herdr's sign-in allows it (`assistants:show`), one wait at a time beside what it already does, and
+  checks each before anything moves: the pane must be on its own Herdr server, be there now, and be the agent's (its
+  badge lists the card, or it runs that kind of agent: `claude` for Claude Code). Otherwise Pending You hears "not
+  found" and nothing moves. It only ever brings a pane to the front: it never types into one, runs or opens anything,
+  and logs nothing. What it hears is ids and the agent's name, never a card's words.
+- `npx pendingyou app login herdr` asks for `assistants:show` too, and `app status` lists it: "bring the assistant
+  that asked to the front when you press Show". A sign-in from before doesn't hold it: the plugin's setup and doctor
+  say "Sign Herdr in again to use Show in Herdr: npx pendingyou app login herdr", and setup offers to.
+- Setup starts this version's watcher in place of one from an older pendingyou, which doesn't listen for Show in
+  Herdr; doctor says when the one running is older. The watcher's lease now says which pendingyou it is.
+- Fixed: Herdr's toast "Pending You · Herdr is signed out" could show twice when the sign-in ended just after its
+  tokens were renewed. The watcher now tells sign-ins apart by their key, which renewing doesn't change.
+
 ## 0.37.0 (2026-10-22)
 
 - A step your agent hands you now goes on a card (guide 2.55). When its last message gives you a step to do now (“Go:

package/README.md

@@ -412,6 +412,17 @@ as it does while Pending You is open on your desk.
 last use here; it warns in the last 3), and `npx pendingyou app logout herdr` ends Herdr's sign-in. Settings › Apps and devices in Pending You
 lists it too, with Remove. It needs `init` to have run here first: this computer's key vouches for the sign-in.
 
+### Show in Herdr (0.38.0)
+
+Press Show in Herdr on a card in Pending You, at your desk or on your phone, and Herdr moves to the pane of the agent
+that asked, on every client attached to it. The plugin's watcher listens for your presses once Herdr's sign-in allows it
+(`assistants:show`: `npx pendingyou app login herdr` asks for it; a sign-in from before 0.38.0 doesn't hold it, and the
+plugin's setup and doctor say to sign in again). It checks each press before anything moves: the pane must be on its own
+Herdr server, be there now, and be the agent's (its badge lists the card, or it runs that kind of agent, `claude` for
+Claude Code). Otherwise Pending You hears "not found", and nothing moves. It only ever brings a pane to the front: it
+never types into one, runs or opens anything, and logs nothing. Setup starts this version's watcher in place of one
+from an older pendingyou, which doesn't listen.
+
 ## 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
@@ -593,7 +604,9 @@ a command that acts for one agent acts for Claude Code. Options can come before
 hands over a card, and no agent's sign-in can. An app you sign in with `pendingyou app login` (the Pending You plugin
 for Herdr) answers only from its own sign-in and its own key, kept apart in `apps/<app>.json`, which nothing an agent
 runs here reads, and only when you press a key in it; never a high-stakes card, and Pending You labels every answer
-with the app and the computer.
+with the app and the computer. Signed in with `assistants:show` (0.38.0), Herdr's watcher also keeps one wait open with
+Pending You for your presses of Show in Herdr, which name a card, an agent and its pane, never a card's words, and it
+only ever brings that pane to the front.
 
 Each agent's sign-in is that agent's own connection on Pending You, signed in from this computer: it can post cards,
 change or cancel its own, read the answers to them and reply in their threads, and it can't answer anything for you.

package/dist/app-login.js

@@ -18,6 +18,7 @@ export const APP_SCOPES = [
     'cards:later',
     'cards:delegate',
     'assistants:read',
+    'assistants:show',
     'presence:desk',
 ];
 export const FIRST_PARTY_APPS = {
@@ -54,6 +55,7 @@ const MAY = {
     'cards:later': 'put them in Later',
     'cards:delegate': 'hand them to another assistant',
     'assistants:read': 'see your assistants',
+    'assistants:show': 'bring the assistant that asked to the front when you press Show',
     'presence:desk': 'keep your phone quiet while you use it',
 };
 const listed = (items) => items.length <= 1 ? (items[0] ?? '') : `${items.slice(0, -1).join(', ')} and ${items.at(-1)}`;

package/dist/args.js

@@ -619,6 +619,7 @@ const APP_SCOPE_NAMES = [
     'cards:later',
     'cards:delegate',
     'assistants:read',
+    'assistants:show',
     'presence:desk',
 ];
 function appCommandOf(origin, positional, flags, machine, device) {

package/dist/herdr/command.js

@@ -5,6 +5,7 @@ import { reportThreads } from "../apps/codex-wake.js";
 import { APP_IDS, APP_NAMES } from "../apps/ids.js";
 import { configDir, readText, writeWhole } from "../files.js";
 import { badgesOn, clearHerdr, HERDR_SOURCE, herdrBin, herdrPane, herdrTarget, readPayload, setBadges, TOKEN_NAMES, writeHerdr, } from "../herdr.js";
+import { originArgs } from "../hooks.js";
 import { sessionName } from "../permission.js";
 import { presenceName } from "../presence.js";
 import { headlessReason } from "../remote.js";
@@ -14,7 +15,7 @@ import { badgedPanes, nextWaiting, readWaiting } from "./panes.js";
 import { agentView, CARD_ROW, hasBlock, herdrConfigPath, KEYS_SNIPPET, ownSidebar, pluginOff, pluginPlace, SIDEBAR_BLOCK, saveView, setPluginOff, TOAST_SNIPPET, toastDelivery, viewOn, withBlock, withoutBlock, } from "./plugin.js";
 import { cardsPopup, originFor } from "./popup.js";
 import { HerdrError, herdrRequest } from "./socket.js";
-import { pluginEnabled, stopWatcher, watch, watching } from "./watch.js";
+import { olderWatcher, pluginEnabled, stopWatcher, watch, watching } from "./watch.js";
 async function toast(place, title, body) {
     if (!place.socket)
         return;
@@ -157,6 +158,16 @@ async function originHere(io, fallback) {
     return fallback;
 }
 const line = (mark, text) => `${mark} ${text}\n`;
+const showsHere = (stored) => stored.scopes.includes('assistants:show');
+const signInAgainForShow = (origin) => `Sign Herdr in again to use Show in Herdr: npx pendingyou app login herdr${originArgs(origin)}`;
+async function startWatcher(io, place) {
+    if (!place.socket)
+        return;
+    if (await olderWatcher(place))
+        await stopWatcher(place);
+    if (!(await watching(place)))
+        io.background(['herdr', 'watch']);
+}
 async function setup(io, place, options) {
     const ask = async (question) => {
         if (options.yes)
@@ -202,8 +213,7 @@ async function setup(io, place, options) {
             io.out(line('✓', 'Agents waiting on you come first in the Agents panel.'));
         }
     }
-    if (place.socket && !(await watching(place)))
-        io.background(['herdr', 'watch']);
+    await startWatcher(io, place);
     if (io.interactive && !options.yes)
         await io.ask('\nPress Enter to close. ');
     return 0;
@@ -212,6 +222,14 @@ async function signInStep(io, options, ask) {
     const stored = await readAppSignIn(io, 'herdr').catch(() => null);
     if (stored) {
         io.out(`${line('✓', `Herdr is signed in to Pending You at ${stored.origin}: its popup (prefix+y) answers your cards with a key.`)}  npx pendingyou app status herdr says what it may do and for how long.\n\n`);
+        if (showsHere(stored))
+            return;
+        io.out(line('!', signInAgainForShow(stored.origin)));
+        if (options.yes || !io.interactive || !(await ask('Sign Herdr in again now?'))) {
+            io.out('\n');
+            return;
+        }
+        await signInHerdr(io, stored.origin);
         return;
     }
     io.out(`\nAnswer from Herdr: once Herdr is signed in to Pending You, its popup (prefix+y) answers your cards with a key (a choice, yes or no, your words, Later, or handing it to another agent), only when you press one. High-stakes cards still open in Pending You. It sees only this computer's agents' cards unless you tick "all" when you allow it.\n`);
@@ -219,7 +237,9 @@ async function signInStep(io, options, ask) {
         io.out(`${line('·', 'Herdr isn’t signed in: its popup lists what’s waiting. Sign it in any time: setup again, or npx pendingyou app login herdr')}\n`);
         return;
     }
-    const origin = await originHere(io, options.origin);
+    await signInHerdr(io, await originHere(io, options.origin));
+}
+async function signInHerdr(io, origin) {
     const result = await signInApp(io, {
         app: 'herdr',
         origin,
@@ -271,9 +291,14 @@ async function doctor(io, place, options) {
     io.out(shim
         ? line('✓', `Your agents' hooks run ${shimPath(io)}.`)
         : line('!', 'Pending You isn’t set up for your agents here: run npx -y pendingyou@latest init'));
-    if (await readAppSignIn(io, 'herdr').catch(() => true)) {
+    const stored = await readAppSignIn(io, 'herdr').catch(() => undefined);
+    if (stored !== null) {
         const status = await appStatusLines(io, 'herdr');
         io.out(line(status.ok ? '✓' : '!', status.lines[0] ?? ''));
+        if (stored && status.ok)
+            io.out(showsHere(stored)
+                ? line('✓', 'Show in Herdr: press it on a card in Pending You, and Herdr goes to the pane of the agent that asked.')
+                : line('!', signInAgainForShow(stored.origin)));
     }
     else
         io.out(line('·', 'Herdr isn’t signed in to Pending You: its popup lists what’s waiting. Setup signs it in.'));
@@ -294,9 +319,11 @@ async function doctor(io, place, options) {
             const { snapshot, waiting } = await readWaiting(place.socket);
             const badged = badgedPanes(snapshot).length;
             io.out(line('·', `${badged} pane${badged === 1 ? '' : 's'} with Pending You's badges, ${waiting.length} waiting on you.`));
-            io.out((await watching(place))
-                ? line('✓', 'Its watcher is running (toasts when a pane gains a card).')
-                : line('!', 'Its watcher isn’t running: it starts with Herdr, or with setup.'));
+            io.out(!(await watching(place))
+                ? line('!', 'Its watcher isn’t running: it starts with Herdr, or with setup.')
+                : (await olderWatcher(place))
+                    ? line('!', `Its watcher runs an older pendingyou than this one (${VERSION}): setup restarts it.`)
+                    : line('✓', 'Its watcher is running (toasts when a pane gains a card).'));
             io.out(line('·', `Its Agents view is ${(await viewOn(place)) ? 'on' : 'off'}.`));
         }
         catch (error) {

package/dist/herdr/show.js

@@ -0,0 +1,35 @@
+import { isAppId } from "../apps/ids.js";
+import { HERDR_AGENTS, TOKENS } from "../herdr.js";
+import { idsOf, readSnapshot } from "./panes.js";
+import { herdrRequest } from "./socket.js";
+export const SHOW_PLACES = ['herdr'];
+export const placeHere = (server) => (place) => place.app === 'herdr' && place.server === server;
+const herdrAgentOf = (app) => (isAppId(app) ? HERDR_AGENTS[app] : null);
+export async function showPane(socket, show) {
+    const result = await herdrRequest(socket, 'session.snapshot');
+    const { panes } = readSnapshot(result?.snapshot);
+    const agent = herdrAgentOf(show.agent.app);
+    for (const place of show.places) {
+        const pane = panes.find((each) => each.paneId === place.paneId);
+        if (!pane)
+            continue;
+        if (idsOf(pane.tokens[TOKENS.cards]).includes(show.card.id))
+            return { paneId: pane.paneId };
+        if (agent !== null && pane.agent === agent)
+            return { paneId: pane.paneId };
+    }
+    return null;
+}
+export async function focusPane(socket, pane) {
+    await herdrRequest(socket, 'pane.focus', { pane_id: pane.paneId });
+}
+export function followHerdrShows(client, options) {
+    const { socket, server, signal } = options;
+    return client.followShows({
+        places: [...SHOW_PLACES],
+        mine: placeHere(server),
+        find: (show) => showPane(socket, show),
+        focus: (pane) => focusPane(socket, pane),
+        signal,
+    });
+}

package/dist/herdr/watch.js

@@ -2,11 +2,15 @@ import { randomBytes } from 'node:crypto';
 import { mkdir, readFile, rm, stat, utimes, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { appClient, RENEW_WITHIN_MS, readAppSignIn } from "../app-login.js";
+import { herdrServer } from "../herdr.js";
+import { atLeast } from "../mod.js";
 import { SignedOutError } from "../sdk/index.js";
+import { VERSION } from "../version.js";
 import { due, emptyNotices, look } from "./notice.js";
 import { readWaiting } from "./panes.js";
 import { agentView, pluginOff, viewOn } from "./plugin.js";
 import { awayDesk, deskStep, lastActive } from "./presence.js";
+import { followHerdrShows } from "./show.js";
 import { HerdrError, herdrRequest, herdrSubscribe } from "./socket.js";
 export const LEASE_STALE_MS = 60_000;
 export const RENEW_MS = 20_000;
@@ -32,7 +36,10 @@ async function takeLease(place) {
     const id = randomBytes(8).toString('hex');
     await rm(path, { force: true });
     try {
-        await writeFile(path, JSON.stringify({ id, pid: process.pid }), { flag: 'wx', mode: 0o600 });
+        await writeFile(path, JSON.stringify({ id, pid: process.pid, version: VERSION }), {
+            flag: 'wx',
+            mode: 0o600,
+        });
         return id;
     }
     catch {
@@ -43,13 +50,23 @@ async function holder(place) {
     try {
         const held = JSON.parse(await readFile(leasePath(place), 'utf8'));
         return typeof held.id === 'string' && typeof held.pid === 'number'
-            ? { id: held.id, pid: held.pid }
+            ? {
+                id: held.id,
+                pid: held.pid,
+                version: typeof held.version === 'string' ? held.version : null,
+            }
             : null;
     }
     catch {
         return null;
     }
 }
+export async function olderWatcher(place) {
+    if (!(await watching(place)))
+        return false;
+    const held = await holder(place);
+    return held !== null && (held.version === null || !atLeast(held.version, VERSION));
+}
 async function renew(place, id) {
     if ((await holder(place))?.id !== id)
         return false;
@@ -121,6 +138,8 @@ const FOCUS_EVENTS = new Set([
     'workspace_focused',
 ]);
 const EXPIRY_CHECK_MS = 6 * 60 * 60_000;
+export const SHOWS_AGAIN_MS = 10 * 60_000;
+const signInOf = (stored) => `${stored.key.x}.${stored.key.y}`;
 export const SIGNED_OUT_TOAST = {
     title: 'Pending You · Herdr is signed out',
     body: 'Removed in Settings, signed in again, or ended. To answer from Herdr again: Pending You: set up.',
@@ -131,19 +150,50 @@ export const endingToast = (days) => ({
 });
 export function signInKeeper(io, socket, place) {
     let client = null;
-    let token = null;
+    let current = null;
     let presence = false;
+    let shows = false;
     let desk = awayDesk();
     let checkedAt = Number.NEGATIVE_INFINITY;
-    let endedToken = null;
+    let endedSignIn = null;
     let warnedAt = Number.NEGATIVE_INFINITY;
     let focusAt = null;
-    const ended = async () => {
-        if (token && endedToken !== token) {
-            endedToken = token;
+    const server = herdrServer(io.env, io.host);
+    let following = null;
+    let refused = null;
+    const stopShows = () => {
+        following?.stop.abort();
+        following = null;
+    };
+    const ended = async (which = current) => {
+        if (which === null || which !== current)
+            return;
+        client = null;
+        stopShows();
+        if (endedSignIn !== which) {
+            endedSignIn = which;
             await showToast(socket, SIGNED_OUT_TOAST);
         }
-        client = null;
+    };
+    const followShows = () => {
+        if (!client || !current || !shows || !server || following || io.signal.aborted)
+            return;
+        if (refused?.signIn === current && io.now() - refused.at < SHOWS_AGAIN_MS)
+            return;
+        const run = { signIn: current, stop: new AbortController() };
+        following = run;
+        void followHerdrShows(client, { socket, server, signal: run.stop.signal })
+            .catch(async (error) => {
+            if (error instanceof SignedOutError)
+                await ended(run.signIn);
+            else
+                refused = { signIn: run.signIn, at: io.now() };
+        })
+            .catch(() => { })
+            .finally(() => {
+            if (following === run)
+                following = null;
+        });
     };
     return {
         heard(event) {
@@ -152,16 +202,27 @@ export function signInKeeper(io, socket, place) {
         },
         async renew() {
             const stored = await readAppSignIn(io, 'herdr').catch(() => null);
-            if (!stored || stored.refreshToken === endedToken) {
+            const signIn = stored ? signInOf(stored) : null;
+            if (!stored || signIn === endedSignIn) {
                 client = null;
-                token = stored?.refreshToken ?? null;
+                current = signIn;
+                stopShows();
                 return;
             }
-            if (token !== stored.refreshToken || !client) {
-                token = stored.refreshToken;
+            if (signIn !== current || !client) {
+                current = signIn;
                 client = appClient(io, 'herdr');
-                presence = stored.scopes.includes('presence:desk');
+                stopShows();
             }
+            presence = stored.scopes.includes('presence:desk');
+            shows = stored.scopes.includes('assistants:show');
+            if (shows)
+                followShows();
+            else
+                stopShows();
+        },
+        stop() {
+            stopShows();
         },
         async tick() {
             if (!client)
@@ -268,6 +329,7 @@ export async function watch(io, place, options) {
         return 0;
     }
     finally {
+        signIn.stop();
         if ((await holder(place))?.id === lease)
             await rm(leasePath(place), { force: true }).catch(() => { });
     }

package/dist/sdk/client.js

@@ -2,9 +2,11 @@ import { changeFeed } from "./changes.js";
 import { importKey, proof, wantsNonce } from "./dpop.js";
 import { ApiError, SignedOutError } from "./errors.js";
 import { nonces, tokenRequest } from "./oauth.js";
+import { followShowsWith, showFeed } from "./shows.js";
 export const REFRESH_SKEW_MS = 60_000;
 const CACHE_MAX = 200;
 const path = (id, action) => `/v1/cards/${encodeURIComponent(id)}${action ? `/${action}` : ''}`;
+const showPath = (id) => `/v1/shows/${encodeURIComponent(id)}`;
 export function queryString(query) {
     const params = new URLSearchParams();
     for (const [name, value] of Object.entries(query ?? {})) {
@@ -218,6 +220,16 @@ export function createClient(options) {
             ...(query ? { query: query } : {}),
         }),
         changes: (opts) => changeFeed((query, signal) => client.changesPage(query, signal ? { signal } : {}), { now: http.now, sleep }, opts),
+        showsPage: (query, opts) => request('GET', '/v1/shows', {
+            ...opts,
+            query: query,
+        }),
+        shows: (opts) => showFeed((query, signal) => client.showsPage(query, signal ? { signal } : {}), { now: http.now, sleep }, opts),
+        answerShow: (id, result, opts) => request('POST', showPath(id), {
+            body: { result },
+            ...keyed(opts?.idempotencyKey),
+        }),
+        followShows: (opts) => followShowsWith((follow) => client.shows(follow), (id, result) => client.answerShow(id, result), opts),
         request,
     };
     return client;

package/dist/sdk/index.js

@@ -5,5 +5,6 @@ export { deviceSignIn, } from "./device.js";
 export { generateKey, importKey, thumbprint } from "./dpop.js";
 export { ApiError, SignedOutError, SignInError } from "./errors.js";
 export * from "./openapi.generated.js";
+export { REPEAT_MS } from "./shows.js";
 export { signOut } from "./signout.js";
 export { memoryStore } from "./store.js";

package/dist/sdk/shows.js

@@ -0,0 +1,86 @@
+import { backoffMs, WAIT_SECONDS } from "./changes.js";
+import { ApiError, SignedOutError } from "./errors.js";
+export const REPEAT_MS = 1000;
+const KEPT_MS = 60_000;
+export async function* showFeed(look, clock, options) {
+    const { signal } = options;
+    const wait = Math.max(0, Math.min(WAIT_SECONDS, options.wait ?? WAIT_SECONDS));
+    const yielded = new Map();
+    let failures = 0;
+    while (!signal?.aborted) {
+        let page;
+        try {
+            page = await look({ places: [...options.places], wait }, signal);
+        }
+        catch (error) {
+            if (signal?.aborted)
+                return;
+            if (error instanceof SignedOutError)
+                throw error;
+            if (error instanceof ApiError) {
+                if (error.status === 429) {
+                    failures++;
+                    await clock.sleep((error.retryAfterSeconds ?? 60) * 1000, signal);
+                    continue;
+                }
+                if (error.status < 500)
+                    throw error;
+            }
+            failures++;
+            await clock.sleep(backoffMs(failures), signal);
+            continue;
+        }
+        failures = 0;
+        const now = clock.now();
+        for (const [id, until] of yielded)
+            if (until < now)
+                yielded.delete(id);
+        const fresh = page.shows.filter((show) => !yielded.has(show.id));
+        for (const show of fresh) {
+            const ends = Date.parse(show.expiresAt);
+            yielded.set(show.id, (Number.isFinite(ends) ? ends : now) + KEPT_MS);
+            yield show;
+            if (signal?.aborted)
+                return;
+        }
+        if (page.shows.length > 0 && fresh.length === 0)
+            await clock.sleep(REPEAT_MS, signal);
+    }
+}
+function isMine(options, place, show) {
+    if (!options.mine)
+        return true;
+    try {
+        return options.mine(place, show);
+    }
+    catch {
+        return false;
+    }
+}
+export async function followShowsWith(shows, answer, options) {
+    const { places, wait, signal, find, focus } = options;
+    for await (const show of shows({ places, wait, signal })) {
+        const theirs = show.places.filter((place) => isMine(options, place, show));
+        if (!theirs.length)
+            continue;
+        const ours = { ...show, places: theirs };
+        let result = 'not_found';
+        try {
+            const window = await find(ours);
+            if (window !== null && window !== undefined) {
+                await focus(window, ours);
+                result = 'shown';
+            }
+        }
+        catch {
+            result = 'not_found';
+        }
+        try {
+            await answer(show.id, result);
+        }
+        catch (error) {
+            if (error instanceof SignedOutError)
+                throw error;
+        }
+    }
+}

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.37.0';
+export const VERSION = '0.38.0';

package/mod/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pendingyou-wake",
   "displayName": "Pending You",
-  "version": "2.54.1",
+  "version": "2.56.0",
   "description": "Wakes Claude Code when your person answers a Pending You card it posted, even while it sits idle. Installed by `npx pendingyou init`.",
   "author": {
     "name": "RecordPlane",

package/mod/README.md

@@ -4,4 +4,4 @@ The pendingyou command line’s copy of the Pending You plugin’s wake mod, for
 
 In each session it learns the cards the session posts to Pending You, checks them through the session’s own Pending You connection, and starts a turn when your person answers, writes back or a fallback comes due, or hands the session a question from another of their assistants (CLI 0.14.0), even while it sits idle. It answers `npx pendingyou hold` itself, so nothing waits in the background, and shows “2 waiting on you” under the prompt, after the plugin’s name. With the Pending You plugin installed too, only one copy acts.
 
-Generated from recordplane/pendingyou (packages/claude-plugin/src/wake) with Pending You’s guide 2.54.1; send changes there.
+Generated from recordplane/pendingyou (packages/claude-plugin/src/wake) with Pending You’s guide 2.56.0; send changes there.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pendingyou",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Pending You for your coding agents: one command sets up Claude Code, Codex, OpenCode and Pi to ask you through Pending You and hear your answers, even while they sit idle.",
   "keywords": [
     "pendingyou",