pendingyou 0.9.0 → 0.10.0

package/dist/main.js

@@ -2,13 +2,15 @@
 // it with their own Io.
 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 { claudeState, installClaude, mcpFromFile, readManifest, uninstallClaude } from "./claude.js";
+import { connectionClient, connectionMachine, readCredential, saveConnectionClient, signedInOrigins, updateCredential, } from "./credentials.js";
 import { differs, serverForFolder, siteOf } from "./environment.js";
 import { PlainError } from "./errors.js";
 import { hold } from "./hold.js";
+import { MOD_CLAUDE, PLUGIN_DIRS } from "./mod.js";
 import { OAuthError, revoke, signIn, signInWithDevice } from "./oauth.js";
 import { pickup } from "./pickup.js";
+import { checkHelper, computerName, foundBy, headlessReason, helperPath, isRemoteSetup, machineOf, mcpHeaders, usesHelper, } from "./remote.js";
 import { stopcheck } from "./stopcheck.js";
 import { VERSION } from "./version.js";
 import { watch } from "./watch.js";
@@ -30,27 +32,89 @@ async function checkSignIn(io, origin) {
         return { state: 'unreachable' };
     }
 }
+/** `--origin <it>` for a command to run next, when it isn't production. */
+const originFlag = (origin) => (origin === DEFAULT_ORIGIN ? '' : ` --origin ${origin}`);
+/** What a computer's Claude Code connection is called: "Claude Code on devbox". */
+const titleOf = (machine) => machine ? `Claude Code on ${machine}` : 'Claude Code on this computer';
+/** This computer's connection's title: by the name it signed in with, else its hostname. */
+const connectionTitle = async (io, origin) => titleOf((await connectionMachine(io, origin)) ?? machineOf(io.host));
+/** A connection's title as Pending You has it: "Claude Code on devbox". */
+const serverTitle = (heard) => heard.machine ? `${heard.name} on ${heard.machine}` : heard.name;
+/** How to give this computer's connection another name: sign in again under it, which renames the connection. */
+const renameAdvice = (origin) => `To call it something friendlier, run: npx pendingyou login --name <name>${originFlag(origin)}\n`;
+/**
+ * Whether Claude Code here signs in through this computer's own sign-in for `origin` (remote.ts): its pendingyou MCP
+ * server runs our headersHelper, or init recorded that it set it up so. Then a sign-in must be that connection.
+ */
+async function signsInThroughHelper(io, origin) {
+    if (io.platform === 'win32')
+        return false;
+    const server = await mcpFromFile(io);
+    if (server !== 'unknown')
+        return usesHelper(server, origin);
+    const manifest = await readManifest(io);
+    return Boolean(manifest?.helper && manifest.origin === origin);
+}
 async function login(io, options) {
-    if (!options.force && (await readCredential(io, options.origin))) {
+    const connection = options.connection ?? (await signsInThroughHelper(io, options.origin));
+    if (connection && options.device === false)
+        throw new PlainError(`Claude Code on this computer signs in through this computer’s own sign-in, which you approve with a code on your phone. Run npx pendingyou login${originFlag(options.origin)} without --browser.`);
+    const current = await readCredential(io, options.origin);
+    if (!options.force && current && (!connection || current.kind === 'connection')) {
         const check = await checkSignIn(io, options.origin);
-        if (check.state === 'ok') {
+        // Another name for this computer's connection signs in again (one approval), which renames it on Pending You.
+        const known = check.state === 'ok' ? check.for?.machine : undefined;
+        const renaming = connection &&
+            options.machine !== undefined &&
+            options.machine !== (known ?? (await connectionMachine(io, options.origin)));
+        if (check.state === 'ok' && !renaming) {
             io.out(`Already signed in to Pending You at ${options.origin}.\n`);
             return 0;
         }
     }
     const previous = await readCredential(io, options.origin);
-    const { clientId, tokens } = options.device
-        ? await signInWithDevice(io, { origin: options.origin })
-        : await signIn(io, { origin: options.origin, browser: options.browser });
+    // A code on the phone: for a connection, when asked, or with no browser here (an SSH session).
+    const device = connection || (options.device ?? headlessReason(io) !== null);
+    // What the phone and the Assistants page call this computer: --name, Tailscale's name, or the hostname.
+    const named = device ? await computerName(io, options.machine) : null;
+    const machine = named?.name ?? '';
+    const { clientId, tokens } = connection
+        ? await signInWithDevice(io, {
+            origin: options.origin,
+            machine,
+            connection: true,
+            clientId: await connectionClient(io, options.origin),
+        })
+        : device
+            ? await signInWithDevice(io, { origin: options.origin, machine })
+            : await signIn(io, { origin: options.origin, browser: options.browser });
     await updateCredential(io, options.origin, () => ({
         clientId,
         ...tokens,
         signedInAt: new Date(io.now()).toISOString(),
+        ...(connection ? { kind: 'connection' } : {}),
     }));
+    if (connection)
+        await saveConnectionClient(io, options.origin, clientId, machine);
     // The sign-in this one replaces is revoked, so only one is live per computer.
     if (previous)
         await revoke(io, options.origin, previous.clientId, previous.refreshToken);
-    io.out('Signed in. Claude Code on this computer can now hear your answers from Pending You, even while it’s idle.\n');
+    if (connection) {
+        // A connection's sign-in hears for that connection, by name. A Pending You from before connections by code
+        // answers with the command line's own sign-in instead, whose token /mcp refuses: say so, rather than hand it to
+        // Claude Code.
+        const check = await checkSignIn(io, options.origin);
+        if (check.state === 'ok' && !check.for) {
+            await updateCredential(io, options.origin, (current) => current ? { ...current, kind: undefined } : null);
+            throw new PlainError(`Pending You at ${options.origin} doesn’t connect Claude Code on a computer with no browser yet, so this computer is signed in only to hear answers. Try again once it’s updated.`);
+        }
+    }
+    io.out(connection
+        ? `Signed in: ${titleOf(machine)} can ask you questions and hear your answers, with no browser here.\n`
+        : 'Signed in. Claude Code on this computer can now hear your answers from Pending You, even while it’s idle.\n');
+    // A cloud's own name ("ip-10-42-1-252"): kept, since there's nothing better, with how to change it.
+    if (connection && named?.unfriendly)
+        io.out(`It’s named after this computer’s hostname. ${renameAdvice(options.origin)}`);
     return 0;
 }
 async function logout(io, options) {
@@ -72,64 +136,150 @@ async function logout(io, options) {
     return 0;
 }
 async function status(io, origin) {
-    const [signIn, claude, here] = await Promise.all([
+    const [signIn, claude, here, credential, manifest] = await Promise.all([
         checkSignIn(io, origin),
         claudeState(io),
         serverForFolder(io, io.cwd),
+        readCredential(io, origin),
+        readManifest(io),
     ]);
-    const lines = [`Pending You for Claude Code · ${origin}`];
+    const flag = originFlag(origin);
+    const mcp = claude.mcp;
+    // A computer with no browser (remote.ts): Claude Code's server signs in through the helper, and the sign-in is its
+    // connection. What's set up and what's missing is said for that, with the command that fixes it.
+    const helped = usesHelper(mcp, origin);
+    const remote = isRemoteSetup(io, null, helped || Boolean(manifest?.helper && manifest.origin === origin));
+    const why = remote ? headlessReason(io) : null;
+    const lines = [
+        `Pending You for Claude Code · ${origin}${remote ? (why ? ` · no browser here (${why})` : ' · signs in without a browser') : ''}`,
+    ];
     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 sameServer = mcp !== false && mcp !== 'unknown' && (!mcp.url || mcp.url.replace(/\/+$/, '') === url);
+    const mcpOk = remote ? sameServer && helped : sameServer;
     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}, so sessions post cards where these hooks don’t hear them; run npx pendingyou init${origin === DEFAULT_ORIGIN ? '' : ` --origin ${origin}`} to replace it`;
+            ? `not added; run npx pendingyou init${flag}`
+            : !sameServer
+                ? `points at ${mcp.url}, not ${url}, so sessions post cards where these hooks don’t hear them; run npx pendingyou init${flag} to replace it`
+                : !remote
+                    ? `pendingyou${mcp.url ? ` (${mcp.url})` : ''}`
+                    : helped
+                        ? `pendingyou (${mcp.url}), signed in through ${helperPath(io)}`
+                        : mcp.helper
+                            ? `pendingyou (${mcp.url}) signs in through a headersHelper of its own (${mcp.helper}); run npx pendingyou init${flag} to use this computer’s sign-in`
+                            : `pendingyou (${mcp.url}) signs in through a browser, 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
+        ? `needs Claude Code ${MOD_CLAUDE} or later`
+        : !mod.loads
+            ? `needs Claude Code ${MOD_CLAUDE} or later (this is ${claude.claude}); until then, a background hold wakes it`
+            : mod.present
+                ? `in ${PLUGIN_DIRS} (${mod.dirs.join(', ')}); a session is woken when you answer, with no hold running`
+                : mod.plugin
+                    ? 'in the Pending You plugin; a session is woken when you answer, with no hold running'
+                    : mod.dirs.length
+                        ? `${mod.dirs.join(', ')} is gone; run npx pendingyou@latest init${flag}`
+                        : `not installed; run npx pendingyou@latest init${flag}`;
     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`
+                : `the Node or the copy of pendingyou they run is gone (${form.node}, ${form.script}); run npx pendingyou@latest init${flag}`
             : form.form === 'npx'
-                ? 'they run through npx, which is slower; run npx pendingyou@latest init to run them directly'
+                ? `they run through npx, which is slower; run npx pendingyou@latest init${flag} 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)`
-            : `hears for ${signIn.connections} Claude Code connection${signIn.connections === 1 ? '' : 's'}`
-        : signIn.state === 'ended'
-            ? '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(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'}`);
+    // Remote: 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
+        ? serverTitle(signIn.for)
+        : await connectionTitle(io, origin);
+    const connected = credential?.kind === 'connection';
+    const signOk = signIn.state === 'ok' && (!remote || connected);
+    const signText = remote
+        ? signIn.state === 'ok'
+            ? connected
+                ? `this computer’s own connection, ${title}; Claude Code here asks and hears through it`
+                : `this computer’s sign-in only hears answers, so Claude Code here can’t use it; run ${fix}`
+            : signIn.state === 'ended'
+                ? `ended; run ${fix}`
+                : signIn.state === 'none'
+                    ? `not signed in; run ${fix} (you approve a code on your phone)`
+                    : 'Pending You couldn’t be reached'
+        : signIn.state === 'ok'
+            ? signIn.for
+                ? `hears for ${signIn.for.name} only (for pendingyou watch)`
+                : `hears for ${signIn.connections} Claude Code connection${signIn.connections === 1 ? '' : 's'}`
+            : signIn.state === 'ended'
+                ? `ended; run npx pendingyou login${flag}`
+                : 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 helper = remote ? await checkHelper(io, origin) : null;
+    lines.push(`  ${mark(signOk)} Sign-in: ${signText}`, `  ${mark(claude.claude !== null)} Claude Code: ${claude.claude ?? 'not found on PATH'}`, `  ${mark(mcpOk)} MCP server: ${mcpText}`, ...(helper
+        ? [
+            `  ${mark(helper.ok)} Sign-in helper: ${helper.ok
+                ? `${helper.node} (${foundBy(helper.from)}) runs pendingyou ${helper.version}, even for a Claude Code started without your shell’s PATH`
+                : `${helper.why}; run npx pendingyou init${flag}`}`,
+        ]
+        : []), `  ${mark(claude.skill)} Skill: ${claude.skill ? 'saved' : `not saved; run npx pendingyou init${flag}`}`, `  ${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}`);
     // 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;
-    const ready = signIn.state === 'ok' && claude.hooks && hooksRun && !other;
+    // Remote, Claude Code reaches Pending You only through the helper, the connection and the server together.
+    const reaches = !remote || (signOk && mcpOk && helper?.ok === true);
+    const ready = reaches && signIn.state === 'ok' && claude.hooks && hooksRun && !other;
     if (other)
         lines.push(`Mismatch: Claude Code’s MCP server is ${siteOf(other.url)} but the hooks and sign-in are ${siteOf(origin) ?? origin}. Use the one you look at (npx pendingyou init --origin <it>), then restart your Claude Code sessions.`);
     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").');
+        ? remote
+            ? 'Ready: Claude Code here signs in with no browser, and hears answers right away (report_setup hears "instant").'
+            : 'Ready: Claude Code hears answers right away (report_setup hears "instant").'
+        : reaches
+            ? 'Not ready: Claude Code hears answers while it’s working (report_setup hears "while-working").'
+            : 'Not ready: Claude Code here can’t reach Pending You until the lines marked missing are fixed.');
     io.out(`${lines.join('\n')}\n`);
     return ready ? 0 : 1;
 }
 async function init(io, options) {
     io.out(`Setting up Pending You for Claude Code (${options.origin}).\n`);
-    const steps = await installClaude(io, options.origin, {
-        yes: options.yes,
-        report: (step) => io.out(`  ${step.ok ? 'ok     ' : 'check  '} ${step.text}\n`),
-    });
+    const name = options.machine ? { machine: options.machine } : {};
+    const report = (step) => io.out(`  ${step.ok ? 'ok     ' : 'check  '} ${step.text}\n`);
+    // A computer with no browser (remote.ts): one code approved on the phone signs Claude Code in, then the rest.
+    if (isRemoteSetup(io, options.device, await signsInThroughHelper(io, options.origin))) {
+        const why = options.device ? null : headlessReason(io);
+        io.out(`${why ? `No browser here (${why}), so ` : ''}Claude Code here signs in through this computer’s own sign-in, which you approve once with a code on your phone.\n`);
+        if (options.login)
+            await login(io, {
+                origin: options.origin,
+                browser: false,
+                force: false,
+                device: true,
+                connection: true,
+                ...name,
+            });
+        else
+            io.out(`Skipped signing in. Run npx pendingyou login${originFlag(options.origin)} when you’re ready: you approve a code on your phone.\n`);
+        const steps = await installClaude(io, options.origin, {
+            yes: options.yes,
+            report,
+            remote: true,
+        });
+        io.out('Next: start Claude Code here (claude, in the folder you work in) and ask it to finish setting up Pending You. It’s signed in already, so there’s nothing to Authenticate in /mcp. If it’s running, restart it first (/exit, then claude --continue).\n');
+        return steps.every((step) => step.ok) ? 0 : 1;
+    }
+    const steps = await installClaude(io, options.origin, { yes: options.yes, report });
     if (options.login) {
         io.out('Signing this computer in, so answers can wake Claude Code:\n');
         await login(io, {
@@ -137,18 +287,25 @@ async function init(io, options) {
             browser: options.browser,
             device: options.device,
             force: false,
+            ...name,
         });
     }
     else
-        io.out('Skipped signing in. Run npx pendingyou login when you’re ready.\n');
+        io.out(`Skipped signing in. Run npx pendingyou login${originFlag(options.origin)} when you’re ready.\n`);
     io.out('Next, in Claude Code: if it’s open, restart it (/exit, then claude --continue), run /mcp, choose pendingyou and Authenticate. Then ask Claude Code to finish setting up Pending You.\n');
     return steps.every((step) => step.ok) ? 0 : 1;
 }
 async function uninstall(io, origin) {
+    const credential = await readCredential(io, origin);
+    const title = await connectionTitle(io, origin);
     const steps = await uninstallClaude(io);
     for (const step of steps)
         io.out(`  ${step.ok ? 'ok     ' : 'check  '} ${step.text}\n`);
     await logout(io, { origin, all: false });
+    await saveConnectionClient(io, origin, null);
+    // Its connection outlives the sign-in on Pending You's side: only the person removes it.
+    if (credential?.kind === 'connection')
+        io.out(`${title} is still on your Assistants page (${origin}/app/assistants): remove it there if you won’t use it again.\n`);
     return steps.every((step) => step.ok) ? 0 : 1;
 }
 async function run(io, command, hook = { fallback: '' }) {
@@ -186,6 +343,9 @@ async function run(io, command, hook = { fallback: '' }) {
             }
             catch { }
             return 0;
+        case 'mcp-headers':
+            // Claude Code's headersHelper on a computer with no browser: stdout is the headers and nothing else.
+            return mcpHeaders(io, command);
     }
 }
 /**

package/dist/mod.js

@@ -0,0 +1,87 @@
+// The wake mod (0.10.0, guide 2.24): the Pending You plugin's mod, which this package carries in mod/ for Claude Code
+// set up with `npx pendingyou init` and no plugin. Claude Code 2.1.287 and later load it from CLAUDE_CODE_PLUGIN_DIRS
+// (`env` in ~/.claude/settings.json). Every session then learns the cards it posts, checks them through its own
+// Pending You connection, and is woken when the person answers, with no hold running; a hold an agent still starts is
+// answered by the mod. `init` adds the copy inside the hooks' private copy (install.ts), keeping every other entry and
+// replacing an older version's; `uninstall` takes it out; `status` says whether it's there. With the Pending You plugin
+// installed too, the two copies agree that one acts.
+import { join } from 'node:path';
+/** The first Claude Code that loads mods. */
+export const MOD_CLAUDE = '2.1.287';
+/** Where Claude Code finds plugin folders to load as --plugin-dir does. */
+export const PLUGIN_DIRS = 'CLAUDE_CODE_PLUGIN_DIRS';
+/** The Pending You plugins, which carry the same mod: production's, and staging's for our own testing. */
+export const PLUGINS_WITH_MOD = ['pending-you@pendingyou', 'pending-you-staging@pendingyou-staging'];
+/** The mod in a copy of this package (its folder in node_modules). */
+export const modDir = (packageRoot) => join(packageRoot, 'mod');
+/** Claude Code's version from `claude --version` ("2.1.289 (Claude Code)"); null when it can't be read. */
+export function claudeVersion(output) {
+    return /^\s*(\d+\.\d+\.\d+)\b/.exec(output)?.[1] ?? null;
+}
+/** Whether that Claude Code loads mods (2.1.287 or later). */
+export function loadsMods(version) {
+    const have = version.split('.').map(Number);
+    const want = MOD_CLAUDE.split('.').map(Number);
+    for (let index = 0; index < want.length; index++) {
+        const a = have[index] ?? 0;
+        const b = want[index] ?? 0;
+        if (a !== b)
+            return a > b;
+    }
+    return true;
+}
+/** Whether a CLAUDE_CODE_PLUGIN_DIRS entry is a copy of this mod, from any version of this package. */
+export const isOurModDir = (entry) => /(^|[\\/])node_modules[\\/]pendingyou[\\/]mod[\\/]?$/.test(entry.trim());
+/** What Claude Code splits CLAUDE_CODE_PLUGIN_DIRS on. */
+export const separatorFor = (platform) => (platform === 'win32' ? ';' : ':');
+const objectAt = (parent, key) => {
+    const value = parent[key];
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+};
+/** The entries of CLAUDE_CODE_PLUGIN_DIRS in settings' `env`; null when it's there but isn't text. */
+export function pluginDirs(settings, separator) {
+    const env = objectAt(settings, 'env');
+    if (settings.env !== undefined && env === null)
+        return null;
+    const value = env?.[PLUGIN_DIRS];
+    if (value === undefined)
+        return [];
+    if (typeof value !== 'string')
+        return null;
+    return value.split(separator).filter((entry) => entry.trim() !== '');
+}
+/**
+ * Settings with the mod at `dir` in CLAUDE_CODE_PLUGIN_DIRS, or with none of ours when `dir` is null: every other entry
+ * kept as it was, in its place, and any copy of ours (an older version's) replaced. `changed` is false when there was
+ * nothing to do; `invalid` says why the settings were left alone.
+ */
+export function withModDir(settings, dir, separator) {
+    const entries = pluginDirs(settings, separator);
+    if (entries === null)
+        return {
+            invalid: `Claude Code’s settings have an “env” or ${PLUGIN_DIRS} that I can’t read, so I left them alone.`,
+        };
+    if (dir?.includes(separator))
+        return { invalid: `The wake mod’s folder has a “${separator}” in its path: ${dir}` };
+    const wanted = [...entries.filter((entry) => !isOurModDir(entry)), ...(dir ? [dir] : [])];
+    if (wanted.join(separator) === entries.join(separator))
+        return { settings, changed: false };
+    const next = structuredClone(settings);
+    const env = objectAt(next, 'env') ?? {};
+    if (wanted.length)
+        env[PLUGIN_DIRS] = wanted.join(separator);
+    else
+        delete env[PLUGIN_DIRS];
+    if (Object.keys(env).length)
+        next.env = env;
+    else
+        delete next.env;
+    return { settings: next, changed: true };
+}
+/** Whether settings enable a Pending You plugin, which carries the mod itself. */
+export function pluginEnabled(settings) {
+    const enabled = objectAt(settings, 'enabledPlugins');
+    return PLUGINS_WITH_MOD.some((id) => enabled?.[id] === true);
+}

package/dist/oauth.js

@@ -3,11 +3,14 @@
 // consent page with PKCE (S256), and hears the code back on a one-time loopback address (127.0.0.1, any free port).
 // The consent page recognises the command line by that name and the loopback address, and gives it a grant that only
 // hears answers to your Claude Code assistants' questions: it isn't an assistant, and can't ask or answer anything.
+// On a computer with no browser it signs in with a code instead (RFC 8628, signInWithDevice), and there `init` asks
+// for more: a Claude Code connection of this computer's own, whose token Claude Code's MCP server uses too (remote.ts).
 //
 // Access tokens last 15 minutes and refresh on their own; refresh tokens rotate on every use. Nothing here prints or
 // logs a token, a code or a verifier.
 import { createHash, randomBytes } from 'node:crypto';
 import { createServer } from 'node:http';
+import { qrLines } from "./qr.js";
 import { VERSION } from "./version.js";
 /** The name the consent page knows the command line by (apps/pendingyou/worker/oauth/authorize.ts). */
 export const CLIENT_NAME = 'Pending You CLI';
@@ -237,18 +240,31 @@ export async function revoke(io, origin, clientId, refreshToken) {
     }
 }
 /**
- * Device sign-in (RFC 8628) for a computer with no browser: shows a short code and where to enter it, then polls until
- * the person presses Allow on their phone (or Cancel, or the code runs out).
+ * Device sign-in (RFC 8628) for a computer with no browser: shows a short code, where to enter it and, at a terminal, a
+ * QR code that opens that page with the code filled in; then polls until the person presses Allow on their phone (or
+ * Cancel, or the code runs out).
  */
 export async function signInWithDevice(io, options) {
     const metadata = await discover(io, options.origin);
-    const clientId = await register(io, metadata);
-    const started = await io.fetch(`${options.origin}/oauth/device`, {
+    const begin = (client) => io.fetch(`${options.origin}/oauth/device`, {
         method: 'POST',
         headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
-        body: new URLSearchParams({ client_id: clientId, scope: SCOPE }).toString(),
+        body: new URLSearchParams({
+            client_id: client,
+            scope: SCOPE,
+            ...(options.machine ? { machine: options.machine } : {}),
+            ...(options.connection ? { assistant: 'claude-code' } : {}),
+        }).toString(),
         signal: AbortSignal.timeout(15_000),
     });
+    let clientId = options.clientId || (await register(io, metadata));
+    let started = await begin(clientId);
+    if (started.status === 401 && options.clientId) {
+        // Pending You no longer knows that client (a registration lapses after 90 days unused): register again.
+        await started.body?.cancel();
+        clientId = await register(io, metadata);
+        started = await begin(clientId);
+    }
     const start = (await started.json().catch(() => ({})));
     if (!started.ok || typeof start.device_code !== 'string' || typeof start.user_code !== 'string')
         throw new OAuthError(start.error ?? `http_${started.status}`, start.error === 'slow_down'
@@ -257,8 +273,13 @@ export async function signInWithDevice(io, options) {
     const page = start.verification_uri ?? `${options.origin}/device`;
     if (new URL(page).origin !== options.origin)
         throw new OAuthError('discovery', 'Pending You sent the sign-in page somewhere else.');
+    const direct = start.verification_uri_complete ?? `${page}?code=${start.user_code}`;
+    const qr = io.interactive && new URL(direct).origin === options.origin ? qrLines(direct, io.env) : null;
     io.err(`On your phone or any browser, open ${page} and enter this code:\n\n    ${start.user_code}\n\n` +
-        `Or go straight to ${start.verification_uri_complete ?? `${page}?code=${start.user_code}`}\nWaiting for you to press Allow…\n`);
+        (qr
+            ? `Or scan this with your phone’s camera, which opens it with the code filled in:\n\n${qr.join('\n')}\n\nOr go straight to ${direct}\n`
+            : `Or go straight to ${direct}\n`) +
+        'Waiting for you to press Allow…\n');
     let interval = Math.max(1, start.interval ?? 5) * 1000;
     const deadline = io.now() + Math.max(60, start.expires_in ?? 600) * 1000;
     for (;;) {

package/dist/pickup.js

@@ -6,8 +6,10 @@
 //   Pending You: …"). While signed in, it also adds one short line (REMINDER) to every message, so an assistant
 //   deep in a long conversation still puts what it needs from the person on a card, and that line names this folder's
 //   cards still waiting on the person (openLine), so one they answer in chat gets cancelled with answeredHere. That's
-//   one small request per message (the open cards, and answers too while a hold from this computer is outstanding),
-//   time-boxed short; on any error, or from a server too old to list open cards, the line is the plain reminder.
+//   one small request per message (the open cards and this folder's answers together), time-boxed short; on any
+//   error, or from a server too old to list open cards, the line is the plain reminder. Until 0.10.0 it looked for
+//   answers only while a hold had left an entry behind, so an answer to a card no hold ever waited on stayed unheard
+//   until the next session (2026-10-04).
 //
 // Both also add one line when the session's pendingyou MCP server is another Pending You than the hooks' origin
 // (environment.ts): its cards would go where these hooks, and maybe its person, don't look.
@@ -15,13 +17,14 @@
 // 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 { getJson, SESSION_APP, SignInNeeded } from "./api.js";
 import { readCredential } from "./credentials.js";
 import { environmentWarning } from "./environment.js";
-import { clip, describe, isClosed } from "./format.js";
-import { markHanded, momentOf, waitingOn, wasHanded } from "./state.js";
+import { clip, describe } from "./format.js";
+import { holdCommand } from "./hold.js";
+import { markHanded, momentOf, wasHanded } from "./state.js";
 /** Each request's own limit, inside the hook's 3-second deadline (main.ts). */
-const TIME_BOX_MS = { pickup: 2500, handoff: 2000, open: 1500 };
+const TIME_BOX_MS = { pickup: 2500, handoff: 2000 };
 /** 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. */
@@ -87,26 +90,25 @@ export async function pickup(io, options, hook = { fallback: '' }) {
         warning = await environmentWarning(io, cwd, origin);
         if (warning)
             hook.fallback = `${warning}\n`;
-        // The hand-off hears answers only while a hold from this computer is outstanding; it always asks for open cards.
-        let answers = true;
+        // The hand-off asks for this folder's answers and its open cards in one request, whether or not a hold ran.
         if (mode === 'handoff') {
             if ((await readCredential(io, origin)) === null)
                 return 0;
             line = REMINDER;
             hook.fallback = `${[REMINDER, warning].filter(Boolean).join('\n')}\n`;
-            answers = (await waitingOn(io, origin)).length > 0;
         }
         const query = new URLSearchParams([
             ...folderForms(cwd, io.home).map((form) => ['cwd', form]),
-            ['limit', answers ? '5' : '0'],
+            ['limit', '5'],
             ...(mode === 'handoff' ? [['open', String(OPEN_SHOWN)]] : []),
+            ['source', SESSION_APP],
         ]);
-        const { status, body } = await getJson(io, origin, `/mcp/cli/answers?${query}`, answers ? TIME_BOX_MS[mode] : TIME_BOX_MS.open, io.signal, { hook: true });
+        const { status, body } = await getJson(io, origin, `/mcp/cli/answers?${query}`, TIME_BOX_MS[mode], io.signal, { hook: true });
         if (status !== 200)
             return 0;
         if (mode === 'handoff')
             line = openLine(body.open);
-        if (!answers || !Array.isArray(body.requests))
+        if (!Array.isArray(body.requests))
             return 0;
         const fresh = [];
         for (const heard of body.requests)
@@ -114,7 +116,7 @@ export async function pickup(io, options, hook = { fallback: '' }) {
                 fresh.push(heard);
         if (fresh.length === 0)
             return 0;
-        const again = (id) => `run \`npx pendingyou hold ${id}\` in the background`;
+        const again = (id) => `run \`${holdCommand(id, origin)}\` 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(`${[
@@ -129,11 +131,7 @@ export async function pickup(io, options, hook = { fallback: '' }) {
         ].join('\n')}\n`);
         line = null;
         warning = null;
-        await markHanded(io, origin, fresh.map((heard) => ({
-            requestId: heard.requestId,
-            moment: momentOf(heard),
-            closed: isClosed(heard),
-        })));
+        await markHanded(io, origin, fresh.map((heard) => ({ requestId: heard.requestId, moment: momentOf(heard) })));
         return 0;
     }
     catch (error) {