pendingyou 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 0.10.0
+
+- The wake mod: Claude Code 2.1.287 or later is woken when you answer, with nothing waiting in the background. A
+  session heard your answer only while `npx pendingyou hold` ran, and a hold stops: after its own 4 hours, or sooner
+  when Claude Code stops a background command. Then it said "Don't start another hold now", and an answer that came
+  later waited until you next typed in that session; two sessions missed answers that way overnight (2026-10-04).
+  `init` now adds the Pending You plugin's mod, which this package carries in `mod/`, to `CLAUDE_CODE_PLUGIN_DIRS`
+  (`env` in `~/.claude/settings.json`), from the hooks' own copy in `~/.config/pendingyou/cli/0.10.0/`, keeping any
+  other folders there and replacing an older version's copy. Each session then learns the cards it posts, checks them
+  through its own Pending You connection (every 20 seconds while a card changed in the last half hour, then every
+  minute), and starts one turn when you answer, write back or a fallback comes due: “Pending You: your person
+  answered … Call get_request for it …, act on their words, then ack_answer.” Under the prompt it shows
+  `⚠ pendingyou-wake: 2 waiting on you`. It answers `npx pendingyou hold` itself, so an agent that still runs one waits on
+  nothing. With the Pending You plugin installed too (it carries the same mod, plugin 2.24), only one copy acts. On an
+  older Claude Code, or none, `init` skips it without a word. `uninstall` takes it out; `status` says whether it's
+  loaded, from where, and what to do when it isn't.
+- Without the mod, a hold that stops without an answer (its own `--timeout`, or Claude Code stopping it) says to start
+  it again in the background, with the exact command, `--origin` and `--timeout` included when they aren't the
+  defaults.
+- The next-message hook looks for this folder's answers with every message, not only while a hold had left an entry
+  behind: one request, as before, given up after 2 seconds, inside the hook's 3-second deadline. `state.json` no
+  longer keeps holds' waits.
+- A computer with no browser (a devbox or server you SSH into): one code approved on your phone sets Claude Code up.
+  `/mcp`'s Authenticate opened a browser on that machine, which nobody could reach, and `login --device` only signed
+  this command in. Now `init` there (an SSH session, or Linux with no display; `--device` forces it, `--browser` the
+  browser) signs the machine in by code as a Claude Code connection of its own ("Claude Code on devbox" on your
+  Assistants page, named by `--name`, else Tailscale's name for it, else its hostname; `login --name` with a new name
+  renames the connection with one more approval, which `login` suggests for a cloud's own name like `ip-10-42-1-252`;
+  QR code of the link at a terminal), then adds the MCP server with a `headersHelper` instead of OAuth
+  (`claude mcp add-json`), the wake mod in `env.CLAUDE_CODE_PLUGIN_DIRS` with `mcp__pendingyou` allowed, the skill and
+  the hooks. The helper, `~/.config/pendingyou/bin/pendingyou-mcp-headers`, is a small sh script Claude Code runs on
+  each connection: it finds Node on PATH, then nvm's default, then the Node `init` ran with, runs this version's own
+  copy (never npx) and prints only `{"Authorization":"Bearer …"}` (`pendingyou mcp-headers`), refreshing the sign-in in
+  the background when it's due. A browser sign-in at the same address (0.9.0's) is switched over; another's
+  `headersHelper` is kept. `login` there signs in that connection again, with the same client, so the machine keeps
+  one connection. `status` says what's set up and what's missing (it runs the helper as Claude Code would with a bare
+  PATH), each with the command that fixes it, `--origin` included off production. `uninstall` takes the helper out and
+  says the connection stays on your Assistants page. Needs Pending You's Worker from the same release.
+- `login` over SSH signs in by code without `--device`. A sign-in by code names the computer, and the phone asks "Let
+  devbox hear your answers for the assistants running on it?"; in the browser, "Let this computer hear…". Neither offers
+  a choice of assistant any more (Darin, 2026-10-04): a computer hears for the assistants running on it. A sign-in
+  pointed at one assistant before then keeps hearing it, so `watch` for a Muse or another app can't be set up anew.
+- Routing by sender: the hooks and `hold` ask Pending You for Claude Code's cards only (`source=claude-code`), so a card
+  Codex or another app posted from the same folder never reaches a Claude Code session, even with a sign-in pointed at
+  that app. `watch` names no app: it hands answers to a script, not a session. Pending You treats a folder's request
+  from an older version the same way.
+- Hooks still run 0.9.0 from `~/.config/pendingyou/cli/0.9.0/`: run `npx pendingyou@latest init` once to switch, and
+  to add the mod.
+
+## 0.9.0
+
+- The Stop check catches a final message that asks you to type or reply something in Claude Code's own chat
+  ("Reply “yes, erase disk12” here", "To confirm, type `yes`", "Confirm here"). Some steps an agent takes only on your
+  own words in its conversation, not on a card answer (something that can't be undone, credentials, anything outside
+  its sandbox), and that's right; but when it asks only in its chat, you never learn where you're needed. Unless a
+  Pending You card posted in that turn, or one still open from this folder, asks for the same thing, Claude Code is
+  asked once to post an action card that sends you there (about 76 tokens, plus the link): titled “Confirm in Claude
+  Code on <computer>: <step>”, with the exact words as a step's command (so the card shows them with a copy button),
+  where to type them, and what it'll do then; or, for a card you already answered, to reopen it with the same ask.
+- The link is the session's own when Claude Code says it: `https://claude.ai/code/<id>` from
+  `CLAUDE_CODE_BRIDGE_SESSION_ID` while Remote Control is on, or from `CLAUDE_CODE_REMOTE_SESSION_ID` on the web.
+- It counts as an ask: an imperative or a request to you ("please …", "can you …", "I need you to …") with the words
+  quoted, in backticks, or a plain "yes", tied to this chat ("here", "in this chat") or to going ahead ("to confirm",
+  "and I'll …"). Not in code, block quotes or quoted text; not what a program, prompt, page or message says; not a step
+  in your terminal, at a prompt or on a page; not a standing offer ("anytime"); not a command or slash command. A card
+  matches when its words name what's being confirmed ("erase" and "disk12"), or, with only a "yes" to go on, when it
+  was posted in the turn or its title asks to confirm.
+- Only such a message costs a request: this folder's open cards (the same one the next-message hook makes), given up
+  after 1.5 seconds. When Pending You can't say (offline, slow, an older server), the message's own word that it's on
+  a card is taken. Everything else the Stop check does is as before, with no request.
+- Hooks still run this version from `~/.config/pendingyou/cli/0.9.0/`: run `npx pendingyou@latest init` once to switch.
+
 ## 0.8.0
 
 - The hooks say when a session is on another Pending You. A Claude Code session stayed connected to staging after its

package/README.md

@@ -11,20 +11,25 @@ Run it once on each computer. It:
 
 - adds the Pending You MCP server to Claude Code for every project (unless it's already there),
 - saves the Pending You skill to `~/.claude/skills/pendingyou/SKILL.md`,
-- signs this computer in (your browser opens once; press Allow),
+- signs this computer in (your browser opens once; press Allow; over SSH, a code on your phone instead, as
+  [below](#a-computer-with-no-browser)),
 - adds three hooks to `~/.claude/settings.json`: a new session picks up answers that arrived while nothing was
   running, your next message brings a waiting answer with it, and a check when Claude Code finishes a turn (below),
 - lets Claude Code start `npx pendingyou hold` and use Pending You's tools without a permission prompt, so a question
   it asks while you're away doesn't wait on one,
 - keeps a copy of this version for the hooks in `~/.config/pendingyou/cli/<version>/`, so they start in a few
-  hundredths of a second instead of waiting on npx (about half a second each).
+  hundredths of a second instead of waiting on npx (about half a second each),
+- on Claude Code 2.1.287 or later, adds the wake mod in that copy to `CLAUDE_CODE_PLUGIN_DIRS` (`env` in
+  `~/.claude/settings.json`), so every session is woken when you answer (below). Other folders already there are kept;
+  an older version's copy is replaced.
 
 Your other settings are kept as they are. `npx pendingyou uninstall` removes exactly what `init` added.
 
 Adding the MCP server can take Claude Code a minute or more (it checks its servers); `init` says when it's waiting on
 that. If Claude Code already has a `pendingyou` server pointing somewhere else (staging, say), `init` names both and
 asks before replacing it; `--yes` replaces it without asking, and with nobody to ask it prints the two commands to
-run. Afterwards restart Claude Code, run `/mcp`, choose pendingyou and Authenticate.
+run. Afterwards restart Claude Code, run `/mcp`, choose pendingyou and Authenticate (on a computer with no browser
+there's nothing to authenticate: [below](#a-computer-with-no-browser)).
 
 If the `pendingyou` MCP server Claude Code uses in a session's folder is another Pending You than the hooks' (staging
 and production, say), both hooks add one line telling Claude Code so, and to ask you which one you use: its cards
@@ -37,7 +42,7 @@ never refreshes the sign-in itself: when that's due, it starts the refresh in th
 own. Running `init` again updates them in place, and adds any a newer version brings.
 
 The hooks run that copy with Node directly, like
-`"/opt/homebrew/bin/node" "~/.config/pendingyou/cli/0.8.0/node_modules/pendingyou/dist/cli.js" handoff || true` (the
+`"/opt/homebrew/bin/node" "~/.config/pendingyou/cli/0.10.0/node_modules/pendingyou/dist/cli.js" handoff || true` (the
 paths in full). If the copy can't be made (no npm, no network), they run through `npx -y --prefer-offline
 pendingyou@<version>` instead. `npx pendingyou status` says which. If you remove the Node they run with, run `init`
 again.
@@ -51,48 +56,100 @@ Deep into a long conversation, Claude Code tends to end a turn with a question f
   person also goes on a card.* While cards Claude Code posted from this folder are still waiting on you, the same line
   names them (at most 3, newest first, about 20 tokens each) and asks it to `cancel_request` one with `answeredHere`
   when your message answers it, so a question you answer in chat doesn't stay in your queue. That costs one small
-  request per message, given up after 1.5 seconds.
+  request per message, which brings any answer waiting for this folder too, given up after 2 seconds.
 - When Claude Code finishes a turn, `pendingyou stopcheck` looks at its last message. If it has something for you and
   nothing was posted, updated or replied to in Pending You that turn (and the message doesn't say it's on a card, or
   that one is coming),
   Claude Code is asked to go on once (about 31 tokens): post them as cards, or say they don't need one. It never asks
   twice in a row.
 
-The check is pattern matching on your computer: no model, no network. It reads only the last turn from the end of the
+The check is pattern matching on your computer: no model. It reads only the last turn from the end of the
 transcript (at most 4 MB) and skips code blocks and quotes. It counts as for you: a question to you (a sentence ending
 in "?" with "you" or "your"); "you'll need to", "your step", "can you", "please run", "in your terminal", "only you
 can", "waiting on you" and the like; or a list under a heading like "Your part", "Your steps", "For you", "Waiting on
 you" or "Left for you". It lets the turn end when the message says nothing needs a card ("No card needed.", "Nothing
 needs your attention.", "There's nothing waiting on you.").
 
+Since 0.9.0 it also catches a message asking you to type or reply something in Claude Code's own chat ("Reply “yes,
+erase disk12” here", "To confirm, type `yes`", "Confirm here"). Some steps an agent takes only on your own words in
+its conversation, never on a card answer; that's fine, but then a card has to send you there. Unless a card posted in
+that turn, or one still open from this folder, asks for the same thing, Claude Code is asked once to post an action
+card titled “Confirm in Claude Code on <computer>: <step>”, with the exact words to copy, where to type them (the
+session's link when Remote Control or Claude Code on the web gives one) and what it'll do then. Only such a message
+costs a request: this folder's open cards, given up after 1.5 seconds.
+
 **On 0.2.0 with another origin?** Its hooks blocked every message (`There's no "--origin" command`). Run
 `npx pendingyou@latest init --origin <url>` again to repair them; see [CHANGELOG.md](CHANGELOG.md).
 
-## How Claude Code uses it
+## 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
+Claude Code posts, checks them through the session's own Pending You connection (every 20 seconds while a card changed
+in the last half hour, then every minute), and when you answer (after the 5-second window to undo), write back, or a
+fallback comes due, it starts a turn naming the card and what to do: read it with `get_request`, act, then
+`ack_answer`. That works while the session sits idle at the prompt, for as long as it's open, and across a restart
+with `claude --continue`. Under the prompt it shows `⚠ pendingyou-wake: 2 waiting on you`. If Claude Code still runs
+`npx pendingyou hold`, the mod answers it at once and nothing runs in the background. With the Pending You plugin
+installed as well, only one copy acts. `npx pendingyou status` says whether the mod is loaded.
+
+The mod's checks are Pending You tool calls like Claude Code's own, so they need Pending You's tools allowed, which
+`init` does (`mcp__pendingyou`). If they aren't, the line under the prompt says which rule to add in `/permissions`, and
+holds run as before.
 
-After it posts a question to Pending You, Claude Code runs this in the background and keeps working:
+**Older Claude Code: a background hold.** After it posts a question to Pending You, Claude Code runs this in the
+background and keeps working:
 
 ```sh
 npx pendingyou hold req_0123456789abcdef0123
 ```
 
-When you answer (after the 5-second window to undo), write back, or the question's fallback comes due, it prints a few
-lines (the question, your answer, the next step) and exits. Claude Code wakes up with them. It stops on its own after
-4 hours (`--timeout`), telling Claude Code the hooks will bring the answer later.
+When you answer, write back, or the question's fallback comes due, it prints a few lines (the question, your answer,
+the next step) and exits. Claude Code wakes up with them. It stops on its own after 4 hours (`--timeout`), and Claude
+Code may stop a background command sooner; either way it then says to start it again, with the exact command. Your
+next message brings any answer with it too.
 
 When you're at the terminal, Claude Code asks you there and puts the same question in Pending You at once; the
 first answer wins. If you answer in the terminal, it withdraws the card and the hold ends by itself.
 
 ## A computer with no browser
 
-On a server or over SSH, sign in with a code instead:
+On a devbox or server you reach over SSH, `/mcp`'s Authenticate opens a browser on that machine, which you can't
+reach. So SSH in, and at the prompt there run:
 
 ```sh
-npx pendingyou login --device
+npx pendingyou init
 ```
 
-It shows a short code. Open pendingyou.com/device on your phone, sign in, enter the code and press Allow. Only enter a
-code your own computer is showing you.
+`init` sees it's an SSH session (or Linux with no display) and signs the machine in with a code instead: it shows the
+code, `pendingyou.com/device` and a QR code of the link with the code in it. Open it on your phone, sign in, check the
+code matches and press Allow. Only allow a code your own computer is showing you. That one approval makes the machine
+a Claude Code connection of its own ("Claude Code on devbox" on your Assistants page), and `init` sets up the rest:
+
+- adds the `pendingyou` MCP server for every project with a `headersHelper` instead of OAuth
+  (`claude mcp add-json --scope user pendingyou '{"type":"http","url":"…/mcp","headersHelper":"…"}'`), so Claude Code
+  signs in through this machine's sign-in and there's nothing to Authenticate,
+- writes that helper, `~/.config/pendingyou/bin/pendingyou-mcp-headers`, a small sh script Claude Code runs each time
+  it connects. It finds Node on PATH, else nvm's default (`$NVM_DIR` or `~/.nvm`), else the Node `init` ran with,
+  runs this version's own copy (never npx), and prints only `{"Authorization":"Bearer …"}`, refreshing the sign-in
+  when it's due,
+- adds the wake mod, the hooks and Pending You's tools to `~/.claude/settings.json` as above, so Remote Control,
+  terminal multiplexers and plain SSH sessions all get them, whatever shell profile they read.
+
+Run it at an interactive prompt after you SSH in, not as `ssh host npx pendingyou init`: on stock Ubuntu that one-line
+form doesn't read your shell's setup, so nvm's Node and `claude` may not be on PATH. `--device` sets a computer up this
+way wherever it is, and `--browser` uses the browser instead. Then start Claude Code there and ask it to finish
+setting up Pending You. `npx pendingyou status` says what's set up and what's missing, with the command that fixes it.
+If the sign-in ends (30 days, or you remove the machine on your Assistants page), `npx pendingyou login` approves a
+new code and keeps the same connection.
+
+The machine is called by its Tailscale name when Tailscale is installed and running (as `tailscale status` shows it),
+else by its hostname, or by `--name devbox` on `init` or `login`. A cloud's own hostname (AWS's `ip-10-42-1-252`) is
+kept when there's nothing better, and `login` says how to change it: `npx pendingyou login --name <name>` asks for one
+more approval on your phone and renames the connection, which stays the same one.
+
+Only want this command's own sign-in (for `watch`, below)? `npx pendingyou login --device` signs it in with a code,
+hearing answers only, and adds no connection. Your phone asks "Let devbox hear your answers for the assistants running
+on it?", with no choice of assistant.
 
 ## Always-on scripts
 
@@ -102,8 +159,9 @@ code your own computer is showing you.
 npx pendingyou watch -- ./on-answer.sh
 ```
 
-When you sign in, pick which assistant it hears for ("Hear answers for: Only Muse"); by default it's your Claude Code
-assistants. The command runs without a shell, once per answer, message or fallback that comes due, oldest first. It
+It hears your Claude Code assistants' answers. Signing in asks no choice of assistant (since 2026-10-04: "Let pi hear
+your answers for the assistants running on it?"); a sign-in pointed at one assistant before then keeps hearing that
+one. The command runs without a shell, once per answer, message or fallback that comes due, oldest first. It
 gets the request as JSON on stdin, and `PENDINGYOU_REQUEST_ID`, `PENDINGYOU_EVENT` (`answer_ready`, `message_ready` or
 `fallback_due`), `PENDINGYOU_VERSION` and `PENDINGYOU_ORIGIN` in its environment. A failing command is tried twice
 more, then skipped. `--once` stops after the first.
@@ -112,10 +170,10 @@ more, then skipped. `--once` stops after the first.
 
 | Command | What it does |
 | --- | --- |
-| `init` | Set up Claude Code on this computer (`--no-login`, `--no-browser`, `--device`, `--yes`) |
-| `hold <requestId>` | Wait for the answer, print it, exit (`--timeout 4h`) |
+| `init` | Set up Claude Code on this computer (`--no-login`, `--no-browser`, `--device`, `--browser`, `--yes`) |
+| `hold <requestId>` | Wait for the answer, print it, exit (`--timeout 4h`); the wake mod answers it itself |
 | `status` | What's set up; exits 0 when Claude Code hears answers right away |
-| `login` / `logout` | Sign this computer in or out (`--device`, `--force`, `--all`) |
+| `login` / `logout` | Sign this computer in or out (`--device`, `--browser`, `--force`, `--all`) |
 | `watch -- <command>` | Run a command each time an answer is ready (`--once`) |
 | `pickup` / `handoff` | The session-start and next-message hooks |
 | `stopcheck` | The Stop hook: items for you left only in chat |
@@ -126,14 +184,22 @@ before or after the command.
 
 ## What it can see, and where it keeps things
 
-The sign-in only hears answers to your own Claude Code assistants' questions, or to the one assistant you picked. It isn't an assistant: it can't ask,
-answer or change anything, and it doesn't show up as one. It's stored in `~/.config/pendingyou/credentials.json`
-(readable only by you), refreshes itself, and ends after 30 days or on `logout`. `state.json` beside it remembers
+The sign-in only hears answers to your own Claude Code assistants' questions (or, for one made before 2026-10-04, to the one assistant you picked). It isn't an assistant: it can't ask,
+answer or change anything, and it doesn't show up as one. The hooks and `hold` hand a session only the cards its own
+app (Claude Code) posted from its folder, never one Codex or another app posted there. On a computer with no browser it's that computer's Claude
+Code connection instead, which Claude Code asks through, and the hooks hear its answers only. It's stored in
+`~/.config/pendingyou/credentials.json` (readable only by you), refreshes itself, and ends after 30 days or on
+`logout`; `clients.json` remembers which sign-in a computer's connection used, so signing in again keeps it. `state.json` beside it remembers
 which answers were already handed over (ids only), `claude-code.json` what `init` added, 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) only to see whether Claude Code has a `pendingyou` MCP server and where
 it points. Nothing is sent anywhere but Pending You.
 
+The wake mod runs inside Claude Code and reaches Pending You only through the session's own connection, with
+`get_request` on the session's own cards. It keeps each session's cards (id, title, the agent's name, where each
+stands) in Claude Code's store for mods, `~/.claude/plugins/store/`, and forgets them once they close or after 7 days.
+It marks the copy acting for a session in that session's environment (`PENDINGYOU_WAKE_OWNER`).
+
 ## Development
 
 In the Pending You repo: `pnpm --filter pendingyou test`, `pnpm --filter pendingyou build` (to `dist/`). Try it with a

package/dist/api.js

@@ -12,6 +12,12 @@
 import { credentialsPath, readCredential, updateCredential, } from "./credentials.js";
 import { isLocked } from "./files.js";
 import { OAuthError, refresh } from "./oauth.js";
+/**
+ * The app whose sessions the command line hands answers to: its hooks and holds run in Claude Code. Routing by sender
+ * (2026-10-04): every request for a session names it, so Pending You returns only Claude Code's cards, never one Codex
+ * or another app posted from the same folder. `watch` names none: it hands answers to a script, not a session.
+ */
+export const SESSION_APP = 'claude-code';
 /** Refresh this long before the access token runs out. */
 const EARLY_MS = 60_000;
 /** A hook starts a background refresh this long before the access token runs out, and goes on with the old one. */
@@ -116,6 +122,33 @@ async function hookToken(io, origin, force, signal) {
     }
     throw new Unavailable('The sign-in is being refreshed in the background.');
 }
+/**
+ * The token `pendingyou mcp-headers` hands Claude Code (remote.ts). Claude Code runs the helper each time it connects
+ * and gives it 10 seconds, so, as for a hook, a refresh is never made in this process: within 5 minutes of expiry it
+ * starts `pendingyou refresh` detached and waits for its token, up to `waitMs`, then uses the old one while it still
+ * works. A token handed over has at least 10 seconds left; Claude Code runs the helper again on a 401.
+ */
+export async function helperToken(io, origin, waitMs) {
+    const stored = await readCredential(io, origin);
+    if (!stored)
+        throw new SignInNeeded(false);
+    if (stored.expiresAt - io.now() > SOON_MS)
+        return stored.accessToken;
+    if (!(await isLocked(credentialsPath(io))))
+        io.background(['refresh', '--origin', origin]);
+    const until = io.now() + waitMs;
+    while (io.now() < until) {
+        await io.sleep(100);
+        const current = await readCredential(io, origin);
+        if (!current)
+            throw new SignInNeeded(true);
+        if (current.refreshToken !== stored.refreshToken)
+            return current.accessToken;
+    }
+    if (stored.expiresAt - io.now() > USABLE_MS)
+        return stored.accessToken;
+    throw new Unavailable('Pending You couldn’t be reached to refresh the sign-in.');
+}
 /** Aborts on `signal` or after `ms`, whichever comes first (AbortSignal.any needs Node 20.3). */
 function either(signal, ms) {
     const timeout = AbortSignal.timeout(ms);

package/dist/args.js

@@ -20,6 +20,24 @@ export function parseDuration(text) {
     const unit = match[2] ?? 'm';
     return Math.round(amount * (unit === 's' ? 1000 : unit === 'm' ? 60_000 : 3_600_000));
 }
+/**
+ * A computer's name as Pending You keeps it (a connection's machine, "Claude Code on devbox"): control and format
+ * characters out, spaces collapsed, at most 60 characters. Empty when nothing is left.
+ */
+export function cleanName(text) {
+    const cleaned = [...text]
+        .map((char) => (/[\p{Cc}\p{Cf}]/u.test(char) ? ' ' : char))
+        .join('')
+        .replace(/\s+/g, ' ')
+        .trim();
+    let short = '';
+    for (const char of cleaned) {
+        if (short.length + char.length > 60)
+            break;
+        short += char;
+    }
+    return short.trim();
+}
 /** An origin Pending You can live at: https, or http on this computer (the local dev server). */
 export function parseOrigin(text) {
     let url;
@@ -50,25 +68,42 @@ const COMMANDS = new Set([
     'uninstall',
     'watch',
     'refresh',
+    'mcp-headers',
 ]);
 /** Flags each command takes; `true` when the flag takes a value. */
 const FLAGS = {
     help: {},
     version: {},
-    login: { origin: true, 'no-browser': false, force: false, device: false },
+    login: {
+        origin: true,
+        'no-browser': false,
+        force: false,
+        device: false,
+        browser: false,
+        name: true,
+    },
     logout: { origin: true, all: false },
     status: { origin: true },
     hold: { origin: true, timeout: true },
     pickup: { origin: true },
     handoff: { origin: true },
     stopcheck: { origin: true },
-    init: { origin: true, 'no-login': false, 'no-browser': false, device: false, yes: false },
+    init: {
+        origin: true,
+        'no-login': false,
+        'no-browser': false,
+        device: false,
+        browser: false,
+        yes: false,
+        name: true,
+    },
     uninstall: { origin: true },
     watch: { origin: true, once: false },
     refresh: { origin: true, force: false },
+    'mcp-headers': { origin: true, check: false },
 };
 /** Options that take a value, whichever command they belong to: needed to find the command behind them. */
-const VALUE_OPTIONS = new Set(['origin', 'timeout']);
+const VALUE_OPTIONS = new Set(['origin', 'timeout', 'name']);
 /** Splits off the options given before the command: [those options, the command, everything after it]. */
 function splitCommand(argv) {
     let index = 0;
@@ -147,6 +182,22 @@ export function parseArgs(argv, env = {}) {
         if (positional.length)
             throw new UsageError(`${first} takes no “${positional[0]}”.`);
     };
+    /** `--name`, cleaned up as Pending You keeps it; none when it isn't given. */
+    const machine = () => {
+        const given = text('name');
+        if (given === undefined)
+            return {};
+        const name = cleanName(given);
+        if (!name)
+            throw new UsageError('--name needs a name for this computer, like: --name devbox');
+        return { machine: name };
+    };
+    /** `--device` or `--browser`, or neither (null: decided by looking). */
+    const device = () => {
+        if (flags.has('device') && flags.has('browser'))
+            throw new UsageError('Use --device or --browser, not both.');
+        return flags.has('device') ? true : flags.has('browser') ? false : null;
+    };
     switch (first) {
         case 'help':
             return { name: 'help' };
@@ -159,7 +210,8 @@ export function parseArgs(argv, env = {}) {
                 origin,
                 browser: !flags.has('no-browser'),
                 force: flags.has('force'),
-                device: flags.has('device'),
+                device: device(),
+                ...machine(),
             };
         case 'logout':
             none();
@@ -183,6 +235,10 @@ export function parseArgs(argv, env = {}) {
         case 'refresh':
             none();
             return { name: 'refresh', origin, force: flags.has('force') };
+        // Not in USAGE: what Claude Code's headersHelper runs on a computer with no browser (remote.ts).
+        case 'mcp-headers':
+            none();
+            return { name: 'mcp-headers', origin, check: flags.has('check') };
         case 'init':
             none();
             return {
@@ -190,8 +246,9 @@ export function parseArgs(argv, env = {}) {
                 origin,
                 login: !flags.has('no-login'),
                 browser: !flags.has('no-browser'),
-                device: flags.has('device'),
+                device: device(),
                 yes: flags.has('yes'),
+                ...machine(),
             };
         case 'watch':
             none();
@@ -216,21 +273,28 @@ export function parseArgs(argv, env = {}) {
 export const USAGE = `pendingyou: Pending You for Claude Code
 
   npx pendingyou init          Set up Claude Code on this computer: the MCP server, the skill,
-                               this command's sign-in, and three hooks (answers, and a check
-                               that what Claude Code leaves you in chat is also in Pending You)
+                               this command's sign-in, three hooks (answers, and a check that
+                               what Claude Code leaves you in chat is also in Pending You), and
+                               on Claude Code 2.1.287 or later the wake mod, which wakes a
+                               session when you answer. Over SSH, or on Linux with no display,
+                               you approve one code on your phone and Claude Code signs in
+                               through this computer's sign-in: no browser needed
   npx pendingyou hold <req_…>  Wait in the background until the answer to a request is ready,
-                               print it, and exit (which wakes Claude Code)
+                               print it, and exit (which wakes Claude Code); with the wake mod,
+                               the mod answers it and nothing runs
   npx pendingyou status        What's set up, and whether Claude Code hears answers right away
-  npx pendingyou login [--device] | logout
-                               --device: on a computer with no browser, approve a short code on your phone
+  npx pendingyou login [--device | --browser] | logout
+                               --device: on a computer with no browser, approve a short code on your
+                               phone (the default over SSH); --browser: sign in in this computer's browser
   npx pendingyou watch -- <command> [args…]
                                Run a command each time an answer is ready (always-on scripts)
   npx pendingyou uninstall     Remove exactly what init added
   npx pendingyou pickup        Answers waiting for this folder (the session-start hook)
-  npx pendingyou handoff       The same, only while a hold is outstanding (the next-message hook)
+  npx pendingyou handoff       The same, with your next message (the next-message hook)
   npx pendingyou stopcheck     Questions or steps for you left only in chat (the Stop hook)
 
-Options: --origin <url> (default ${DEFAULT_ORIGIN}), --timeout 4h (hold), --no-browser and --device (login,
-init), --no-login (init), --yes (init: replace a pendingyou MCP server that points elsewhere without asking),
---all (logout), --force (login), --once (watch).
+Options: --origin <url> (default ${DEFAULT_ORIGIN}), --timeout 4h (hold), --no-browser, --device and --browser
+(login, init), --name <name> (login, init: what to call this computer when it signs in with a code; by default its
+Tailscale name, else its hostname), --no-login (init), --yes (init: replace a pendingyou MCP server that points
+elsewhere without asking), --all (logout), --force (login), --once (watch).
 `;