pendingyou 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.7.0
+
+- Faster hooks. They ran `npx -y --prefer-offline pendingyou@<version> …`, and npx alone took about half a second
+  (and real CPU) before each one started; sessions starting or resuming together queued on npm's cache lock. `init`
+  now keeps a copy of this version in `~/.config/pendingyou/cli/<version>/` (copied from the package it runs from, or
+  installed with `npm install --prefix`, checked before it's used) and the hooks run it with Node directly:
+  `"<node>" "~/.config/pendingyou/cli/0.7.0/node_modules/pendingyou/dist/cli.js" handoff || true`. A signed-out
+  pickup went from 0.42 s to 0.04 s; a hand-off with its request from 0.77 s to 0.26 s. When the copy can't be made,
+  the hooks keep the npx form. Running `init` again upgrades the copy in place and removes old versions;
+  `uninstall` removes it; `status` says how the hooks run. To switch: `npx pendingyou@latest init`.
+- `init` no longer looks hung: it says before each slow step what it's waiting on ("Adding the pendingyou MCP server
+  to Claude Code (this can take a minute)…"), gives Claude Code 3 minutes, and says plainly if it ran out. It reads
+  the MCP server from `~/.claude.json` (read only) instead of asking `claude mcp get`, which takes a minute, so a
+  server that's already there costs no `claude` call at all.
+- Fixed: `init` kept a `pendingyou` MCP server that pointed at another origin (staging, when you asked for
+  production) and only said "check Claude Code didn't add the MCP server". It now names both addresses and replaces
+  the old one once you say so: asked at the terminal, or `--yes` to replace without asking. With nobody to ask, it
+  prints the two `claude mcp` commands. Then restart Claude Code, run `/mcp` and Authenticate.
+- Everything from 0.6.0 stays: the 3-second deadline (which no longer loses half a second to npx), the background
+  refresh and the Stop check.
+
+## 0.6.0
+
+- Fixed: a hook could run past Claude Code's 10 seconds (`UserPromptSubmit hook … timed out after 10s — output
+  discarded`), mostly when the sign-in needed refreshing, which no time limit covered. Every hook (`pickup`,
+  `handoff`, `stopcheck`) now stops 3 seconds after it starts, printing only its plain fallback (the hand-off's
+  one-line reminder; nothing from the others, so the Stop check lets the turn end) and exiting 0. Requests give up
+  sooner too: 2.5 seconds for `pickup` (was 5), 2 for `handoff` with answers (was 2.5), 1.5 for open cards.
+- A hook never refreshes the sign-in itself. Cut off halfway, a refresh can end the sign-in, so when the access token
+  runs out within 5 minutes a hook starts `pendingyou refresh` in the background, detached, which finishes under the
+  credentials lock however the hook ends (one at a time: none starts while another holds the lock). The hook goes on
+  with the token it has; one that has run out waits up to 1.2 seconds for the new one, then falls back.
+- A refresh now gives up within 20 seconds in all (it could take 35), inside the lock's 30, so a slow one is never
+  taken over while it's still running.
+- The Stop check no longer asks Claude Code to go on over "There's nothing waiting on you" or "no cards from me
+  waiting on you" (a negation before "waiting on you"), or "say if it needs you to download it" (what another agent
+  will say, if it ever does). A message that says nothing needs a card ("No card needed.", "Nothing needs your
+  attention.", "doesn't need a card") is taken at its word, as the Stop reason offers.
+
 ## 0.5.0
 
 - A card with several questions (guide 2.6) prints each answer on its own line when `hold` ends (and when a hook

package/README.md

@@ -15,12 +15,27 @@ Run it once on each computer. It:
 - 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.
+  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).
 
 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.
+
 The hooks never get in your way: if anything goes wrong (no network, not signed in, a bad option), they print nothing
-and let your message through. Running `init` again updates them in place, and adds any a newer version brings.
+and let your message through. Each one stops within 3 seconds whatever happens, with at most its one-line reminder, and
+never refreshes the sign-in itself: when that's due, it starts the refresh in the background, which finishes on its
+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.7.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.
 
 ## Nothing left only in chat
 
@@ -42,7 +57,8 @@ The check is pattern matching on your computer: no model, no network. It reads o
 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".
+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.").
 
 **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).
@@ -91,7 +107,7 @@ 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`) |
+| `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`) |
 | `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`) |
@@ -108,7 +124,9 @@ before or after the command.
 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
-which answers were already handed over (ids only). Nothing is sent anywhere but Pending You.
+which answers were already handed over (ids only), `claude-code.json` what `init` added, and `cli/` the hooks' copy
+of the command line. `init` reads `~/.claude.json` only to see whether Claude Code has a `pendingyou` MCP server and
+where it points. Nothing is sent anywhere but Pending You.
 
 ## Development
 

package/dist/api.js

@@ -1,9 +1,25 @@
 // 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.
-import { readCredential, updateCredential } from "./credentials.js";
+//
+// 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.
+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';
@@ -23,12 +39,11 @@ export class Unavailable extends Error {
         this.retryAfter = retryAfter;
     }
 }
-async function freshToken(io, origin, force) {
-    const stored = await readCredential(io, origin);
-    if (!stored)
-        throw new SignInNeeded(false);
-    if (!force && stored.expiresAt - EARLY_MS > io.now())
-        return stored.accessToken;
+/**
+ * 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) {
     let ended = false;
     const updated = await updateCredential(io, origin, async (current) => {
         if (!current)
@@ -36,6 +51,8 @@ async function freshToken(io, origin, force) {
         // 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())
+            return current;
         try {
             const tokens = await refresh(io, origin, current.clientId, current.refreshToken);
             return { ...current, ...tokens };
@@ -51,7 +68,53 @@ async function freshToken(io, origin, force) {
     });
     if (!updated)
         throw new SignInNeeded(ended);
-    return updated.accessToken;
+    return updated;
+}
+async function freshToken(io, origin, force) {
+    const stored = await readCredential(io, origin);
+    if (!stored)
+        throw new SignInNeeded(false);
+    if (!force && stored.expiresAt - EARLY_MS > io.now())
+        return stored.accessToken;
+    return (await refreshStored(io, origin, stored, { force, earlyMs: EARLY_MS })).accessToken;
+}
+/**
+ * `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) {
+    const stored = await readCredential(io, origin);
+    if (!stored)
+        return false;
+    if (!force && stored.expiresAt - SOON_MS > io.now())
+        return true;
+    await refreshStored(io, origin, stored, { force, earlyMs: SOON_MS });
+    return true;
+}
+/** A hook's token: never refreshed here (see the top of this file). */
+async function hookToken(io, origin, force, signal) {
+    const stored = await readCredential(io, origin);
+    if (!stored)
+        throw new SignInNeeded(false);
+    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(['refresh', '--origin', origin, ...(force ? ['--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;
+    while (io.now() < until && !signal?.aborted) {
+        await io.sleep(50, signal);
+        const current = await readCredential(io, origin);
+        if (!current)
+            throw new SignInNeeded(true);
+        if (current.refreshToken !== stored.refreshToken)
+            return current.accessToken;
+    }
+    throw new Unavailable('The sign-in is being refreshed in the background.');
 }
 /** Aborts on `signal` or after `ms`, whichever comes first (AbortSignal.any needs Node 20.3). */
 function either(signal, ms) {
@@ -70,13 +133,18 @@ function either(signal, ms) {
  * GETs `path` on `origin` as the command line, 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) {
+export async function getJson(io, origin, path, timeoutMs, signal, options = {}) {
     for (let attempt = 0;; attempt++) {
         let token;
         try {
-            token = await freshToken(io, origin, attempt > 0);
+            token =
+                options.hook && io.background
+                    ? await hookToken(io, origin, attempt > 0, signal)
+                    : await freshToken(io, origin, attempt > 0);
         }
         catch (error) {
+            if (error instanceof Unavailable)
+                throw error;
             if (error instanceof SignInNeeded)
                 throw error;
             throw new Unavailable('Pending You couldn’t be reached to refresh the sign-in.');

package/dist/args.js

@@ -49,6 +49,7 @@ const COMMANDS = new Set([
     'init',
     'uninstall',
     'watch',
+    'refresh',
 ]);
 /** Flags each command takes; `true` when the flag takes a value. */
 const FLAGS = {
@@ -61,9 +62,10 @@ const FLAGS = {
     pickup: { origin: true },
     handoff: { origin: true },
     stopcheck: { origin: true },
-    init: { origin: true, 'no-login': false, 'no-browser': false, device: false },
+    init: { origin: true, 'no-login': false, 'no-browser': false, device: false, yes: false },
     uninstall: { origin: true },
     watch: { origin: true, once: false },
+    refresh: { origin: true, force: 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']);
@@ -177,6 +179,10 @@ export function parseArgs(argv, env = {}) {
         case 'uninstall':
             none();
             return { name: 'uninstall', origin };
+        // Not in USAGE: what a hook starts in the background when the sign-in needs refreshing (api.ts).
+        case 'refresh':
+            none();
+            return { name: 'refresh', origin, force: flags.has('force') };
         case 'init':
             none();
             return {
@@ -185,6 +191,7 @@ export function parseArgs(argv, env = {}) {
                 login: !flags.has('no-login'),
                 browser: !flags.has('no-browser'),
                 device: flags.has('device'),
+                yes: flags.has('yes'),
             };
         case 'watch':
             none();
@@ -224,5 +231,6 @@ export const USAGE = `pendingyou: Pending You for Claude Code
   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), --all (logout), --force (login), --once (watch).
+init), --no-login (init), --yes (init: replace a pendingyou MCP server that points elsewhere without asking),
+--all (logout), --force (login), --once (watch).
 `;

package/dist/claude.js

@@ -3,12 +3,17 @@
 // ~/.claude/settings.json. Settings are merged, never replaced: a file that isn't JSON is left alone, entries that
 // aren't ours are never touched, and running init again changes nothing it doesn't need to. What init added is written
 // down in ~/.config/pendingyou/claude-code.json, so uninstall removes exactly that.
+//
+// Since 0.7.0 the hooks run a private copy of this version with Node directly (install.ts), and init asks Claude Code
+// itself as little as it can: `claude mcp get` and `claude mcp add` each take up to a minute or more (Claude Code checks
+// its servers), so the MCP server is looked up in ~/.claude.json first (read only), and init says what it's waiting on.
 import { createHash } from 'node:crypto';
 import { rm, rmdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { DEFAULT_ORIGIN } from "./args.js";
 import { PlainError } from "./errors.js";
 import { claudeDir, configDir, readJson, readText, writeWhole } from "./files.js";
+import { hookForm, hookRuns, installCli, pruneCli, removeCli, shellQuote, } from "./install.js";
 import { VERSION } from "./version.js";
 export const MCP_NAME = 'pendingyou';
 /** The hooks, by Claude Code event, and the command each runs. */
@@ -46,13 +51,15 @@ export function selfCommand(io) {
                 : `node ${quote(io.script)}`;
 }
 /**
- * A hook's command line: the command first, then `--origin` only when it isn't the default. `|| true` keeps the hook
- * from ever blocking the person, even when npx can't fetch the package or the command fails before it starts (Claude
- * Code blocks a message when its UserPromptSubmit hook exits 2, and flags any other non-zero exit).
+ * A hook's command line: the private copy run by Node directly when there is one (`"<node>" "<…/cli.js>"`, both
+ * quoted), otherwise selfCommand; the command first, then `--origin` only when it isn't the default. `|| true` keeps
+ * the hook from ever blocking the person, even when npx can't fetch the package or the command fails before it starts
+ * (Claude Code blocks a message when its UserPromptSubmit hook exits 2, and flags any other non-zero exit).
  */
-export function hookCommand(io, origin, sub) {
+export function hookCommand(io, origin, sub, direct) {
     const flag = origin === DEFAULT_ORIGIN ? '' : ` --origin ${quote(origin)}`;
-    return `${selfCommand(io)} ${sub}${flag} || true`;
+    const self = direct ? `${shellQuote(direct.node)} ${shellQuote(direct.script)}` : selfCommand(io);
+    return `${self} ${sub}${flag} || true`;
 }
 /** Whether a hook command is one of ours: it runs pendingyou's `pickup`, `handoff` or `stopcheck`. */
 export function isOurHook(command, sub) {
@@ -170,39 +177,157 @@ export function unmergeSettings(settings, permissionsAdded) {
     return { settings: next, changed };
 }
 const writeSettings = (io, settings) => writeWhole(settingsPath(io), `${JSON.stringify(settings, null, 2)}\n`);
-/** The MCP server at user scope, unless Claude Code already has one called pendingyou. */
-async function addMcp(io, origin) {
+/** How long Claude Code may take to look up, add or remove an MCP server (it checks each server it has). */
+const MCP_TIMEOUT_MS = 180_000;
+/** Claude Code's own state file: ~/.claude.json, or .claude.json in $CLAUDE_CONFIG_DIR. */
+export const claudeJsonPath = (io) => io.env.CLAUDE_CONFIG_DIR
+    ? join(io.env.CLAUDE_CONFIG_DIR, '.claude.json')
+    : join(io.home, '.claude.json');
+/**
+ * The user-scope pendingyou MCP server, read from ~/.claude.json without asking Claude Code (which takes a minute):
+ * the server, null when there isn't one, or 'unknown' when the file isn't there or isn't the shape expected. Only
+ * mcpServers.pendingyou is looked at; nothing is written.
+ */
+export async function mcpFromFile(io) {
+    let parsed;
+    try {
+        const text = await readText(claudeJsonPath(io));
+        if (text === null)
+            return 'unknown';
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return 'unknown';
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return 'unknown';
+    const servers = parsed.mcpServers;
+    if (servers === undefined)
+        return null;
+    if (typeof servers !== 'object' || servers === null || Array.isArray(servers))
+        return 'unknown';
+    const server = servers[MCP_NAME];
+    if (server === undefined)
+        return null;
+    if (typeof server !== 'object' || server === null)
+        return 'unknown';
+    const url = server.url;
+    return { url: typeof url === 'string' ? url : null, scope: 'user' };
+}
+/** `claude mcp get pendingyou`'s answer: the server, null when there isn't one, 'timeout' when it took too long. */
+async function mcpFromClaude(io) {
+    const result = await io.run('claude', ['mcp', 'get', MCP_NAME], MCP_TIMEOUT_MS);
+    if (result.code === 124)
+        return 'timeout';
+    if (result.code !== 0)
+        return null;
+    const url = /^\s*URL:\s*(\S+)/m.exec(result.stdout)?.[1] ?? null;
+    const scope = /^\s*Scope:\s*(\w+)/m.exec(result.stdout)?.[1]?.toLowerCase();
+    return {
+        url,
+        scope: scope === 'user' || scope === 'local' || scope === 'project' ? scope : null,
+    };
+}
+const sameUrl = (a, b) => a.replace(/\/+$/, '') === b.replace(/\/+$/, '');
+const addCommand = (url) => `claude mcp add --scope user --transport http ${MCP_NAME} ${url}`;
+const removeCommand = (scope) => `claude mcp remove${scope ? ` --scope ${scope}` : ''} ${MCP_NAME}`;
+/**
+ * The MCP server at user scope. One already there pointing at this origin is kept; one pointing elsewhere (staging
+ * when you asked for production) is replaced once you say so: asked at the terminal, `--yes` without asking, or, with
+ * nobody to ask, the two commands are printed.
+ */
+async function addMcp(io, origin, options, progress) {
+    const url = `${origin}/mcp`;
+    let existing = await mcpFromFile(io);
+    if (existing !== 'unknown' && existing?.url && sameUrl(existing.url, url))
+        return {
+            added: false,
+            step: { ok: true, text: `The pendingyou MCP server (${url}) was already in Claude Code.` },
+        };
     const version = await io.run('claude', ['--version'], 20_000);
     if (version.code === 127)
         return {
             added: false,
             step: {
                 ok: false,
-                text: `Claude Code isn’t on this computer’s PATH. Install it, then run: claude mcp add --scope user --transport http ${MCP_NAME} ${origin}/mcp`,
+                text: `Claude Code isn’t on this computer’s PATH. Install it, then run: ${addCommand(url)}`,
             },
         };
-    const existing = await io.run('claude', ['mcp', 'get', MCP_NAME], 20_000);
-    if (existing.code === 0)
+    if (existing === 'unknown') {
+        progress('Checking Claude Code’s MCP servers (this can take a minute)…\n');
+        existing = await mcpFromClaude(io);
+        if (existing === 'timeout')
+            return {
+                added: false,
+                step: {
+                    ok: false,
+                    text: `Claude Code took more than 3 minutes to list its MCP servers, so I left them alone. Check with: claude mcp get ${MCP_NAME}. If it isn’t there, run: ${addCommand(url)}`,
+                },
+            };
+    }
+    let replacing = null;
+    if (existing) {
+        if (!existing.url || sameUrl(existing.url, url))
+            return {
+                added: false,
+                step: { ok: true, text: 'The pendingyou MCP server was already in Claude Code.' },
+            };
+        progress(`Claude Code’s pendingyou MCP server points at ${existing.url}, not ${url}.\n`);
+        const commands = `  ${removeCommand(existing.scope)}\n    ${addCommand(url)}`;
+        let replace = options.yes;
+        if (!replace && io.interactive) {
+            const answer = await io.ask(`Replace it with ${url}? [y/N] `);
+            replace = /^\s*y(es)?\s*$/i.test(answer);
+            if (!replace)
+                return {
+                    added: false,
+                    step: {
+                        ok: false,
+                        text: `Kept the MCP server at ${existing.url}. To switch later, run:\n  ${commands}`,
+                    },
+                };
+        }
+        if (!replace)
+            return {
+                added: false,
+                step: {
+                    ok: false,
+                    text: `Kept the MCP server at ${existing.url}. To use ${url}, run init again with --yes, or run:\n  ${commands}`,
+                },
+            };
+        progress('Removing the old pendingyou MCP server (this can take a minute)…\n');
+        const removed = await io.run('claude', ['mcp', 'remove', ...(existing.scope ? ['--scope', existing.scope] : []), MCP_NAME], MCP_TIMEOUT_MS);
+        if (removed.code !== 0)
+            return {
+                added: false,
+                step: {
+                    ok: false,
+                    text: `${removed.code === 124 ? 'Claude Code took more than 3 minutes to remove' : 'Claude Code didn’t remove'} the old MCP server. Run:\n  ${commands}`,
+                },
+            };
+        replacing = existing;
+    }
+    progress('Adding the pendingyou MCP server to Claude Code (this can take a minute)…\n');
+    const add = await io.run('claude', ['mcp', 'add', '--scope', 'user', '--transport', 'http', MCP_NAME, url], MCP_TIMEOUT_MS);
+    if (add.code === 0)
         return {
-            added: false,
-            step: { ok: true, text: 'The pendingyou MCP server was already in Claude Code.' },
-        };
-    const add = await io.run('claude', ['mcp', 'add', '--scope', 'user', '--transport', 'http', MCP_NAME, `${origin}/mcp`], 30_000);
-    return add.code === 0
-        ? {
             added: true,
             step: {
                 ok: true,
-                text: `Added the pendingyou MCP server (${origin}/mcp) for every project.`,
-            },
-        }
-        : {
-            added: false,
-            step: {
-                ok: false,
-                text: `Claude Code didn’t add the MCP server. Run: claude mcp add --scope user --transport http ${MCP_NAME} ${origin}/mcp`,
+                text: replacing
+                    ? `Replaced the pendingyou MCP server (was ${replacing.url}) with ${url}. Restart Claude Code, then run /mcp, choose pendingyou and Authenticate.`
+                    : `Added the pendingyou MCP server (${url}) for every project.`,
             },
         };
+    return {
+        added: false,
+        step: {
+            ok: false,
+            text: add.code === 124
+                ? `Claude Code took more than 3 minutes to add the MCP server. Check with: claude mcp get ${MCP_NAME}. If it isn’t there, run: ${addCommand(url)}`
+                : `Claude Code didn’t add the MCP server. Run: ${addCommand(url)}`,
+        },
+    };
 }
 /** The stub skill: written when it isn't there, or refreshed while it's still the one init wrote. */
 async function saveSkill(io, origin, before) {
@@ -238,27 +363,50 @@ async function saveSkill(io, origin, before) {
         step: { ok: true, text: `Saved the skill to ${path}.` },
     };
 }
-/** Everything init does in Claude Code (not the sign-in). Idempotent. */
-export async function installClaude(io, origin) {
+/** Everything init does in Claude Code (not the sign-in). Idempotent. Each step is reported as it's done. */
+export async function installClaude(io, origin, options = {}) {
     const before = await readManifest(io);
     const steps = [];
-    const mcp = await addMcp(io, origin);
-    steps.push(mcp.step);
+    const report = (step) => {
+        steps.push(step);
+        options.report?.(step);
+    };
+    const progress = (text) => io.out(text);
+    const mcp = await addMcp(io, origin, { yes: options.yes ?? false }, progress);
+    report(mcp.step);
     const skill = await saveSkill(io, origin, before?.skill ?? null);
-    steps.push(skill.step);
+    report(skill.step);
+    // The hooks' own copy of this version, unless PENDINGYOU_SELF says what they run.
+    let installed = null;
+    if (!io.env.PENDINGYOU_SELF) {
+        const cli = await installCli(io, progress);
+        installed = cli.installed;
+        report(cli.installed
+            ? {
+                ok: true,
+                text: `${cli.installed.how === 'kept' ? `pendingyou ${VERSION} for the hooks was already in` : `Installed pendingyou ${VERSION} for the hooks in`} ${cli.installed.prefix} (they run it with ${cli.installed.node}, no npx).`,
+            }
+            : {
+                ok: true,
+                text: `Couldn’t install pendingyou for the hooks (${cli.error}), so they run it through npx, which is slower. Run init again to retry.`,
+            });
+    }
     const commands = Object.fromEntries(Object.keys(HOOKS).map((event) => [
         event,
-        hookCommand(io, origin, HOOKS[event]),
+        hookCommand(io, origin, HOOKS[event], installed),
     ]));
     const merged = mergeSettings(await readSettings(io), commands);
     if (merged.changed)
         await writeSettings(io, merged.settings);
-    steps.push({
+    report({
         ok: true,
         text: merged.changed
             ? `Installed or updated the session-start pickup, next-message hand-off and Stop check hooks in ${settingsPath(io)}.`
             : 'The hooks were already installed.',
     });
+    // The hooks run this version now (or npx): the copies of other versions are no longer used.
+    if (!io.env.PENDINGYOU_SELF)
+        await pruneCli(io, installed?.version ?? null);
     const manifest = {
         version: 1,
         origin,
@@ -267,6 +415,7 @@ export async function installClaude(io, origin) {
         skill: skill.skill,
         hooks: commands,
         permissions: [...new Set([...(before?.permissions ?? []), ...merged.permissionsAdded])],
+        cli: installed ? { version: installed.version, prefix: installed.prefix } : null,
     };
     await writeWhole(manifestPath(io), `${JSON.stringify(manifest, null, 2)}\n`, { secret: true });
     return steps;
@@ -295,8 +444,11 @@ export async function uninstallClaude(io) {
         else if (text !== null)
             steps.push({ ok: true, text: `Kept ${manifest.skill.path}: it was changed after init.` });
     }
+    if (await removeCli(io))
+        steps.push({ ok: true, text: 'Removed the hooks’ copy of pendingyou.' });
     if (manifest?.mcpAdded) {
-        const result = await io.run('claude', ['mcp', 'remove', '--scope', 'user', MCP_NAME], 30_000);
+        io.out('Removing the pendingyou MCP server from Claude Code (this can take a minute)…\n');
+        const result = await io.run('claude', ['mcp', 'remove', '--scope', 'user', MCP_NAME], MCP_TIMEOUT_MS);
         steps.push(result.code === 0
             ? { ok: true, text: 'Removed the pendingyou MCP server from Claude Code.' }
             : {
@@ -311,20 +463,33 @@ export async function uninstallClaude(io) {
 export async function claudeState(io) {
     const version = await io.run('claude', ['--version'], 20_000);
     const claude = version.code === 0 ? version.stdout.trim().split(/\s+/)[0] || 'installed' : null;
-    const mcp = claude ? (await io.run('claude', ['mcp', 'get', MCP_NAME], 20_000)).code === 0 : false;
+    let mcp = false;
+    const fromFile = await mcpFromFile(io);
+    if (fromFile !== 'unknown')
+        mcp = fromFile ?? false;
+    else if (claude) {
+        const fromClaude = await mcpFromClaude(io);
+        mcp = fromClaude === 'timeout' ? 'unknown' : (fromClaude ?? false);
+    }
     const skill = (await readText(skillPath(io))) !== null;
-    let installed = (_event) => false;
+    let ours = (_event) => undefined;
     try {
         const all = objectAt(await readSettings(io), 'hooks') ?? {};
-        installed = (event) => Array.isArray(all[event]) &&
-            all[event].some((group) => (group.hooks ?? []).some((hook) => isOurHook(hook.command, HOOKS[event])));
+        ours = (event) => Array.isArray(all[event])
+            ? all[event]
+                .flatMap((group) => group.hooks ?? [])
+                .find((hook) => isOurHook(hook.command, HOOKS[event]))
+            : undefined;
     }
     catch { }
+    const start = ours('SessionStart');
+    const form = typeof start?.command === 'string' ? hookForm(start.command) : null;
     return {
         claude,
         mcp,
         skill,
-        hooks: installed('SessionStart') && installed('UserPromptSubmit'),
-        stopcheck: installed('Stop'),
+        hooks: Boolean(start && ours('UserPromptSubmit')),
+        stopcheck: Boolean(ours('Stop')),
+        form: form ? { ...form, runs: await hookRuns(form) } : null,
     };
 }

package/dist/files.js

@@ -60,7 +60,11 @@ export async function writeWhole(path, text, options = {}) {
     }
 }
 /** A lock older than this was left by a process that died; it's taken over. */
-const STALE_MS = 30_000;
+export const STALE_MS = 30_000;
+/** Whether another process holds `<path>.lock` now (a lock older than STALE_MS doesn't count). */
+export async function isLocked(path) {
+    return stat(`${path}.lock`).then((info) => Date.now() - info.mtimeMs <= STALE_MS, () => false);
+}
 /** Runs `work` while holding `<path>.lock`, so two processes (a hold and a hook) never write over each other. */
 export async function withLock(path, io, work) {
     const lock = `${path}.lock`;

package/dist/install.js

@@ -0,0 +1,163 @@
+// The command line's own copy for Claude Code's hooks (0.7.0). Hooks used to run `npx -y --prefer-offline
+// pendingyou@<version> …`: npx costs about half a second before the command starts, and sessions starting together
+// queue on npm's cache lock. Now `init` puts this exact version in a private folder,
+// ~/.config/pendingyou/cli/<version>/node_modules/pendingyou, and the hooks run it with Node directly:
+//
+//   "<node>" "<config>/cli/<version>/node_modules/pendingyou/dist/cli.js" handoff || true
+//
+// The copy comes from the package init is running from when that's this very version (npx's copy: no network), and
+// otherwise from `npm install --prefix`. It's built in a temporary folder, checked (`--version` must print this
+// version), then moved into place, so a hook never runs half a copy. Running init again keeps a copy that checks out,
+// and removes the other versions once the hooks point at this one. When none of that works, the hooks keep the npx
+// form, which is slower but works.
+import { randomBytes } from 'node:crypto';
+import { cp, mkdir, readdir, realpath, rename, rm, stat } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+import { configDir, readJson } from "./files.js";
+import { VERSION } from "./version.js";
+/** Where the private copies live: ~/.config/pendingyou/cli. */
+export const cliRoot = (io) => join(configDir(io), 'cli');
+/** One version's prefix: ~/.config/pendingyou/cli/<version>. */
+export const cliPrefix = (io, version = VERSION) => join(cliRoot(io), version);
+/** The command line inside a prefix. */
+export const cliScript = (prefix) => join(prefix, 'node_modules', 'pendingyou', 'dist', 'cli.js');
+/** How long npm may take to install the package (it usually takes a few seconds). */
+const NPM_TIMEOUT_MS = 180_000;
+const exists = (path) => stat(path).then(() => true, () => false);
+/**
+ * The Node the hooks should run: the running one, by the path on PATH that leads to it when there is one
+ * (Homebrew's /opt/homebrew/bin/node outlives an upgrade; the versioned folder it points into doesn't).
+ */
+export async function hookNode(io) {
+    const running = await realpath(io.execPath).catch(() => null);
+    if (running)
+        for (const dir of (io.env.PATH ?? '').split(':')) {
+            if (!dir || !isAbsolute(dir))
+                continue;
+            const candidate = join(dir, 'node');
+            if ((await realpath(candidate).catch(() => null)) === running)
+                return candidate;
+        }
+    return io.execPath;
+}
+/** Whether `script` run by `node` is this version of the command line. */
+async function works(io, node, script) {
+    if (!(await exists(script)))
+        return false;
+    const result = await io.run(node, [script, '--version'], 30_000);
+    return result.code === 0 && result.stdout.trim() === VERSION;
+}
+/** The package init is running from, when it's this version of pendingyou (npx's copy, or a global install). */
+async function runningPackage(io) {
+    if (!io.script || basename(io.script) !== 'cli.js' || basename(dirname(io.script)) !== 'dist')
+        return null;
+    const root = dirname(dirname(io.script));
+    const manifest = await readJson(join(root, 'package.json')).catch(() => null);
+    return manifest?.name === 'pendingyou' && manifest.version === VERSION ? root : null;
+}
+/** Copies the package's published files (no dependencies to bring: it has none). */
+async function copyPackage(from, to) {
+    await mkdir(to, { recursive: true });
+    for (const name of ['package.json', 'dist', 'README.md', 'CHANGELOG.md', 'LICENSE'])
+        if (await exists(join(from, name)))
+            await cp(join(from, name), join(to, name), { recursive: true });
+}
+/**
+ * Puts this version in its private prefix, or keeps the one already there. Null (and why) when it couldn't: the hooks
+ * then use npx.
+ */
+export async function installCli(io, progress) {
+    const node = await hookNode(io);
+    const prefix = cliPrefix(io);
+    const script = cliScript(prefix);
+    if (await works(io, node, script))
+        return { installed: { version: VERSION, prefix, node, script, how: 'kept' } };
+    const root = cliRoot(io);
+    const staging = join(root, `.tmp-${VERSION}-${randomBytes(4).toString('hex')}`);
+    try {
+        await mkdir(root, { recursive: true, mode: 0o700 });
+        let how = null;
+        const from = await runningPackage(io);
+        if (from) {
+            try {
+                await copyPackage(from, join(staging, 'node_modules', 'pendingyou'));
+                if (await works(io, node, cliScript(staging)))
+                    how = 'copied';
+            }
+            catch { }
+        }
+        if (!how) {
+            await rm(staging, { recursive: true, force: true });
+            await mkdir(staging, { recursive: true });
+            progress(`Installing pendingyou@${VERSION} with npm, so the hooks start fast…\n`);
+            const result = await io.run('npm', [
+                'install',
+                '--prefix',
+                staging,
+                '--no-save',
+                '--no-package-lock',
+                '--no-audit',
+                '--no-fund',
+                '--prefer-offline',
+                '--loglevel=error',
+                `pendingyou@${VERSION}`,
+            ], NPM_TIMEOUT_MS);
+            if (result.code === 127)
+                return { installed: null, error: 'npm isn’t on this computer’s PATH' };
+            if (result.code === 124)
+                return { installed: null, error: 'npm took more than 3 minutes to install it' };
+            if (result.code !== 0)
+                return { installed: null, error: 'npm couldn’t install it' };
+            if (!(await works(io, node, cliScript(staging))))
+                return { installed: null, error: 'the installed copy didn’t run' };
+            how = 'npm';
+        }
+        await rm(prefix, { recursive: true, force: true });
+        await rename(staging, prefix);
+        return { installed: { version: VERSION, prefix, node, script, how } };
+    }
+    catch {
+        return { installed: null, error: `couldn’t write to ${root}` };
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true }).catch(() => { });
+    }
+}
+/** Removes every private copy but `keep` (the versions the hooks no longer run, and leftovers). */
+export async function pruneCli(io, keep) {
+    const root = cliRoot(io);
+    const entries = await readdir(root).catch(() => []);
+    for (const entry of entries)
+        if (entry !== keep)
+            await rm(join(root, entry), { recursive: true, force: true }).catch(() => { });
+}
+/** Removes the private copies altogether (uninstall). True when there were any. */
+export async function removeCli(io) {
+    const root = cliRoot(io);
+    if (!(await exists(root)))
+        return false;
+    await rm(root, { recursive: true, force: true });
+    return true;
+}
+/** A double-quoted shell word: safe for any path, spaces and quotes included. */
+export const shellQuote = (text) => `"${text.replace(/["$`\\]/g, '\\$&')}"`;
+const QUOTED = /^"((?:[^"\\]|\\.)*)"\s+"((?:[^"\\]|\\.)*)"\s/;
+const unquote = (text) => text.replace(/\\(.)/g, '$1');
+export function hookForm(command) {
+    const direct = QUOTED.exec(command);
+    if (direct) {
+        const script = unquote(direct[2]);
+        const version = /\/cli\/([^/]+)\/node_modules\/pendingyou\/dist\/cli\.js$/.exec(script);
+        return {
+            form: 'direct',
+            node: unquote(direct[1]),
+            script,
+            version: version?.[1] ?? null,
+        };
+    }
+    if (/^npx\s/.test(command))
+        return { form: 'npx', version: /pendingyou@([^\s]+)/.exec(command)?.[1] ?? null };
+    return { form: 'other' };
+}
+/** Whether a direct hook's Node and script are both still there. */
+export const hookRuns = async (form) => form.form !== 'direct' || ((await exists(form.node)) && (await exists(form.script)));

package/dist/io.js

@@ -2,6 +2,7 @@
 // network, a fake browser and a fake `claude`. `realIo()` is the real thing.
 import { spawn } from 'node:child_process';
 import { homedir, hostname } from 'node:os';
+import { createInterface } from 'node:readline';
 export function runProgram(command, args, timeoutMs = 60_000) {
     return new Promise((resolve) => {
         let stdout = '';
@@ -10,7 +11,6 @@ export function runProgram(command, args, timeoutMs = 60_000) {
         try {
             child = spawn(command, [...args], {
                 stdio: ['ignore', 'pipe', 'pipe'],
-                timeout: timeoutMs,
                 windowsHide: true,
             });
         }
@@ -18,14 +18,23 @@ export function runProgram(command, args, timeoutMs = 60_000) {
             resolve({ code: 127, stdout, stderr });
             return;
         }
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+        }, timeoutMs);
+        const done = (code) => {
+            clearTimeout(timer);
+            resolve({ code: timedOut ? 124 : code, stdout, stderr });
+        };
         child.stdout?.on('data', (chunk) => {
             stdout += String(chunk);
         });
         child.stderr?.on('data', (chunk) => {
             stderr += String(chunk);
         });
-        child.on('error', (error) => resolve({ code: error.code === 'ENOENT' ? 127 : 1, stdout, stderr }));
-        child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
+        child.on('error', (error) => done(error.code === 'ENOENT' ? 127 : 1));
+        child.on('close', (code) => done(code ?? 1));
     });
 }
 export function execProgram(command, args, options) {
@@ -96,6 +105,21 @@ function readStdin(timeoutMs) {
         process.stdin.on('error', finish);
     });
 }
+function ask(question) {
+    return new Promise((resolve) => {
+        const prompt = createInterface({ input: process.stdin, output: process.stdout });
+        let answered = false;
+        prompt.on('close', () => {
+            if (!answered)
+                resolve('');
+        });
+        prompt.question(question, (answer) => {
+            answered = true;
+            prompt.close();
+            resolve(answer);
+        });
+    });
+}
 async function openBrowser(url) {
     const [command, args] = process.platform === 'darwin'
         ? ['open', [url]]
@@ -105,6 +129,20 @@ async function openBrowser(url) {
     const result = await runProgram(command, args, 10_000);
     return result.code === 0;
 }
+function background(script, args) {
+    if (!script)
+        return;
+    try {
+        const child = spawn(process.execPath, [script, ...args], {
+            detached: true,
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch { }
+}
 export function realIo() {
     const controller = new AbortController();
     // The first signal lets the command finish cleanly (a hold says how the answer will still arrive); a second one
@@ -124,6 +162,9 @@ export function realIo() {
         out: (text) => process.stdout.write(text),
         err: (text) => process.stderr.write(text),
         fetch: (input, init) => fetch(input, init),
+        execPath: process.execPath,
+        interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        ask,
         run: runProgram,
         exec: execProgram,
         openBrowser,
@@ -132,5 +173,7 @@ export function realIo() {
         sleep,
         signal: controller.signal,
         script: process.argv[1] ?? '',
+        uptime: () => process.uptime() * 1000,
+        background: (args) => background(process.argv[1] ?? '', args),
     };
 }

package/dist/main.js

@@ -1,7 +1,7 @@
 // The command line: parse the arguments, run the command, return the exit code. `cli.ts` runs it for real; tests run
 // it with their own Io.
-import { getJson, SignInNeeded, Unavailable } from "./api.js";
-import { commandOf, HOOK_COMMANDS, parseArgs, USAGE, UsageError } from "./args.js";
+import { getJson, refreshInBackground, SignInNeeded, Unavailable } from "./api.js";
+import { commandOf, DEFAULT_ORIGIN, HOOK_COMMANDS, parseArgs, USAGE, UsageError, } from "./args.js";
 import { claudeState, installClaude, uninstallClaude } from "./claude.js";
 import { readCredential, signedInOrigins, updateCredential } from "./credentials.js";
 import { PlainError } from "./errors.js";
@@ -74,6 +74,27 @@ async function status(io, origin) {
     const [signIn, claude] = await Promise.all([checkSignIn(io, origin), claudeState(io)]);
     const lines = [`Pending You for Claude Code · ${origin}`];
     const mark = (ok) => (ok ? 'ok     ' : 'missing');
+    const url = `${origin}/mcp`;
+    const mcp = claude.mcp;
+    const mcpOk = mcp !== false && mcp !== 'unknown' && (!mcp.url || mcp.url.replace(/\/+$/, '') === url);
+    const mcpText = mcp === 'unknown'
+        ? 'Claude Code didn’t say in time; check with claude mcp get pendingyou'
+        : mcp === false
+            ? 'not added; run npx pendingyou init'
+            : mcpOk
+                ? `pendingyou${mcp.url ? ` (${mcp.url})` : ''}`
+                : `points at ${mcp.url}, not ${url}; run npx pendingyou init${origin === DEFAULT_ORIGIN ? '' : ` --origin ${origin}`} to replace it`;
+    const form = claude.form;
+    const hooksRun = form?.runs ?? true;
+    const formText = !form
+        ? ''
+        : form.form === 'direct'
+            ? form.runs
+                ? `they run pendingyou${form.version ? ` ${form.version}` : ''} directly (${form.script})`
+                : `the Node or the copy of pendingyou they run is gone (${form.node}, ${form.script}); run npx pendingyou@latest init`
+            : form.form === 'npx'
+                ? 'they run through npx, which is slower; run npx pendingyou@latest init to run them directly'
+                : 'they run pendingyou from PATH or a file of your own';
     lines.push(`  ${mark(signIn.state === 'ok')} Sign-in: ${signIn.state === 'ok'
         ? signIn.for
             ? `hears for ${signIn.for.name} only (for pendingyou watch)`
@@ -82,8 +103,8 @@ async function status(io, origin) {
             ? 'ended; run npx pendingyou login'
             : signIn.state === 'none'
                 ? 'not signed in; run npx pendingyou login'
-                : 'Pending You couldn’t be reached'}`, `  ${mark(claude.claude !== null)} Claude Code: ${claude.claude ?? 'not found on PATH'}`, `  ${mark(claude.mcp)} MCP server: ${claude.mcp ? 'pendingyou' : 'not added; run npx pendingyou init'}`, `  ${mark(claude.skill)} Skill: ${claude.skill ? 'saved' : 'not saved; run npx pendingyou init'}`, `  ${mark(claude.hooks)} Hooks: ${claude.hooks ? 'session-start pickup and next-message hand-off' : 'not installed; run npx pendingyou init'}`, `  ${mark(claude.stopcheck)} Stop check: ${claude.stopcheck ? 'asks Claude Code to post what it leaves you in chat' : 'not installed; run npx pendingyou init'}`);
-    const ready = signIn.state === 'ok' && claude.hooks;
+                : 'Pending You couldn’t be reached'}`, `  ${mark(claude.claude !== null)} Claude Code: ${claude.claude ?? 'not found on PATH'}`, `  ${mark(mcpOk)} MCP server: ${mcpText}`, `  ${mark(claude.skill)} Skill: ${claude.skill ? 'saved' : 'not saved; run npx pendingyou init'}`, `  ${mark(claude.hooks && hooksRun)} Hooks: ${claude.hooks ? `session-start pickup and next-message hand-off; ${formText}` : 'not installed; run npx pendingyou init'}`, `  ${mark(claude.stopcheck)} Stop check: ${claude.stopcheck ? 'asks Claude Code to post what it leaves you in chat' : 'not installed; run npx pendingyou init'}`);
+    const ready = signIn.state === 'ok' && claude.hooks && hooksRun;
     lines.push(ready
         ? 'Ready: Claude Code hears answers right away (report_setup hears "instant").'
         : 'Not ready: Claude Code hears answers while it’s working (report_setup hears "while-working").');
@@ -92,9 +113,10 @@ async function status(io, origin) {
 }
 async function init(io, options) {
     io.out(`Setting up Pending You for Claude Code (${options.origin}).\n`);
-    const steps = await installClaude(io, options.origin);
-    for (const step of steps)
-        io.out(`  ${step.ok ? 'ok     ' : 'check  '} ${step.text}\n`);
+    const steps = await installClaude(io, options.origin, {
+        yes: options.yes,
+        report: (step) => io.out(`  ${step.ok ? 'ok     ' : 'check  '} ${step.text}\n`),
+    });
     if (options.login) {
         io.out('Signing this computer in, so answers can wake Claude Code:\n');
         await login(io, {
@@ -116,7 +138,7 @@ async function uninstall(io, origin) {
     await logout(io, { origin, all: false });
     return steps.every((step) => step.ok) ? 0 : 1;
 }
-async function run(io, command) {
+async function run(io, command, hook = { fallback: '' }) {
     switch (command.name) {
         case 'help':
             io.out(USAGE);
@@ -133,9 +155,9 @@ async function run(io, command) {
         case 'hold':
             return hold(io, command);
         case 'pickup':
-            return pickup(io, { origin: command.origin, mode: 'pickup' });
+            return pickup(io, { origin: command.origin, mode: 'pickup' }, hook);
         case 'handoff':
-            return pickup(io, { origin: command.origin, mode: 'handoff' });
+            return pickup(io, { origin: command.origin, mode: 'handoff' }, hook);
         case 'stopcheck':
             return stopcheck(io, { origin: command.origin });
         case 'init':
@@ -144,6 +166,61 @@ async function run(io, command) {
             return uninstall(io, command.origin);
         case 'watch':
             return watch(io, command);
+        case 'refresh':
+            // Detached and quiet: nobody reads what it prints, and the next hook sees the result in the credentials file.
+            try {
+                await refreshInBackground(io, command.origin, command.force);
+            }
+            catch { }
+            return 0;
+    }
+}
+/**
+ * A hook's hard deadline, from the moment this process started: Claude Code gives a hook 10 seconds (init's
+ * `timeout`), npx (hooks from before 0.7.0) takes about half a second before this process starts, and a normal hook
+ * is done in well under one.
+ * When it's reached, the hook prints its plain fallback (the hand-off's one-line reminder; nothing for pickup and
+ * stopcheck) unless it already printed, and exits 0, whatever it was still waiting on.
+ */
+export const HOOK_DEADLINE_MS = 3000;
+async function runHook(io, command) {
+    const hook = { fallback: '' };
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    if (io.signal.aborted)
+        stop();
+    io.signal.addEventListener('abort', stop, { once: true });
+    let finished = false;
+    let printed = false;
+    const hookIo = {
+        ...io,
+        out: (text) => {
+            if (finished)
+                return;
+            printed = true;
+            io.out(text);
+        },
+        signal: controller.signal,
+    };
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('deadline'), Math.max(0, HOOK_DEADLINE_MS - io.uptime()));
+    });
+    try {
+        const outcome = await Promise.race([run(hookIo, command, hook), deadline]);
+        if (outcome !== 'deadline')
+            return outcome;
+        finished = true;
+        controller.abort();
+        if (!printed && hook.fallback)
+            io.out(hook.fallback);
+        io.err('pendingyou: Pending You took too long; skipped this hook.\n');
+        return 0;
+    }
+    finally {
+        finished = true;
+        clearTimeout(timer);
+        io.signal.removeEventListener('abort', stop);
     }
 }
 /**
@@ -174,7 +251,7 @@ export async function main(argv, io) {
     if (hook && !HOOK_COMMANDS.has(command.name))
         return 0;
     try {
-        return await run(io, command);
+        return hook ? await runHook(io, command) : await run(io, command);
     }
     catch (error) {
         // Plain words only: never a stack, a token or a server's description.

package/dist/oauth.js

@@ -32,10 +32,10 @@ export function pkce() {
 }
 /** The resource the tokens are for: Pending You's MCP server, whose /mcp/cli/* the command line calls. */
 export const resourceOf = (origin) => `${origin}/mcp`;
-export async function discover(io, origin) {
+export async function discover(io, origin, timeoutMs = 15_000) {
     const response = await io.fetch(`${origin}/.well-known/oauth-authorization-server`, {
         headers: { accept: 'application/json' },
-        signal: AbortSignal.timeout(15_000),
+        signal: AbortSignal.timeout(timeoutMs),
     });
     if (!response.ok)
         throw new OAuthError('discovery', `Pending You at ${origin} didn’t answer (${response.status}).`);
@@ -136,12 +136,12 @@ async function listen(state, signal) {
         },
     };
 }
-async function tokenRequest(io, metadata, params) {
+async function tokenRequest(io, metadata, params, timeoutMs = 20_000) {
     const response = await io.fetch(metadata.token_endpoint, {
         method: 'POST',
         headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
         body: new URLSearchParams(params).toString(),
-        signal: AbortSignal.timeout(20_000),
+        signal: AbortSignal.timeout(timeoutMs),
     });
     const body = (await response.json().catch(() => ({})));
     if (!response.ok ||
@@ -203,15 +203,18 @@ export async function signIn(io, options) {
         loopback.close();
     }
 }
-/** A new access token (and the next refresh token) from the current refresh token. */
+/**
+ * A new access token (and the next refresh token) from the current refresh token. At most 20 seconds in all, well
+ * inside the credentials lock's 30 seconds, so no other process takes the lock over while a refresh is still running.
+ */
 export async function refresh(io, origin, clientId, refreshToken) {
-    const metadata = await discover(io, origin);
+    const metadata = await discover(io, origin, 8_000);
     return tokenRequest(io, metadata, {
         grant_type: 'refresh_token',
         refresh_token: refreshToken,
         client_id: clientId,
         resource: resourceOf(origin),
-    });
+    }, 12_000);
 }
 /** Revokes the sign-in on the server (RFC 7009). Best effort: signing out here still happens if this fails. */
 export async function revoke(io, origin, clientId, refreshToken) {

package/dist/pickup.js

@@ -10,12 +10,14 @@
 //   time-boxed short; on any error, or from a server too old to list open cards, the line is the plain reminder.
 //
 // Whatever they print, Claude Code adds to the conversation. A hook must never get in the way: each is time-boxed,
+// has a hard deadline (main.ts) after which it prints only its fallback, never refreshes the sign-in itself (api.ts),
 // prints nothing when there's nothing new, never repeats an answer it handed over, and always exits 0.
 import { getJson, SignInNeeded } from "./api.js";
 import { readCredential } from "./credentials.js";
 import { clip, describe, isClosed } from "./format.js";
 import { markHanded, momentOf, waitingOn, wasHanded } from "./state.js";
-const TIME_BOX_MS = { pickup: 5000, handoff: 2500, open: 1500 };
+/** Each request's own limit, inside the hook's 3-second deadline (main.ts). */
+const TIME_BOX_MS = { pickup: 2500, handoff: 2000, open: 1500 };
 /** What every message carries while signed in (about 18 tokens). */
 export const REMINDER = 'Pending You: anything you need from your person also goes on a card.';
 /** The most open cards the line names, and how much of each title. */
@@ -70,18 +72,19 @@ export function folderForms(cwd, home) {
         forms.push(`~${cwd.slice(base.length)}`);
     return forms;
 }
-export async function pickup(io, options) {
+export async function pickup(io, options, hook = { fallback: '' }) {
     const { origin, mode } = options;
-    let remind = false;
-    let line = REMINDER;
+    // The hand-off's line, printed at the end unless something else was printed with it.
+    let line = null;
     try {
         const cwd = await sessionFolder(io);
         // The hand-off hears answers only while a hold from this computer is outstanding; it always asks for open cards.
         let answers = true;
         if (mode === 'handoff') {
-            remind = (await readCredential(io, origin)) !== null;
-            if (!remind)
+            if ((await readCredential(io, origin)) === null)
                 return 0;
+            line = REMINDER;
+            hook.fallback = `${REMINDER}\n`;
             answers = (await waitingOn(io, origin)).length > 0;
         }
         const query = new URLSearchParams([
@@ -89,7 +92,7 @@ export async function pickup(io, options) {
             ['limit', answers ? '5' : '0'],
             ...(mode === 'handoff' ? [['open', String(OPEN_SHOWN)]] : []),
         ]);
-        const { status, body } = await getJson(io, origin, `/mcp/cli/answers?${query}`, answers ? TIME_BOX_MS[mode] : TIME_BOX_MS.open, io.signal);
+        const { status, body } = await getJson(io, origin, `/mcp/cli/answers?${query}`, answers ? TIME_BOX_MS[mode] : TIME_BOX_MS.open, io.signal, { hook: true });
         if (status !== 200)
             return 0;
         if (mode === 'handoff')
@@ -103,6 +106,8 @@ export async function pickup(io, options) {
         if (fresh.length === 0)
             return 0;
         const again = (id) => `run \`npx pendingyou hold ${id}\` in the background`;
+        // One write, the line included: at the deadline a hook has printed all of this or none of it. Printed before it's
+        // marked as handed over, so a hook cut off in between repeats an answer rather than losing it.
         io.out(`${[
             mode === 'pickup'
                 ? 'Pending You: your person answered while no session was listening.'
@@ -110,7 +115,9 @@ export async function pickup(io, options) {
             '',
             ...fresh.flatMap((heard) => [...describe(heard, again(heard.requestId)), '']),
             'Tell them in one line first (“You answered in Pending You: …”), then act.',
+            ...(line ? [line] : []),
         ].join('\n')}\n`);
+        line = null;
         await markHanded(io, origin, fresh.map((heard) => ({
             requestId: heard.requestId,
             moment: momentOf(heard),
@@ -122,11 +129,11 @@ export async function pickup(io, options) {
         if (mode === 'pickup' && error instanceof SignInNeeded && error.ended)
             io.out('Pending You: this computer’s pendingyou sign-in has ended, so answers can’t wake Claude Code. Ask your person to run `npx pendingyou login`.\n');
         if (error instanceof SignInNeeded)
-            remind = false;
+            line = null;
         return 0;
     }
     finally {
-        if (remind)
+        if (line)
             io.out(`${line}\n`);
     }
 }

package/dist/stopcheck.js

@@ -19,8 +19,16 @@ const POSTING_TOOL = /^mcp__.+__(post_request|update_request|reply_in_thread)$/;
  * announces a card to come, not a step left in chat.
  */
 const SAYS_POSTED = /\b(posted|put|added|raised|filed)\b[^.\n]{0,60}\b(cards?|pending ?you)\b|\bon (a|the|its|their|your|that|this) cards?\b|\b(in|to|through|via|on) pending ?you\b|\bpending ?you cards?\b|\b(i|we|you)(?:(?:'|’)ll| will)\s+(?:\w+\s+)?(post|send|put|add|raise|file|get|see|find)\b[^.\n]{0,40}\bcards?\b/i;
-/** Steps only the person can take, said to them. */
-const STEPS_FOR_THEM = /\b(you(?:'|’)ll need to|you will need to|you(?:'|’)ll have to|you will have to|your (?:next )?steps?\b|can you|could you|would you mind|please (?:run|confirm|approve|check|add|set|sign|create|open|paste|reply|send|choose|pick|decide|let me know)|in your terminal|only you can|waiting on you|waiting for you|needs? you to|over to you|parked for you|when you(?:'|’)re ready|up to you|your call\b|is yours\b|say the word|let me know (?:which|whether)|tell me (?:which|whether)|needs? your (?:ok|okay|approval|decision|sign-?off|go-ahead))/i;
+/**
+ * Steps only the person can take, said to them. Not "nothing (is) waiting on you" or "no cards … waiting on you" (a
+ * negation within the clause), nor "say if it needs you to …" (what another agent will say, if it ever does).
+ */
+const STEPS_FOR_THEM = /\b(you(?:'|’)ll need to|you will need to|you(?:'|’)ll have to|you will have to|your (?:next )?steps?\b|can you|could you|would you mind|please (?:run|confirm|approve|check|add|set|sign|create|open|paste|reply|send|choose|pick|decide|let me know)|in your terminal|only you can|(?<!\b(?:no|nothing|none|not)\b[^.,;:!?\n]{0,40})waiting (?:on|for) you|(?<!\bif (?:it|he|she|they|that|this|anything|something|someone|anyone|one) )needs? you to|over to you|parked for you|when you(?:'|’)re ready|up to you|your call\b|is yours\b|say the word|let me know (?:which|whether)|tell me (?:which|whether)|needs? your (?:ok|okay|approval|decision|sign-?off|go-ahead))/i;
+/**
+ * Text that says nothing here needs a card: the "or say they don’t need one" the Stop reason offers ("No card
+ * needed.", "Nothing needs your attention.", "There’s nothing waiting on you.").
+ */
+const SAYS_NO_CARD = /\bno (?:new |more |further )?cards? (?:is |are )?(?:needed|necessary|required)\b|\b(?:doesn(?:'|’)t|don(?:'|’)t|does not|do not|won(?:'|’)t|will not) need (?:a |any )?(?:new )?cards?\b|\bnothing (?:here |else |more |now )?(?:needs|requires) your (?:attention|input|action|answer)\b|\b(?:nothing|no cards?)\b[^.,;:!?\n]{0,40}\b(?:waiting|pending) (?:on|for) you\b/i;
 /** A heading over a list of things for the person. */
 const FOR_THEM_HEADING = /\b(your part|your steps?|your to-?dos?|your turn|your call|for you|waiting on you|left for you|parked for you|needs you|over to you|what you need to do|you(?:'|’)ll need)\b/i;
 const LIST_ITEM = /^\s*(?:\d+[.)]|[-*•]|\[ \])\s+\S/;
@@ -77,6 +85,8 @@ export function itemsForPerson(text) {
 }
 /** Whether the text says the items are already in Pending You. */
 export const saysPosted = (text) => SAYS_POSTED.test(plainText(text));
+/** Whether the text says nothing in it needs a card. */
+export const saysNoCard = (text) => SAYS_NO_CARD.test(plainText(text));
 /** A message from the person (not a tool's result): where a turn starts. */
 function startsTurn(entry) {
     if (entry.type !== 'user' || entry.isMeta || entry.message?.role !== 'user')
@@ -170,7 +180,7 @@ export async function stopcheck(io, options) {
         const text = typeof input.last_assistant_message === 'string' && input.last_assistant_message.trim()
             ? input.last_assistant_message
             : turn.text;
-        if (turn.posted || !text || saysPosted(text) || !itemsForPerson(text))
+        if (turn.posted || !text || saysPosted(text) || saysNoCard(text) || !itemsForPerson(text))
             return 0;
         io.out(`${JSON.stringify({ decision: 'block', reason: STOP_REASON })}\n`);
         return 0;

package/dist/version.js

@@ -1,2 +1,2 @@
 // The command line's version, as published (package.json). A test keeps them the same.
-export const VERSION = '0.5.0';
+export const VERSION = '0.7.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pendingyou",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Pending You for Claude Code: hear your answers from Pending You in the background, and set Claude Code up in one command.",
   "license": "Apache-2.0",
   "homepage": "https://www.pendingyou.com",