pendingyou 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.21.0 (2026-10-06)
+
+- Answer from Herdr. The Pending You plugin for Herdr (0.2) can now answer your cards from its popup, once you sign
+  Herdr in. The command line itself still never answers anything: the plugin's popup does, with Herdr's own sign-in
+  and its own key, only when you press a key in it, and never a high-stakes card.
+- `pendingyou app login herdr` (also the plugin's setup) signs Herdr in to Pending You with a code, as `login --device`
+  does: your phone or browser shows one card naming Herdr and this computer, with a tick for all your cards (off: it
+  sees this computer's agents' cards only). This computer's key (0.18.0) vouches for the sign-in, naming Herdr and the
+  new sign-in's own key, so run `npx -y pendingyou@latest init` here first. The sign-in and its private key are kept
+  in `~/.config/pendingyou/apps/herdr.json` (readable only by you), which none of the agents' hooks, helpers or
+  `hold` read; its tokens are useless without that key (DPoP). Signing in again on the same computer replaces it.
+  `pendingyou app status` says what each app signed in here may do and until when (and warns in its last 3 days);
+  `pendingyou app logout herdr` ends it at Pending You and removes it. Another registered app signs in with
+  `--client-id` (and `--scope`).
+- The popup (`prefix+y`), signed in: your cards from Pending You, the chosen one open with what it asks, how many wait
+  elsewhere, and a key per decision: 1–9 for a choice (and Enter to send several), y or n to approve or decline, Enter
+  to write an answer, y or n for a step done or not, Tab between a grouped card's questions. r writes to the agent, l
+  puts the card in Later, d hands it to another of your agents, u undoes for 5 seconds, t goes to the agent's pane
+  (from its badges, or its session running in this Herdr), o opens the card in Pending You (high-stakes cards are
+  answered there), a opens all your cards. It follows Pending You's change feed while it's open. Not signed in, it's
+  the read-only list it was, with a line saying how to sign in. `herdr open --demo` shows made-up cards, for
+  screenshots.
+- Your phone stays quiet while you're active in Herdr (moving between panes, tabs and workspaces, or pressing keys in
+  the popup), for the cards Herdr can show, as it does while Pending You is open on your desk. The plugin's watcher
+  also says in a toast when Herdr's sign-in has ended, and in its last 3 days that it's about to.
+- The plugin's `unconfigure` signs Herdr out too. `doctor` says whether it's signed in.
+- The plugin 0.2 runs the command line `init` put here only once that one can answer (`pendingyou app` exists);
+  until then it runs 0.21.0 through npx. Run `npx pendingyou@latest init` once to switch.
+- Answering works once Pending You turns on its person API for its own apps; until then sign-in says Pending You
+  doesn't let Herdr sign in yet.
+
+## 0.20.1 (2026-10-06)
+
+- An older answer is no longer hidden behind newer ones. The session-start and next-message hooks asked for a folder's
+  five newest answers and left out the ones already handed over, so a session with five newer answers it hadn't
+  acknowledged yet never heard an older one, even on the person's own message (seen 2026-10-06: two answers waited
+  over an hour). They now ask for 20 and hand over the newest five not handed over yet; the rest come with the next
+  message.
+- The wake mod (guide 2.33.1) makes room in a session's list of 50 cards with the answers its agent already heard,
+  never a card still waiting on you while there's one of those: a session that ran many agents lost its oldest open
+  cards, and their answers were never told.
+
 ## 0.20.0 (2026-10-06)
 
 - “I’ll handle it”: a card you ended yourself in Pending You says so, and tells the agent to stand down. An answer can

package/README.md

@@ -316,8 +316,30 @@ 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.
+up. Its `unconfigure` takes the badges off every pane and stops writing them on this computer (and signs Herdr out);
+its setup turns them on again.
+
+### Answering from Herdr (0.21.0)
+
+Sign Herdr in, from the plugin's setup or here:
+
+```sh
+npx pendingyou app login herdr
+```
+
+Your phone or browser shows one card naming Herdr and this computer: press and hold Allow. Herdr then sees the cards
+of this computer's agents (tick "all" on that card for every card of yours), and its popup (`prefix+y`) answers them
+with a key: 1–9 for a choice (Enter sends several), y or n to approve or decline, Enter to write an answer, y or n for
+a step done or not, Tab between a grouped card's questions; r writes to the agent, l puts it in Later, d hands it to
+another of your agents, u undoes for 5 seconds, t goes to the agent's pane, o opens the card in Pending You. A
+high-stakes card (it spends money, can't be undone or goes public) is never answered from Herdr: o opens it where you
+hold to approve. Pending You says on the card and to the agent "Answered in Herdr on build-01". While you're active in
+Herdr (moving between panes, tabs and workspaces, or pressing keys in the popup) your phone stays quiet for those cards,
+as it does while Pending You is open on your desk.
+
+`npx pendingyou app status` says what each app signed in here may do and until when (a sign-in lasts 30 days; 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.
 
 ## How Claude Code hears your answer
 
@@ -472,6 +494,7 @@ its environment. A failing command is tried twice more, then skipped. `--once` s
 | `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`) |
+| `app login` / `logout` / `status` | An app that answers your cards when you press a key in it, signed in on this computer (`herdr`, or another app with `--client-id` and `--scope`; `--device`, `--browser`, `--name`), out again, or what each may do and until when |
 
 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,
@@ -479,6 +502,12 @@ a command that acts for one agent acts for Claude Code. Options can come before
 
 ## What it can see, and where it keeps things
 
+**The command line never answers for you.** None of its commands, hooks or helpers answers, replies to, snoozes or
+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.
+
 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.
 The hooks use the same sign-in, and hand a session only the cards its own app posted from its folder. An agent that
@@ -488,7 +517,10 @@ answer or change anything, and doesn't show up as an assistant. They're stored i
 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. `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.
+pair, private like the rest; only its proofs leave the computer, each for one sign-in, once. `apps/<app>.json` (0.21.0)
+holds an app's own sign-in and the private key its tokens are bound to (DPoP), private like the rest; the Pending You
+plugin for Herdr also keeps, in Herdr's state folder for it, when you last pressed a key in its popup (a time, nothing
+else).
 
 `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

package/dist/app-login.js

@@ -0,0 +1,304 @@
+import { readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ignoreFolder } from "./credentials.js";
+import { PlainError } from "./errors.js";
+import { configDir } from "./files.js";
+import { originArgs } from "./hooks.js";
+import { attest, clockOffset, readMachine } from "./machine.js";
+import { showDevices } from "./oauth.js";
+import { computerName, headlessReason } from "./remote.js";
+import { ApiError, createClient, deviceSignIn, SignedOutError, SignInError, signOut, } from "./sdk/index.js";
+import { fileStore } from "./sdk/node.js";
+import { memoryStore } from "./sdk/store.js";
+export const APP_SCOPES = [
+    'cards:read',
+    'cards:read:all',
+    'cards:answer',
+    'cards:reply',
+    'cards:later',
+    'cards:delegate',
+    'assistants:read',
+    'presence:desk',
+];
+export const FIRST_PARTY_APPS = {
+    herdr: { name: 'Herdr', scopes: APP_SCOPES },
+};
+export const DEFAULT_SCOPES = ['cards:read'];
+export const APP_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
+export const RENEW_WITHIN_MS = 3 * 24 * 60 * 60 * 1000;
+export const appsDir = (io) => join(configDir(io), 'apps');
+export const appPath = (io, app) => join(appsDir(io), `${app}.json`);
+export const appStore = (io, app) => fileStore(appPath(io, app));
+export const appLabel = (app) => FIRST_PARTY_APPS[app]?.name ?? app;
+export async function readAppSignIn(io, app) {
+    try {
+        return await appStore(io, app).load();
+    }
+    catch {
+        throw new PlainError(`${appLabel(app)}’s sign-in (${appPath(io, app)}) can’t be read. Sign in again to replace it: npx pendingyou app login ${app}`);
+    }
+}
+export function appClient(io, app) {
+    return createClient({
+        store: appStore(io, app),
+        fetch: io.fetch,
+        now: () => io.now(),
+        sleep: (ms, signal) => io.sleep(ms, signal),
+    });
+}
+const MAY = {
+    'cards:read': 'see your cards',
+    'cards:read:all': 'see all your cards',
+    'cards:answer': 'answer them',
+    'cards:reply': 'write to the assistant that asked',
+    'cards:later': 'put them in Later',
+    'cards:delegate': 'hand them to another assistant',
+    'assistants:read': 'see your assistants',
+    '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)}`;
+export function reachWords(me) {
+    return me.grant.reach === 'all' || !me.grant.machine
+        ? 'all your cards'
+        : `cards from ${me.grant.machine.name}’s agents`;
+}
+export function signedInAs(app, me) {
+    const name = FIRST_PARTY_APPS[app] ? appLabel(app) : (me?.app.name ?? app);
+    return me?.grant.machine ? `${name} on ${me.grant.machine.name}` : name;
+}
+function signInWords(error, app) {
+    const name = appLabel(app);
+    switch (error.code) {
+        case 'access_denied':
+            return `You pressed Cancel, so ${name} isn’t signed in.`;
+        case 'expired_token':
+            return 'The code ran out. Run the command again for a new one.';
+        case 'invalid_client':
+            return FIRST_PARTY_APPS[app]
+                ? `Pending You doesn’t let ${name} sign in yet.`
+                : 'Pending You doesn’t know that app, or it doesn’t sign in with a code.';
+        case 'invalid_request':
+            return `Pending You didn’t take this computer’s key. Run npx -y pendingyou@latest init, then try again.`;
+        case 'invalid_scope':
+            return `Pending You doesn’t let ${name} ask for that.`;
+        case 'slow_down':
+            return 'Too many sign-ins from here. Wait 10 minutes, then try again.';
+        case 'aborted':
+            return 'Signing in was stopped.';
+        default:
+            return error.message;
+    }
+}
+export async function signInApp(io, options) {
+    const { app, origin } = options;
+    const name = appLabel(app);
+    const firstParty = FIRST_PARTY_APPS[app];
+    if (!firstParty && !options.clientId)
+        return {
+            ok: false,
+            said: `Name ${app}’s client with --client-id, or sign in Pending You’s own: ${Object.keys(FIRST_PARTY_APPS).join(', ')}.`,
+        };
+    const machine = await readMachine(io);
+    if (!machine)
+        return {
+            ok: false,
+            said: `This computer isn’t set up with Pending You yet: run npx -y pendingyou@latest init${originArgs(origin)} first, then sign ${name} in.`,
+        };
+    const computer = (await computerName(io, options.machine)).name;
+    const offset = await clockOffset(io, origin);
+    const before = await readAppSignIn(io, app).catch(() => null);
+    await ignoreFolder(io).catch(() => { });
+    let started;
+    try {
+        started = await deviceSignIn({
+            origin,
+            ...(options.clientId ? { clientId: options.clientId } : { app }),
+            scopes: options.scopes ?? firstParty?.scopes ?? DEFAULT_SCOPES,
+            machine: computer,
+            attest: (request) => attest(machine, {
+                aud: request.audience,
+                ...(request.clientId ? { client_id: request.clientId } : { app }),
+                name: computer,
+                cnf: { jkt: request.jkt },
+            }, io.now() + offset),
+            store: appStore(io, app),
+            fetch: io.fetch,
+            now: () => io.now(),
+            sleep: (ms, signal) => io.sleep(ms, signal),
+            signal: io.signal,
+        });
+    }
+    catch (error) {
+        if (error instanceof SignInError)
+            return { ok: false, said: signInWords(error, app) };
+        return { ok: false, said: `Pending You at ${origin} couldn’t be reached. Try again.` };
+    }
+    io.err(`Signing ${name} in on ${computer}. Once you allow it, ${name} can answer your cards when you press a key in it; high-stakes cards still open in Pending You.\n`);
+    await showDevices(io, [
+        {
+            flow: {
+                page: started.verificationUri,
+                direct: started.verificationUriComplete,
+                userCode: started.userCode,
+            },
+        },
+    ], options.open);
+    try {
+        await started.signedIn;
+    }
+    catch (error) {
+        if (error instanceof SignInError)
+            return { ok: false, said: signInWords(error, app) };
+        return { ok: false, said: `Pending You at ${origin} couldn’t be reached. Try again.` };
+    }
+    if (before && before.origin !== origin)
+        await signOut({ store: memoryStore(before), fetch: io.fetch }).catch(() => 'unreachable');
+    const me = await appClient(io, app)
+        .me()
+        .catch(() => null);
+    return { ok: true, me };
+}
+async function login(io, command) {
+    const headless = headlessReason(io);
+    const open = command.browser && (command.device === false || (command.device === null && !headless));
+    const result = await signInApp(io, {
+        app: command.app,
+        origin: command.origin,
+        ...(command.clientId ? { clientId: command.clientId } : {}),
+        ...(command.machine ? { machine: command.machine } : {}),
+        ...(command.scopes ? { scopes: command.scopes } : {}),
+        open,
+    });
+    if (!result.ok) {
+        io.err(`pendingyou: ${result.said}\n`);
+        return 1;
+    }
+    io.out(`${signedInWords(io, command.app, result.me)}\n`);
+    return 0;
+}
+export function signedInWords(io, app, me) {
+    const name = appLabel(app);
+    const answers = me ? me.grant.scopes.includes('cards:answer') : true;
+    return [
+        me
+            ? `${signedInAs(app, me)} is signed in: it ${answers ? 'answers' : 'sees'} ${reachWords(me)}${answers ? ', only when you press a key in it' : ''}.`
+            : `${name} is signed in.`,
+        `Its sign-in is in ${appPath(io, app)}, with a key that never leaves this computer.`,
+        `To remove it: npx pendingyou app logout ${app}, or Settings › Apps and devices in Pending You.`,
+    ].join('\n');
+}
+export async function signOutApp(io, app) {
+    const stored = await readAppSignIn(io, app).catch(() => undefined);
+    const path = appPath(io, app);
+    if (!stored) {
+        const there = await rm(path).then(() => true, () => false);
+        return { said: there ? 'unreadable' : 'none', origin: null };
+    }
+    const said = await signOut({ store: memoryStore(stored), fetch: io.fetch });
+    await rm(path, { force: true });
+    return { said, origin: stored.origin };
+}
+async function logout(io, app) {
+    const { said, origin } = await signOutApp(io, app);
+    const name = appLabel(app);
+    io.out(said === 'none'
+        ? `${name} wasn’t signed in here.\n`
+        : said === 'signed-out'
+            ? `Signed ${name} out of Pending You${origin ? ` at ${origin}` : ''}.\n`
+            : said === 'unreadable'
+                ? `Removed ${name}’s sign-in here, which couldn’t be read: remove it in Settings › Apps and devices too, or it ends by itself within 30 days.\n`
+                : `Signed ${name} out on this computer. Pending You couldn’t be reached to end the sign-in there: remove it in Settings › Apps and devices, or it ends by itself within 30 days.\n`);
+    return 0;
+}
+export async function signedInApps(io) {
+    const names = await readdir(appsDir(io)).catch(() => []);
+    return names
+        .filter((name) => name.endsWith('.json'))
+        .map((name) => name.slice(0, -'.json'.length))
+        .filter((name) => APP_NAME.test(name))
+        .sort();
+}
+export async function appStatusLines(io, app) {
+    const name = appLabel(app);
+    let stored;
+    try {
+        stored = await readAppSignIn(io, app);
+    }
+    catch (error) {
+        return { ok: false, lines: [`${name}: ${error.message}`] };
+    }
+    if (!stored)
+        return {
+            ok: false,
+            lines: [`${name}: not signed in here. To sign it in: npx pendingyou app login ${app}`],
+        };
+    const again = `npx pendingyou app login ${app}${originArgs(stored.origin)}`;
+    let me;
+    try {
+        me = await appClient(io, app).me();
+    }
+    catch (error) {
+        if (error instanceof SignedOutError)
+            return {
+                ok: false,
+                lines: [
+                    `${name}: signed out at ${stored.origin} (removed in Settings, replaced by another sign-in, or ended). To sign in again: ${again}`,
+                ],
+            };
+        if (error instanceof ApiError && error.code === 'app_not_available')
+            return {
+                ok: false,
+                lines: [`${name}: signed in at ${stored.origin}, but Pending You doesn’t let it in now.`],
+            };
+        return {
+            ok: false,
+            lines: [
+                `${name}: signed in at ${stored.origin}; Pending You couldn’t be reached to say more.`,
+            ],
+        };
+    }
+    const scopes = me.grant.scopes;
+    const may = scopes
+        .filter((scope) => scope !== 'cards:read' || !scopes.includes('cards:read:all'))
+        .map((scope) => MAY[scope] ?? scope);
+    const ends = Date.parse(me.grant.expiresAt);
+    const left = ends - io.now();
+    const days = Math.max(0, Math.ceil(left / 86_400_000));
+    return {
+        ok: true,
+        lines: [
+            `${name}: signed in at ${stored.origin} as ${signedInAs(app, me)}`,
+            `  It reaches ${reachWords(me)}. It may ${listed(may)}; never a high-stakes card.`,
+            left <= RENEW_WITHIN_MS
+                ? `  ! It ends in ${days} day${days === 1 ? '' : 's'} (${me.grant.expiresAt.slice(0, 10)}): sign in again before then: ${again}`
+                : `  It ends on ${me.grant.expiresAt.slice(0, 10)}; sign in again then.`,
+            `  Kept in ${appPath(io, app)}`,
+        ],
+    };
+}
+async function status(io, app) {
+    const apps = app ? [app] : await signedInApps(io);
+    if (apps.length === 0) {
+        io.out('No app is signed in on this computer. The Pending You plugin for Herdr signs in from its setup, or: npx pendingyou app login herdr\n');
+        return 1;
+    }
+    let ok = true;
+    const sections = [];
+    for (const each of apps) {
+        const said = await appStatusLines(io, each);
+        ok &&= said.ok;
+        sections.push(said.lines.join('\n'));
+    }
+    io.out(`${sections.join('\n\n')}\n`);
+    return ok ? 0 : 1;
+}
+export async function appCommand(io, command) {
+    switch (command.sub) {
+        case 'login':
+            return login(io, { ...command, app: command.app });
+        case 'logout':
+            return logout(io, command.app);
+        case 'status':
+            return status(io, command.app);
+    }
+}

package/dist/args.js

@@ -2,6 +2,7 @@ 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 APP_SUBS = ['login', 'logout', 'status'];
 export const MACHINE_SUBS = ['status', 'attest', 'rotate'];
 export const HERDR_SUBS = [
     'report',
@@ -82,6 +83,7 @@ const COMMANDS = new Set([
     'presence',
     'herdr',
     'machine',
+    'app',
 ]);
 const FLAGS = {
     help: {},
@@ -151,6 +153,15 @@ const FLAGS = {
         ensure: false,
     },
     machine: { origin: true, 'client-id': true, cnf: true, name: true, yes: false },
+    app: {
+        origin: true,
+        'client-id': true,
+        scope: true,
+        name: true,
+        device: false,
+        browser: false,
+        'no-browser': false,
+    },
 };
 const VALUE_OPTIONS = new Set([
     'origin',
@@ -167,6 +178,7 @@ const VALUE_OPTIONS = new Set([
     'at',
     'client-id',
     'cnf',
+    'scope',
 ]);
 function splitCommand(argv) {
     let index = 0;
@@ -417,6 +429,8 @@ export function parseArgs(argv, env = {}) {
             return herdrCommand(origin, positional, flags, app);
         case 'machine':
             return machineCommand(origin, positional, flags, machine);
+        case 'app':
+            return appCommandOf(origin, positional, flags, machine, device);
         case 'init':
             none();
             return {
@@ -569,6 +583,66 @@ function machineCommand(origin, positional, flags, machine) {
         ...machine(),
     };
 }
+const APP_SCOPE_NAMES = [
+    'cards:read',
+    'cards:read:all',
+    'cards:answer',
+    'cards:reply',
+    'cards:later',
+    'cards:delegate',
+    'assistants:read',
+    'presence:desk',
+];
+function appCommandOf(origin, positional, flags, machine, device) {
+    const [sub, app, ...extra] = positional;
+    if (sub === undefined)
+        throw new UsageError('app needs what to do, like: pendingyou app login herdr');
+    if (!APP_SUBS.includes(sub))
+        throw new UsageError(`app has no “${sub}”. Use ${APP_SUBS.join(', ')}.`);
+    if (extra.length)
+        throw new UsageError(`app ${sub} takes one app, not “${extra[0]}”.`);
+    const allowed = {
+        login: ['client-id', 'scope', 'name', 'device', 'browser', 'no-browser'],
+        logout: [],
+        status: [],
+    };
+    for (const key of flags.keys())
+        if (key !== 'origin' && !allowed[sub].includes(key))
+            throw new UsageError(`app ${sub} has no --${key} option.`);
+    if (app !== undefined && !/^[a-z0-9][a-z0-9-]{0,39}$/.test(app))
+        throw new UsageError(`“${app}” isn’t an app’s name here: lower-case letters, digits and dashes.`);
+    if (app === undefined && sub !== 'status')
+        throw new UsageError(`app ${sub} needs the app, like: pendingyou app ${sub} herdr`);
+    const command = {
+        name: 'app',
+        origin,
+        sub: sub,
+        ...(app ? { app } : {}),
+        device: null,
+        browser: true,
+    };
+    if (sub !== 'login')
+        return command;
+    const clientId = flags.get('client-id');
+    if (clientId !== undefined && (typeof clientId !== 'string' || !CLIENT_ID.test(clientId)))
+        throw new UsageError('--client-id needs the client the app signs in with.');
+    const scope = flags.get('scope');
+    let scopes;
+    if (typeof scope === 'string') {
+        scopes = [...new Set(scope.split(/[\s,]+/).filter(Boolean))];
+        const unknown = scopes.find((each) => !APP_SCOPE_NAMES.includes(each));
+        if (unknown || scopes.length === 0)
+            throw new UsageError(`--scope takes the person API’s scopes: ${APP_SCOPE_NAMES.join(', ')}.`);
+    }
+    return {
+        ...command,
+        ...(typeof clientId === 'string' ? { clientId } : {}),
+        ...(scopes ? { scopes } : {}),
+        ...machine(),
+        device: device(),
+        browser: !flags.has('no-browser'),
+    };
+}
 export const USAGE = `pendingyou: Pending You for your coding agents (Claude Code, Codex, OpenCode and Pi)
 
   npx -y pendingyou@latest init
@@ -602,6 +676,10 @@ export const USAGE = `pendingyou: Pending You for your coding agents (Claude Cod
                                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)
+  npx pendingyou app login herdr | logout herdr | status
+                               Sign in an app that answers your cards when you press a key in it (the
+                               Pending You plugin for Herdr), out again, or what each may do. This
+                               command line never answers: the app does, with its own sign-in and key
 
 Apps (for --app): ${APP_IDS.map((app) => `${app} (${APP_NAMES[app]})`).join(', ')}.