pendingyou 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,11 +1,73 @@
 # Changelog
 
+## 0.14.0 (2026-10-05)
+
+- Questions your person hands one of your agents from another assistant (Delegate: Pending You's card link, or D on the
+  desk). Once the delegation's 5-second hold is over, Pending You's `/mcp/cli/answers` brings such a question to the
+  app's sign-in, marked `delegated` (who asked, `freely` or `loop`, the person's note), under the name the helper
+  answers with (`sessionLabel`, the task the person picked) and in that task's folder (`cwd`). The hooks used to say
+  “Pending You: they wrote back on req_…”; now a session start or message says “Pending You: your person handed you
+  req_…, a question from billing-webhooks (answer freely: your answer goes straight to billing-webhooks).”, the
+  question, “Their note: “…””, and “Call get_request (requestId req_…, name “infra”) to read it. If you know,
+  answer_delegated with your answer and how you know; if not, hand_back with what you checked.” (“they’ll see your
+  answer first” when the person kept themselves in the loop). The header says “your person handed you a question from
+  another assistant” (or “answered, and handed you …”), never “your person answered”, and the line to tell the person
+  first is “You handed me a question from …”.
+- Which session hears one (`src/handed.ts`), the same for every app: a session that goes by its name in its folder
+  (the task the person picked; the most recent of several), else the session in that folder that used Pending You
+  most recently, never the one that asked it (a session that goes by the asking assistant's name), and never two: the
+  session that takes it claims it first in `state.json` (`claimHanded`), and gives it back if it couldn't be told. A
+  question with no folder (a task that never said one) goes to a session by its name anywhere, else the app's most
+  recent. A sign-in that only hears (`--oauth`) hears every computer's questions, so it leaves one whose `machine`
+  (the computer Pending You says it went to, as the Assistants page names it) is another computer than this one, by
+  its name or its hostname (the hostname, the names its code sign-ins were given, a Mac's own name, and, outside a
+  hook, Tailscale's); one with no `machine` goes by the folder. The hooks hand a session one at once when it goes by that name (or it's the session the listeners would
+  wake); another session in the folder only after 5 minutes, so the one it went to hears it first.
+- Claude Code's wake mod wakes the session it's for: while a session used Pending You in the last 12 hours (as long as
+  Pending You offers its task as running), it asks `list_pending` with the session's name every minute for the first
+  half hour, then every 3 minutes; reads each new one with `get_request` (who asked, how its answer travels, whether
+  there's a note); and starts one turn, “Pending You: your person handed you “…” (req_…), a question from … Call
+  get_request (requestId req_…, name “infra”) to read it and their note. If you know, answer_delegated …; if not,
+  hand_back …”, never with the note. It claims each in its store (`handed:<requestId>`), so another session by the same
+  name doesn't hear it too, and never wakes a session for one it read or answered itself. Among sessions by one name,
+  the one working in the folder of the task it went to (`list_pending`'s `cwd`: the folder the session started in, or
+  one it gave its own cards, `~/…` or full) takes it, one elsewhere never does, and one that can't tell its folder
+  waits 5 minutes. The hand-off hook that
+  runs for the mod's prompt claims it in `state.json` without saying it twice. `answer_delegated` and `hand_back` are
+  among the calls it reads. Regenerated into the plugin's builds too, which reach installed plugins with the next guide
+  release.
+- Codex: one listener for the app, `pendingyou listen --app codex --handed` (detached, a lease of its own), started by
+  the hooks while any thread may be handed a question, `codex queue`s each into the thread it's for, in the wake mod's
+  words, and gives it back (forgetting the thread) when Codex doesn't know the thread. Codex's hooks now remember each
+  thread's names and folder (`codex-threads.json`), and keep a thread for 12 hours after it last used the card tools,
+  with no card of its own waiting; a session start or message marks it active. A thread's own listener is never woken
+  for its own card while it's with another assistant.
+- OpenCode and Pi: a session's listener also wakes it for a question handed to it, and keeps listening for one for 12
+  hours after the session last used the card tools (`opencode-threads.json`, `pi-threads.json`), while the app is
+  open. OpenCode's plugin starts it with each message while the record says so, and passes the session's folder to
+  `posted`; Pi's extension starts it as before, now for that too. Both start a listener again when a card call asked for
+  one while the last was on its way out: a card posted just as a session's first listener stopped (finding nothing to
+  listen for) went unheard until the next message.
+- `watch` names a handed question's event `delegated_ready` (`PENDINGYOU_EVENT`), with `delegated` in the JSON on
+  stdin.
+- The Stop check never asks a helper to post the question as a card of its own. `answer_delegated` and `hand_back`
+  count as the turn's card calls (Claude Code's transcript, OpenCode's turn, Pi's extension); a turn a handed
+  question's wake started (its first message the wake's words: Claude Code's transcript, OpenCode's turn, Pi's extension
+  says `handed`, Codex's next-message hook records it when Codex gives the message) that left the person something in
+  chat without either is asked once: “Your person handed you that question to answer, not to ask them back:
+  answer_delegated if you know, or hand_back with what you checked, unless you already did. Never post it as a card of
+  your own.” Codex's PostToolUse hook is trusted by its exact matcher, which names only the four card tools, so it never
+  sees those two calls (a new matcher would have to be trusted again).
+- The package names no one, and carries only what runs. Its JavaScript is built without the source's comments, and so is
+  the wake mod's (`mod/hooks`); its examples and this changelog use made-up names (`--name build-01`); and the mod's
+  test, which only `claude plugin test` reads, stays out of the package. Nothing the command line does changes.
+
 ## 0.13.0 (2026-10-04)
 
-- Claude Code's permission prompts on a card (Darin, 2026-10-04: "Tell me: a card and a push, cleared once I answer in
-  the terminal"). A Claude Code agent kept asking to remove files and sat waiting until Darin happened to look. `init`
-  now adds Claude Code's PermissionRequest hook (https://code.claude.com/docs/en/hooks: it runs as Claude Code is about
-  to ask for permission to use a tool, with `tool_name` and `tool_input`), through the shim with `--app claude-code`.
+- Claude Code's permission prompts on a card: a card and a push, cleared once you answer in the terminal. A Claude Code
+  agent kept asking to remove files and sat waiting until its person happened to look. `init` now adds Claude Code's
+  PermissionRequest hook (https://code.claude.com/docs/en/hooks: it runs as Claude Code is about to ask for permission
+  to use a tool, with `tool_name` and `tool_input`), through the shim with `--app claude-code`.
   It never decides: it prints nothing, so the prompt shows exactly as before, and it's done in about a tenth of a
   second. It writes the prompt down (its card's redacted words, never the tool's input) in the session's own file,
   `~/.config/pendingyou/permission-cards/<session>.json`, and starts that session's one worker, detached (`pendingyou
@@ -67,8 +129,8 @@
   approve: 1. whoami with your name. If it says app.setUp is true, another session did this: stop. 2. report_setup with
   source codex, your name, skillSaved true, hears instant, and skillVersion set to whoami’s skill.latest. Its answer
   has a testAreaId. 3. post_request a short test question in that testAreaId, tell your person it’s on its way, and end
-  your turn: you’re woken when they answer, so don’t ask them to type anything.” Pi's first setup on Darin's devbox
-  spent about 20,000 tokens on the words before: “whoami with your name and guide true” answered with the whole guide
+  your turn: you’re woken when they answer, so don’t ask them to type anything.” Pi's first live setup spent about
+  20,000 tokens on the words before: “whoami with your name and guide true” answered with the whole guide
   (87,000 characters), which Pi cut into a file the model then parsed, and “your test question in its testAreaId” sent
   it looking for testAreaId in whoami's answer, where it isn't (report_setup's has it). A setup that has reported gets
   the same calls without whoami's way out (its whoami says app.setUp is true); a test card answered says who picks it
@@ -144,7 +206,7 @@
 
 ## 0.11.0
 
-- One step for the coding agents on a computer (Darin, 2026-10-04): `npx -y pendingyou@latest init` finds Claude Code
+- One step for the coding agents on a computer: `npx -y pendingyou@latest init` finds Claude Code
   and Codex (`--app claude-code,codex` names some), says what it found and which it can't set up (an agent too old for
   it is named, with the version it needs), and sets each up with one approval. Then: restart the agent, and its first
   session finishes setting up by itself (whoami, report_setup, a test card). Asked for by name and not installed, or
@@ -222,10 +284,10 @@
 - 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.
+- A computer with no browser (a 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
+  browser) signs the machine in by code as a Claude Code connection of its own ("Claude Code on build-01" 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
@@ -239,8 +301,8 @@
   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
+  build-01 hear your answers for the assistants running on it?"; in the browser, "Let this computer hear…". Neither
+  offers a choice of assistant any more: 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

package/README.md

@@ -27,7 +27,8 @@ Run it once on each computer, in a terminal. It finds the agents on the computer
   in chat ([below](#nothing-left-only-in-chat)); and, for Claude Code, a card when it waits for your OK to run something
   ([below](#when-claude-code-waits-for-your-ok)),
 - and wakes it when you answer: Claude Code 2.1.287 or later through the wake mod, Codex through `codex queue`, OpenCode
-  through its plugin and Pi through its extension (which also do the hooks' work there).
+  through its plugin and Pi through its extension (which also do the hooks' work there); and when you hand it a
+  question from another of your assistants ([below](#when-you-hand-an-agent-a-question)).
 
 Then it says what to do next, and the one sentence to say if it's needed:
 
@@ -111,7 +112,8 @@ it with `codex queue`: “Pending You: your person answered “…” (req_…).
 answer itself never goes in a command's arguments, where other programs could see it). Codex starts a turn at
 once when the thread is open and idle, after the current one when it's working, or when you next open it. In the Codex
 app, a chat it has open is woken while the app runs (one it let go, idle 3 hours or behind 10 newer idle chats, when
-you open it again).
+you open it again). One more listener, for the whole app, queues a question you hand a thread from another assistant
+([below](#when-you-hand-an-agent-a-question)).
 
 ## OpenCode
 
@@ -139,7 +141,8 @@ does in OpenCode what the hooks do elsewhere, through the same hooks' script: ea
 reminder and any answer waiting (hidden in OpenCode's view, read by the model), a session's first message also says
 what setup has left, a session that left you a question in chat is asked once to put it on a card (with a toast saying
 why), and when you answer a card a session posted, the plugin starts a turn in that session: “Pending You: your person
-answered “…” (req_…). Call get_request …” (never the answer itself). That works while OpenCode is open, idle or busy.
+answered “…” (req_…). Call get_request …” (never the answer itself). That works while OpenCode is open, idle or busy,
+and for a question you hand the session from another assistant too ([below](#when-you-hand-an-agent-a-question)).
 
 Then restart OpenCode (`/exit`, then `opencode --continue`): it finishes setting up the first time you write to it.
 
@@ -167,7 +170,9 @@ Pi has no hooks, so `init` gives it an extension: `~/.config/pendingyou/pi/pendi
 the same hooks' script as a session starts, with each message, after Pending You's card tools and as a run ends (a run
 that leaves you something only in chat goes on once), and when you answer a card a session posted it starts a turn in
 that session, idle or busy: “Pending You: your person answered “…” (req_…). Call get_request …” (never the answer
-itself). In Pi's terminal the first session finishes setting up by itself, once Pending You's tools are there.
+itself), and the same for a question you hand it from another assistant
+([below](#when-you-hand-an-agent-a-question)). In Pi's terminal the first session finishes setting up by itself, once
+Pending You's tools are there.
 
 Then run `/reload` in each Pi session that's open, or start `pi`. Pi's shell waits for a command to end, so in Pi
 `npx pendingyou hold` answers at once instead of waiting.
@@ -208,6 +213,13 @@ replied on a card comes from Codex's own hook for Pending You's tools in that tu
 action card titled “Confirm in Codex on <computer>: <step>” when it asked you to type something there. OpenCode's plugin
 and Pi's extension (0.12.0) do the same in theirs.
 
+A question you hand an agent from another assistant (0.14.0) is never asked to go on a card of its own: answering it
+(`answer_delegated`) or giving it back (`hand_back`) puts it in front of you, so it counts as the turn's card call. A
+turn that such a question started, and that left you something in chat without doing either, is asked once to answer
+it or hand it back instead (about 45 tokens). Codex's hook for Pending You's tools is trusted by its exact list of
+tools, which doesn't name those two, so there the check knows only that the turn started with one (when Codex gives the
+message to its next-message hook), and says “unless you already did”.
+
 **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).
 
@@ -269,10 +281,38 @@ allowed and the server has connected). When it isn't, it starts one turn once th
 Pending You: it’s connected here already.” and exactly what to do. Once per session, in at most three sessions, never
 two within ten minutes, and never again once Pending You says it's set up.
 
+## When you hand an agent a question
+
+In Pending You you can hand a card to another of your assistants, a coding task included (Delegate: the card's link,
+or D on the desk): it answers for you (“Answer freely”), or its answer comes back to you first (“Keep me in the loop”),
+or it hands the card back with what it checked. Since 0.14.0 the task you picked hears it the way it hears your
+answers, once the 5-second window to undo is over:
+
+- **Which session**: the one that goes by the task's name in its folder (the most recent, when several do); else the
+  session in that folder that used Pending You most recently; never the one that asked, and never two. A sign-in that
+  only hears (`--oauth`) hears every computer's, so it leaves one Pending You says went to another computer (by its
+  name or its hostname); one that names no computer goes by the folder.
+- **Claude Code**: the wake mod looks for questions handed to the session's name (`list_pending`, every minute while
+  the session used Pending You in the last half hour, then every 3 minutes, for 12 hours), reads each with
+  `get_request`, and starts a turn: “Pending You: your person handed you “Which AWS account for staging?” (req_…), a
+  question from billing-webhooks (answer freely: your answer goes straight to billing-webhooks). Call get_request
+  (requestId req_…, name “infra”) to read it and their note. If you know, answer_delegated with your answer and how you
+  know; if not, hand_back with what you checked.” Among sessions by one name, the one working in the task's folder
+  takes it (as `list_pending` gives it, `~/…` or a full path), one in another folder never does, and one that can't
+  tell its folder waits 5 minutes.
+- **Codex**: one listener for the app queues it into the thread it's for (`codex queue`, the same words).
+- **OpenCode and Pi**: the session's listener starts the turn through the plugin or extension; a session that used
+  Pending You's card tools keeps listening for 12 hours, while the app is open.
+- **Otherwise**: a session start or your next message in that folder brings it, with your note: at once in the
+  session that goes by the task's name, after 5 minutes in any other.
+
+Your note never goes in a program's arguments, where any other program on the computer could read it: the agent reads
+it with `get_request`.
+
 ## A computer with no browser
 
-On a devbox or server you reach over SSH, an agent's own sign-in opens a browser on that machine, which you can't
-reach. `init` signs in with a code there instead: SSH in, and at the prompt there run
+On a computer you reach over SSH (a build server, a machine in the cloud), an agent's own sign-in opens a browser on
+that machine, which you can't reach. `init` signs in with a code there instead: SSH in, and at the prompt there run
 
 ```sh
 npx -y pendingyou@latest init
@@ -289,15 +329,15 @@ hooks find Node anyway when the agents run without your shell's PATH (a systemd
 Remote Control): on PATH, nvm's default, the one `init` ran with, or where Node usually is.
 
 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 Mac by its own name (Sharing in System Settings). 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:
+else by its hostname, or by `--name build-01` on `init` or `login`; a Mac by its own name (Sharing in System Settings).
+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 and renames the connection, which stays the same one.
 If an agent's sign-in ends (30 days, or you remove it on your Assistants page), `npx pendingyou login` (`--app codex`
 for Codex's) approves a new code and keeps the same connection.
 
 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.
+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.
 
 ## Always-on scripts
 
@@ -309,10 +349,11 @@ npx pendingyou watch -- ./on-answer.sh
 
 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.
+one. The command runs without a shell, once per answer, message or fallback that comes due, or (0.14.0) question you
+hand the assistant from another one, oldest first. It gets the request as JSON on stdin (a handed question with
+`delegated`: who asked, how its answer travels, your note), and `PENDINGYOU_REQUEST_ID`, `PENDINGYOU_EVENT`
+(`answer_ready`, `message_ready`, `fallback_due` or `delegated_ready`), `PENDINGYOU_VERSION` and `PENDINGYOU_ORIGIN` in
+its environment. A failing command is tried twice more, then skipped. `--once` stops after the first.
 
 ## Commands
 
@@ -349,20 +390,24 @@ reminded an unfinished setup, and when; `permission-cards/` each Claude Code ses
 and its card (ids, hashes and the card's redacted words: never what the tool was given), gone once nothing waits;
 `claude-code.json`, `codex.json`, `opencode.json` and `pi.json` what `init`
 added; `codex-threads.json`, `opencode-threads.json` and `pi-threads.json` which cards each Codex thread or OpenCode or
-Pi session waits on (ids, names and titles: never an answer); `pi/` Pi's extension; and `cli/` the hooks' copy of the
+Pi session waits on, and (0.14.0) the names it went by and its folder, kept 12 hours for a question you may hand it
+(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. For a permission prompt's card, the worker reads
+whether the agent has a `pendingyou` MCP server and where it points. 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
 get-url origin` in its folder (sent without any user name or password in it). Nothing is sent anywhere but Pending
 You. OpenCode's plugin reads its session's messages only when it goes idle, for the check that
 nothing was left in chat, and hands the hooks' script just that turn's words and tool names.
 
 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 (and, in `init`'s copy, `whoami` to see whether setup is finished). 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`).
+`get_request` on the session's own cards (and, in `init`'s copy, `whoami` to see whether setup is finished), and (0.14.0)
+`list_pending` with the session's name and `get_request` on a question you handed it. It keeps each session's cards (id,
+title, the agent's name, where each stands), and which handed questions a session was told of (ids and when), 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
 

package/dist/api.js

@@ -1,32 +1,11 @@
-// Calls to Pending You with the command line's sign-in: a fresh access token (refreshed under the credentials lock,
-// so a hold and a hook never spend the same refresh token), one retry after a 401, and plain errors.
-//
-// Hooks never refresh in their own process. A hook has a hard deadline (main.ts), and a refresh cut off halfway can
-// end the sign-in: the server rotates the refresh token as it answers, and keeps exactly one earlier token valid
-// (@cloudflare/workers-oauth-provider's previousRefreshTokenId). A refresh abandoned before its answer arrives is
-// harmless on its own (the stored token is that earlier one, and still works), but if the server finishes it after a
-// later refresh has stored a newer token, that newer token stops working and the next refresh gets invalid_grant. So
-// a hook that needs a new token starts `pendingyou refresh` detached (background), which runs to the end under the
-// lock whatever happens to the hook, and waits for it only briefly; until it lands the hook uses the token it has, or
-// gives up and prints its plain fallback.
-//
-// Since 0.11.0 each app has its own sign-in (credentials.ts), and every call names the app it's for: its sign-in is
-// the one used, and a session's request names it as `source` (routing by sender, 2026-10-04), so Pending You returns
-// only that app's cards, never one Codex posted from the same folder to a Claude Code session there. `watch` names no
-// app: it hands answers to a script, not a session, with Claude Code's sign-in as before.
 import { DEFAULT_APP } from "./apps/ids.js";
 import { credentialsPath, readCredential, updateCredential, } from "./credentials.js";
 import { isLocked } from "./files.js";
 import { OAuthError, refresh } from "./oauth.js";
-/** 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. */
 export const SOON_MS = 5 * 60_000;
-/** How long a hook waits for a background refresh when it has no working token. */
 export const REFRESH_WAIT_MS = 1200;
-/** An access token with less than this left isn't worth sending. */
 const USABLE_MS = 10_000;
-/** Not signed in on this computer (for this origin), or the sign-in ended: the person runs `pendingyou login`. */
 export class SignInNeeded extends Error {
     name = 'SignInNeeded';
     ended;
@@ -35,26 +14,19 @@ export class SignInNeeded extends Error {
         this.ended = ended;
     }
 }
-/** Pending You couldn't be reached, or had a problem: worth trying again later. */
 export class Unavailable extends Error {
     name = 'Unavailable';
-    /** Seconds the server asked to wait, when it said. */
     retryAfter;
     constructor(message, retryAfter) {
         super(message);
         this.retryAfter = retryAfter;
     }
 }
-/**
- * Refreshes the sign-in under the lock unless it no longer needs it: a token with more than `earlyMs` left (or, when
- * `force`d after a 401, a refresh token another process already replaced) is used as it is.
- */
 async function refreshStored(io, origin, stored, options, app) {
     let ended = false;
     const updated = await updateCredential(io, origin, async (current) => {
         if (!current)
             return null;
-        // Another process may have refreshed while this one waited for the lock.
         if (current.refreshToken !== stored.refreshToken && current.expiresAt - EARLY_MS > io.now())
             return current;
         if (!options.force && current.expiresAt - options.earlyMs > io.now())
@@ -84,7 +56,6 @@ async function freshToken(io, origin, force, app) {
         return stored.accessToken;
     return (await refreshStored(io, origin, stored, { force, earlyMs: EARLY_MS }, app)).accessToken;
 }
-/** What a process starts to refresh an app's sign-in in the background: `--app` only for an app but Claude Code. */
 export const refreshArgs = (origin, app, force = false) => [
     'refresh',
     '--origin',
@@ -92,10 +63,6 @@ export const refreshArgs = (origin, app, force = false) => [
     ...(app === DEFAULT_APP ? [] : ['--app', app]),
     ...(force ? ['--force'] : []),
 ];
-/**
- * `pendingyou refresh`, what a hook starts in the background: refreshes the sign-in when it runs out within SOON_MS
- * (or `force`, after a 401), under the lock, to the end. Quiet; true when there's a sign-in afterwards.
- */
 export async function refreshInBackground(io, origin, force, app = DEFAULT_APP) {
     const stored = await readCredential(io, origin, app);
     if (!stored)
@@ -105,7 +72,6 @@ export async function refreshInBackground(io, origin, force, app = DEFAULT_APP)
     await refreshStored(io, origin, stored, { force, earlyMs: SOON_MS }, app);
     return true;
 }
-/** A hook's token: never refreshed here (see the top of this file). */
 async function hookToken(io, origin, force, signal, app) {
     const stored = await readCredential(io, origin, app);
     if (!stored)
@@ -113,10 +79,8 @@ async function hookToken(io, origin, force, signal, app) {
     const left = stored.expiresAt - io.now();
     if (!force && left > SOON_MS)
         return stored.accessToken;
-    // One refresher at a time: a lock held now is a refresh (or a write) already under way.
     if (!(await isLocked(credentialsPath(io))))
         io.background(refreshArgs(origin, app, force));
-    // Still good for a few seconds: this request goes with it, the next one with the new token.
     if (!force && left > USABLE_MS)
         return stored.accessToken;
     const until = io.now() + REFRESH_WAIT_MS;
@@ -130,14 +94,6 @@ async function hookToken(io, origin, force, signal, app) {
     }
     throw new Unavailable('The sign-in is being refreshed in the background.');
 }
-/**
- * The token `pendingyou mcp-headers` hands an app's MCP server (remote.ts), and the stdio bridge sends with each
- * message (bridge.ts). The app runs the helper each time it connects and gives it 10 seconds, and the bridge may be
- * stopped at any moment, 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; the app runs the helper again on a 401. `force` (the bridge,
- * after a 401) refreshes whatever the expiry says, and hands over only the new token.
- */
 export async function helperToken(io, origin, waitMs, app = DEFAULT_APP, force = false) {
     const stored = await readCredential(io, origin, app);
     if (!stored)
@@ -159,7 +115,6 @@ export async function helperToken(io, origin, waitMs, app = DEFAULT_APP, force =
         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);
     if (!signal)
@@ -172,11 +127,6 @@ function either(signal, ms) {
     timeout.addEventListener('abort', abort, { once: true });
     return controller.signal;
 }
-/**
- * GETs `path` on `origin` as the command line, with an app's sign-in (Claude Code's unless `app` says), and returns the
- * JSON body with its status. 401 after a refresh means the sign-in is over (revoked, or 30 days passed). Network
- * failures and 5xx are `Unavailable`.
- */
 export async function getJson(io, origin, path, timeoutMs, signal, options = {}) {
     const app = options.app ?? DEFAULT_APP;
     for (let attempt = 0;; attempt++) {

package/dist/apps/claude-code.js

@@ -1,16 +1,3 @@
-// Claude Code (0.11.0's module of what claude.ts carries out): what `pendingyou init` decides before anyone signs in,
-// what it does after, `status`'s section and the lines init ends with.
-//
-// Its MCP server signs in through this computer's own connection ("Claude Code on devbox"), by the headers helper, on
-// every computer but Windows (where Claude Code runs a headersHelper through cmd) or with `--oauth`; the hooks use the
-// same connection, so one approval covers both. A pendingyou server that's there decides the rest, before signing in:
-// - ours, through the helper, at this Pending You: kept.
-// - one at this Pending You that signs in by itself (Claude Code's own /mcp → Authenticate), or no server beside an
-//   enabled Pending You plugin for it (whose server is OAuth): with no browser here it's switched without a word (as
-//   0.10.0 did: that sign-in can't finish here); at a terminal init asks, Yes by default; `--yes` switches; with nobody
-//   to ask it's kept, and init says how to switch. Kept, Claude Code signs in by itself and the hooks get a sign-in
-//   that only hears; kept beside the plugin, no skill is saved either: the plugin carries it.
-// - one at another Pending You: replaced once the person says so (or `--yes`), or else Claude Code is left alone.
 import { addCommand, claudeState, helperServer, installClaude, mcpFromClaude, mcpFromFile, PLUGIN_ORIGINS, permissionBlocker, pluginFor, readManifest, removeCommand, sameUrl, uninstallClaude, } from "../claude.js";
 import { connectionMachine, readCredential } from "../credentials.js";
 import { differs, serverForFolder, siteOf } from "../environment.js";
@@ -21,12 +8,7 @@ import { connectionTitle, FINISH_SAY, setupOf, setupStatus } from "../setup.js";
 import { shimPath } from "../shim.js";
 import { APP_NAMES } from "./ids.js";
 const NAME = APP_NAMES['claude-code'];
-/** The sentence's lead-in, and what restarting means, in init's last lines. */
 const RESTART = 'restart Claude Code here (/exit, then claude --continue), or start it in the folder you work in';
-/**
- * Whether to move a server that signs in by itself to this computer's sign-in: without a word where there's no
- * browser, `--yes`, or Yes (the default) at a terminal; kept, with nobody to ask.
- */
 async function switches(io, ctx, what) {
     if (ctx.headless || ctx.yes)
         return true;
@@ -36,7 +18,6 @@ async function switches(io, ctx, what) {
     const answer = await io.ask('Switch Claude Code to this computer’s sign-in? [Y/n] ');
     return !/^\s*no?\s*$/i.test(answer);
 }
-/** The plan for a server at another Pending You: replaced once the person says so, or Claude Code left alone. */
 async function replaces(io, ctx, server, url) {
     ctx.progress(`Claude Code’s pendingyou MCP server points at ${server.url}, not ${url}.\n`);
     if (ctx.yes)
@@ -92,7 +73,6 @@ export const claudeCode = {
             };
         }
         else if (server?.url && !sameUrl(server.url, url)) {
-            // Another Pending You (staging, when production was asked for): asked before anyone signs in.
             if (!(await replaces(io, ctx, server, url))) {
                 const commands = `  ${removeCommand(server.scope)}\n    ${add}`;
                 return {
@@ -123,7 +103,6 @@ export const claudeCode = {
             else if (ours)
                 plan = { action: 'switch', server };
             else if (server.helper) {
-                // Someone else's headersHelper: theirs to change. The hooks hear through a sign-in of their own.
                 mode = 'oauth';
                 plan = helperMode
                     ? {
@@ -152,7 +131,6 @@ export const claudeCode = {
             }
         }
         else if (plugin) {
-            // No server added by hand, so the Pending You plugin's is Claude Code's: one added by hand would win over it.
             if (helperMode &&
                 (await switches(io, ctx, 'The Pending You plugin signs Claude Code in to Pending You by itself here.')))
                 plan = { action: 'add', plugin: true };
@@ -224,10 +202,6 @@ export const claudeCode = {
         return claudeStatus(io, ctx);
     },
 };
-/**
- * status's line for the permission-prompt hooks (0.13.0): on; off, as the person chose; or why Claude Code here can't
- * have them. Never a reason status isn't Ready.
- */
 function permissionLine(io, claude, manifest, helper, flag) {
     const label = 'Permission prompts:';
     if (claude.permission)
@@ -241,7 +215,6 @@ function permissionLine(io, claude, manifest, helper, flag) {
         ? `          ${label} no card when Claude Code waits for your OK: ${blocker}`
         : `  missing ${label} no card when Claude Code waits for your OK; run npx pendingyou@latest init${flag}`;
 }
-/** Claude Code's section of `pendingyou status`: what's set up and what's missing, each with the command that fixes it. */
 async function claudeStatus(io, ctx) {
     const { origin, signIn } = ctx;
     const [claude, here, manifest] = await Promise.all([
@@ -252,8 +225,6 @@ async function claudeStatus(io, ctx) {
     const credential = await readCredential(io, origin);
     const flag = originArgs(origin);
     const mcp = claude.mcp;
-    // Through the helper (this computer's own sign-in): Claude Code's server runs ours, init set it up so, or nothing is
-    // set up yet and init would (everywhere but Windows).
     const helped = usesHelper(mcp, origin);
     const helper = io.platform !== 'win32' &&
         (helped ||
@@ -267,7 +238,6 @@ async function claudeStatus(io, ctx) {
     const url = `${origin}/mcp`;
     const plugin = claude.plugins.find((id) => siteOf(PLUGIN_ORIGINS[id] ?? '') === siteOf(origin));
     const sameServer = mcp !== false && mcp !== 'unknown' && (!mcp.url || mcp.url.replace(/\/+$/, '') === url);
-    // The plugin's server is Claude Code's when nobody added one by hand.
     const pluginServer = mcp === false && Boolean(plugin);
     const mcpOk = helper ? sameServer && helped : sameServer || pluginServer;
     const mcpText = mcp === 'unknown'
@@ -287,7 +257,6 @@ async function claudeStatus(io, ctx) {
                                 : `pendingyou (${mcp.url}) signs in through a browser${why ? ', which can’t finish on this computer' : ''}; run npx pendingyou init${flag}`;
     const form = claude.form;
     const hooksRun = form?.runs ?? true;
-    // The wake mod (0.10.0): Claude Code 2.1.287 or later loads it from the plugin or from CLAUDE_CODE_PLUGIN_DIRS.
     const mod = claude.mod;
     const modOk = mod.loads && (mod.plugin || mod.present);
     const modText = !claude.claude
@@ -311,9 +280,7 @@ async function claudeStatus(io, ctx) {
             : form.form === 'npx'
                 ? `they run through npx${via}, which is slower; run npx pendingyou@latest init${flag} to run them directly`
                 : 'they run pendingyou from PATH or a file of your own';
-    // login makes a connection only once Claude Code's server signs in through the helper; init does both.
     const fix = `npx pendingyou ${helped ? 'login' : 'init'}${flag}`;
-    // The connection's name as Pending You has it, so status never drifts from it; else this computer's own record.
     const title = signIn.state === 'ok' && signIn.for
         ? connectionTitle(signIn.for)
         : `${NAME} on ${(await connectionMachine(io, origin)) ?? (machineOf(io.host) || 'this computer')}`;
@@ -338,7 +305,6 @@ async function claudeStatus(io, ctx) {
                 : signIn.state === 'none'
                     ? `not signed in; run npx pendingyou login${flag}`
                     : 'Pending You couldn’t be reached';
-    // The helper as Claude Code runs it at its barest: found Node, and runs pendingyou's copy.
     const check = helper ? await checkHelper(io, origin) : null;
     const skillOk = claude.skill || Boolean(plugin);
     const skillText = claude.skill
@@ -357,17 +323,13 @@ async function claudeStatus(io, ctx) {
             `  ok      Plugin: ${plugin} is enabled${pluginServer ? '' : mcp !== false && mcp !== 'unknown' ? '; Claude Code uses the server added by hand instead of its own' : ''}`,
         ]
         : []), `  ${mark(skillOk)} Skill: ${skillText}`, `  ${mark(claude.hooks && hooksRun)} Hooks: ${claude.hooks ? `session-start pickup and next-message hand-off; ${formText}` : `not installed; run npx pendingyou init${flag}`}`, `  ${mark(claude.stopcheck)} Stop check: ${claude.stopcheck ? 'asks Claude Code to post what it leaves you in chat' : `not installed; run npx pendingyou init${flag}`}`, `  ${mark(modOk)} Wake mod: ${modText}`, permissionLine(io, claude, manifest, helper, flag));
-    // How setup stands on Pending You (from servers that say): never a reason it isn't Ready.
     const setup = setupStatus(NAME, signIn.state === 'ok' ? setupOf(signIn.for) : null);
     if (setup)
         lines.push(`  ${setup === 'finished' ? 'ok     ' : '       '} Setup: ${setup}`);
-    // A folder's own server (local or project scope) wins over the user one in Claude Code: say when it's elsewhere. (The
-    // plugin's server counts only when no server was added by hand, and is production's.)
     if (here && (here.scope === 'local' || here.scope === 'project') && differs(here, origin))
         lines.push(`  ${mark(false)} This folder: its ${here.scope}-scope pendingyou MCP server (${here.url}) is another Pending You than ${origin}; Claude Code uses it here instead`);
     const user = mcp !== false && mcp !== 'unknown' && mcp.url ? { url: mcp.url, scope: 'user' } : null;
     const other = differs(here, origin) ? here : differs(user, origin) ? user : null;
-    // Through the helper, Claude Code reaches Pending You only with the helper, the connection and the server together.
     const reaches = !helper || (signOk && mcpOk && check?.ok === true);
     const ready = reaches && signIn.state === 'ok' && claude.hooks && hooksRun && !other;
     if (other)

package/dist/apps/codex-app.js

@@ -1,32 +1,14 @@
-// The Codex app for macOS (0.13.0; research 2026-10-04): "ChatGPT.app" (bundle id com.openai.codex; 26.928 carries codex
-// 0.159.2) has its own codex command line inside it, and shares ~/.codex with Codex CLI: its MCP servers (the headers
-// helper too), ~/.agents/skills, ~/.codex/hooks.json and the hooks' trust. Its hooks run with a PATH that ends in its own
-// codex, and its private Codex server reads ~/.codex/queue_1.sqlite every 10 seconds, so `codex queue --thread` wakes a
-// chat the app has loaded while it's open (an idle chat is let go after 3 hours, or behind 10 newer idle ones; then the
-// message waits until the chat is opened again). Where `codex` isn't on PATH, init, status and the listener
-// (codex-wake.ts) run the app's own instead: these paths, in /Applications or ~/Applications, under either name.
 import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
-/** The app's names: the ChatGPT desktop app that carries Codex, and Codex's own, should it ship as that. */
 const APP_NAMES = ['ChatGPT.app', 'Codex.app'];
-/**
- * Where a Codex app keeps its own codex: `Contents/Resources/codex-cli/bin/codex`, and the CodexCLI.app inside it that
- * the app's own code looks for (`codex-cli/CodexCLI.app/Contents/MacOS/codex`), in /Applications, then ~/Applications.
- * `system` is /Applications unless PENDINGYOU_APPLICATIONS_DIR says otherwise (tests: they never look in the real one).
- */
 export function appCodexPaths(home, system = '/Applications') {
     return [system, join(home, 'Applications')].flatMap((root) => APP_NAMES.flatMap((name) => {
         const cli = join(root, name, 'Contents', 'Resources', 'codex-cli');
         return [join(cli, 'bin', 'codex'), join(cli, 'CodexCLI.app', 'Contents', 'MacOS', 'codex')];
     }));
 }
-/** `codex --version`'s version ("codex-cli 0.159.2"), or "installed" when it can't be read. */
 const versionOf = (stdout) => /(\d+\.\d+\.\d+)/.exec(stdout)?.[1] ?? 'installed';
 const executable = (path) => stat(path).then((info) => info.isFile() && (info.mode & 0o111) !== 0, () => false);
-/**
- * The codex to run: `codex` on PATH; else, on a Mac, the Codex app's own (the first of `paths` there that answers
- * `--version`); null when there's neither.
- */
 export async function findCodex(io, paths = appCodexPaths(io.home, io.env.PENDINGYOU_APPLICATIONS_DIR || undefined)) {
     const onPath = await io.run('codex', ['--version'], 20_000);
     if (onPath.code === 0)