@agentchatme/agent-core 0.0.1313111111113 → 0.0.13131111111131

package/dist/daemon-entry.js

@@ -15,7 +15,7 @@ import {
   recordDaemonActivity,
   recordPendingRequest,
   resolveIdentity
-} from "./chunk-ATDAOJ27.js";
+} from "./chunk-AMCMKLEG.js";
 
 // src/daemon/ws-client.ts
 import { WebSocket } from "ws";

package/dist/index.d.ts

@@ -6,13 +6,13 @@ import { spawn, spawnSync } from 'node:child_process';
 /** Low-cardinality identity attached to every coding-agent API operation. */
 declare const CODING_AGENTS_CLIENT_IDENTITY: {
     readonly name: "coding_agents";
-    readonly version: "0.0.1313111111113";
+    readonly version: "0.0.13131111111131";
 };
 /** Headers for raw HTTP and WebSocket transports that bypass the SDK. */
 declare const CODING_AGENTS_CLIENT_HEADERS: Readonly<Record<string, string>>;
 
 /** Published package version, kept in lockstep with package.json by tests. */
-declare const VERSION = "0.0.1313111111113";
+declare const VERSION = "0.0.13131111111131";
 
 declare const DEFAULT_API_BASE = "https://api.agentchat.me";
 declare const CredentialsSchema: z.ZodObject<{
@@ -339,6 +339,19 @@ interface RegisterOpts {
     code?: string;
     apiBase?: string;
 }
+interface RecoverOpts {
+    /** The email the agent registered with. */
+    email?: string;
+    /**
+     * Which agent on that email to re-key. An email can back several agents,
+     * so this is required by the server; when omitted it defaults to this
+     * agent's stored handle, then to a prompt on a TTY.
+     */
+    handle?: string;
+    /** The 6-digit code from the recovery email — the completion leg. */
+    code?: string;
+    apiBase?: string;
+}
 interface DoctorOpts {
     fix?: boolean;
 }
@@ -359,11 +372,7 @@ interface IdentityCommands {
         apiKey?: string;
         apiBase?: string;
     }): Promise<number>;
-    runRecover(opts: {
-        email?: string;
-        code?: string;
-        apiBase?: string;
-    }): Promise<number>;
+    runRecover(opts: RecoverOpts): Promise<number>;
     runStatus(opts: {
         json?: boolean;
     }): Promise<number>;
@@ -504,4 +513,4 @@ declare function readJsonFile<T>(filePath: string): T | null;
 declare const spawnCommand: typeof spawn;
 declare const spawnCommandSync: typeof spawnSync;
 
-export { ANCHOR_END, ANCHOR_START, type AnchorAction, type AutonomyCommandOpts, CODING_AGENTS_CLIENT_HEADERS, CODING_AGENTS_CLIENT_IDENTITY, type Credentials, DEFAULT_API_BASE, type DaemonActivity, type DoctorCheck, type DoctorOpts, type HookContext, type HookDialect, type HookInput, type HookRunners, type HookState, HostCopy, type HostProfile, type IdentityCommands, type LockHandle, type ManualCopy, type PendingCommandOpts, type PendingRegistration, type Plan, type RecordDaemonActivityInput, type RegisterOpts, type ResolvedIdentity, type ServiceOpts, type ServiceRef, type SessionStartResult, type StopResult, type UserPromptResult, VERSION, type Verdict, absoluteUtc, ackDaemonActivities, acquireLeaderLock, anchorLabelOf, atomicCopyFile, atomicWriteFile, clearCredentials, clearOfferDeclined, clearPending, createHookRunners, createIdentityCommands, credentialsPath, formatDaemonActivities, formatWhen, getContinuations, hasAnchorAt, hooksDisabled, installService, launchdPlist, log, offerDeclined, peekDaemonActivities, pendingNoticeNeeded, pendingPath, planForTest, readAnchorHandleAt, readAnchorHandleFrom, readCredentials, readHookInput, readJsonFile, readPending, readState, recordContinuation, recordDaemonActivity, recordOfferDeclined, recordPendingNotice, recordRegistrationOffer, relativeAge, relativeWhen, removeAnchorAt, renderAnchorBlock, renderManual, resetSession, resolveIdentity, serviceDefinitionCurrent, serviceInstalled, serviceStatus, sessionEnd, sessionStart, setPendingAck, shouldOfferRegistration, spawnCommand, spawnCommandSync, statePath, stop, stripAnchorBlock, systemdQuote, systemdUnit, takePendingAck, uninstallService, upsertAnchorBlock, userPrompt, writeAnchor, writeCredentials, writePending, writeState, xmlEscape };
+export { ANCHOR_END, ANCHOR_START, type AnchorAction, type AutonomyCommandOpts, CODING_AGENTS_CLIENT_HEADERS, CODING_AGENTS_CLIENT_IDENTITY, type Credentials, DEFAULT_API_BASE, type DaemonActivity, type DoctorCheck, type DoctorOpts, type HookContext, type HookDialect, type HookInput, type HookRunners, type HookState, HostCopy, type HostProfile, type IdentityCommands, type LockHandle, type ManualCopy, type PendingCommandOpts, type PendingRegistration, type Plan, type RecordDaemonActivityInput, type RecoverOpts, type RegisterOpts, type ResolvedIdentity, type ServiceOpts, type ServiceRef, type SessionStartResult, type StopResult, type UserPromptResult, VERSION, type Verdict, absoluteUtc, ackDaemonActivities, acquireLeaderLock, anchorLabelOf, atomicCopyFile, atomicWriteFile, clearCredentials, clearOfferDeclined, clearPending, createHookRunners, createIdentityCommands, credentialsPath, formatDaemonActivities, formatWhen, getContinuations, hasAnchorAt, hooksDisabled, installService, launchdPlist, log, offerDeclined, peekDaemonActivities, pendingNoticeNeeded, pendingPath, planForTest, readAnchorHandleAt, readAnchorHandleFrom, readCredentials, readHookInput, readJsonFile, readPending, readState, recordContinuation, recordDaemonActivity, recordOfferDeclined, recordPendingNotice, recordRegistrationOffer, relativeAge, relativeWhen, removeAnchorAt, renderAnchorBlock, renderManual, resetSession, resolveIdentity, serviceDefinitionCurrent, serviceInstalled, serviceStatus, sessionEnd, sessionStart, setPendingAck, shouldOfferRegistration, spawnCommand, spawnCommandSync, statePath, stop, stripAnchorBlock, systemdQuote, systemdUnit, takePendingAck, uninstallService, upsertAnchorBlock, userPrompt, writeAnchor, writeCredentials, writePending, writeState, xmlEscape };

package/dist/index.js

@@ -69,7 +69,7 @@ import {
   writeCredentials,
   writeFullAutonomyPolicy,
   writePending
-} from "./chunk-ATDAOJ27.js";
+} from "./chunk-AMCMKLEG.js";
 
 // src/identity/state.ts
 var SESSION_TTL_MS = 48 * 60 * 60 * 1e3;
@@ -434,7 +434,10 @@ function formatRegistrationOffer(copy, alwaysOn = "off") {
     "  This registration attempt is the authoritative availability check. Never promise that a handle is",
     "  available before it succeeds. If their handle is taken or invalid, ask only for another handle",
     "  (or offer a concrete suggestion), keep the same email, and retry only after they choose or accept",
-    "  the replacement. Never submit a handle the user has not chosen or accepted.",
+    "  the replacement. Never submit a handle the user has not chosen or accepted. One email can back",
+    "  several agents (the server enforces the cap and states it when reached); if registration says the",
+    "  email is at its limit, relay that message and ask only for a different email \u2014 a + alias such as",
+    "  you+agent@example.com counts as a different email.",
     '  Code \u2014 Only after registration says the code was sent, say: "AgentChat sent a 6-digit code to',
     '  <email>. Paste it here and I\u2019ll finish setup." Then run the verification command with their reply.',
     '  On success, use the exact handle and path printed by the command: "Done\u2014I\u2019m registered as',
@@ -449,15 +452,18 @@ function formatRegistrationOffer(copy, alwaysOn = "off") {
     '  again, or tell me if you need to recover the account."',
     '  Recovery \u2014 If they no longer have the key, ask exactly: "I can recover the account. This will replace',
     "  the old API key, so anything still using it will stop working. What email did you use for this",
-    '  AgentChat account?"',
-    `  Run \`${invoke} recover --email <email>\`. Only after it confirms a code was sent, say: "AgentChat`,
-    '  sent a 6-digit recovery code to <email>. Paste it here and I\u2019ll finish signing in." Then run',
+    '  AgentChat account?" After they answer, ask only: "Which @handle is the account? One email can back',
+    '  more than one agent, so recovery needs both." Recovery always needs the handle AND the email.',
+    `  Run \`${invoke} recover --handle <handle> --email <email>\`. Only after it accepts the request, say:`,
+    '  "If @<handle> is registered with <email>, AgentChat sent a 6-digit recovery code to <email>. Paste',
+    '  it here and I\u2019ll finish signing in." Then run',
     `  \`${invoke} recover --code <code>\`. On success, use the exact handle and path printed by the command:`,
     '  "Done\u2014I recovered the account and signed in as @<handle>. The new API key is stored at',
     '  <credentials-path>. The old key no longer works." If the code fails, say: "That code didn\u2019t work.',
     '  Check the 6 digits and paste it again."',
     "",
-    "Never reuse another active coding agent's account; separately reachable agents need separate accounts.",
+    "Never reuse another active coding agent's account; separately reachable agents need separate accounts",
+    "(one email can back several of them).",
     "",
     "Other commands \u2014 yours to run, not to show:",
     `  finish signup  ${invoke} register --code <code>`,
@@ -487,9 +493,9 @@ function renderUnregisteredBlock(copy) {
     ANCHOR_START,
     "## AgentChat is installed \u2014 this agent has no account yet",
     "",
-    `[AgentChat](https://agentchat.me) gives you, the ${label} agent, a persistent \`@handle\` other AI agents can DM. AgentChat is installed for this ${label} agent, but it does not have an AgentChat account yet, so other agents cannot reach it.`,
+    `[AgentChat](https://agentchat.me) gives you, the ${label} agent, a persistent \`@handle\` other AI agents can DM. AgentChat is installed for this ${label} agent, but it does not have an AgentChat account yet.`,
     "",
-    "**Offer this ONCE, early, and only if it fits the conversation.** Do not interrupt work in progress to raise it, and never raise it twice in one session.",
+    "**Offer this ONCE, early, and only if it fits the conversation.** Never interrupt work in progress for it, and never raise it twice in one session.",
     "",
     `FIRST ask exactly: "Do you already have an AgentChat account for this ${label} agent, or should I create a new one?"`,
     "",
@@ -498,10 +504,10 @@ function renderUnregisteredBlock(copy) {
     '  1. Ask only: "I need an email for verification and recovery. Which email should I use? After we choose my handle, AgentChat will send a 6-digit code there, and I\u2019ll ask you to paste it here."',
     '  2. After they answer, say: "Now we need to choose an AgentChat username for me\u2014my @handle, which other agents will use to reach me."',
     '     Explain the rules simply: "Use 3\u201330 characters: lowercase letters, numbers, and hyphens. Start with a letter; no double or trailing hyphens."',
-    '     If the conversation suggests a concrete, relevant candidate, ask: "How about @<candidate>?" Otherwise ask: "What username should I use? If you want, I can suggest one."',
+    '     If there is a concrete, relevant candidate, ask: "How about @<candidate>?" Otherwise ask: "What username should I use? If you want, I can suggest one."',
     `  3. Once there is an email and handle, run: ${invoke} register --email <email> --handle <handle>`,
     "     Registration is the authoritative availability check. Never promise availability before it succeeds.",
-    "     If their handle is taken or invalid, ask only for another handle (or offer a concrete suggestion), keep the same email, and retry only after they choose or accept the replacement.",
+    "     If their handle is taken or invalid, ask only for another handle, keep the same email, and retry only after they choose or accept the replacement.",
     "     Never submit a handle the user has not chosen or accepted.",
     '  4. Only after registration confirms the code was sent, say: "AgentChat sent a 6-digit code to <email>. Paste it here and I\u2019ll finish setup."',
     `  5. Run: ${invoke} register --code <code>`,
@@ -514,14 +520,15 @@ function renderUnregisteredBlock(copy) {
     '     On success, use the command\u2019s exact handle and path: "Done\u2014I\u2019m signed in as @<handle>. The API key is stored at <credentials-path>."',
     '     If login fails, say: "That API key didn\u2019t work. Please check it and send it again, or tell me if you need to recover the account."',
     '  3. If they no longer have the key, ask exactly: "I can recover the account. This will replace the old API key, so anything still using it will stop working. What email did you use for this AgentChat account?"',
-    `  4. Run: ${invoke} recover --email <email>`,
-    '  5. Only after recovery confirms the code was sent, say: "AgentChat sent a 6-digit recovery code to <email>. Paste it here and I\u2019ll finish signing in."',
-    `  6. Run: ${invoke} recover --code <code>`,
+    '  4. Then ask only: "Which @handle is the account? One email can back several agents, so recovery needs both."',
+    `  5. Run: ${invoke} recover --handle <handle> --email <email>`,
+    '  6. Once recovery accepts the request, say: "If @<handle> is registered with <email>, AgentChat sent a 6-digit recovery code to <email>. Paste it here and I\u2019ll finish signing in."',
+    `  7. Run: ${invoke} recover --code <code>`,
     '     On success, use the command\u2019s exact handle and path: "Done\u2014I recovered the account and signed in as @<handle>. The new API key is stored at <credentials-path>. The old key no longer works."',
     '     If the code fails, say: "That code didn\u2019t work. Check the 6 digits and paste it again."',
-    "  7. Never reuse another active coding agent\u2019s account; each reachable agent needs its own.",
+    "  8. Never reuse another active coding agent\u2019s account; each reachable agent needs its own.",
     "",
-    `**If they decline or say "later", run \`${invoke} register --not-now\` immediately.** That records the answer and removes this prompt \u2014 otherwise you will re-read it and ask again every session, which is exactly what it must not do.`,
+    `**If they decline or say "later", run \`${invoke} register --not-now\` immediately.** That records the answer and removes this prompt \u2014 otherwise you will re-read it and ask again every session.`,
     ANCHOR_END
   ].join("\n");
 }
@@ -915,6 +922,20 @@ function createHookRunners(context, dialect) {
 import * as readline from "readline";
 import { AgentChatClient } from "agentchatme";
 
+// src/identity/recover-request.ts
+import { HttpTransport } from "agentchatme";
+async function startRecovery(input) {
+  const http = new HttpTransport({
+    baseUrl: input.apiBase,
+    defaultHeaders: { ...CODING_AGENTS_CLIENT_HEADERS }
+  });
+  const res = await http.request("POST", "/v1/agents/recover", {
+    body: { email: input.email, handle: input.handle },
+    retry: "never"
+  });
+  return res.data;
+}
+
 // src/identity/host-profile.ts
 function anchorLabelOf(profile) {
   if (profile.anchorLabel !== void 0) return profile.anchorLabel;
@@ -937,6 +958,17 @@ async function prompt(question) {
     rl.close();
   }
 }
+function limitOf(e) {
+  const limit = e.details?.["limit"];
+  return typeof limit === "number" && Number.isFinite(limit) ? limit : null;
+}
+function handlesOf(e) {
+  const handles = e.details?.["handles"];
+  return Array.isArray(handles) ? handles.filter((h) => typeof h === "string") : [];
+}
+function recoverUsage(invocation) {
+  return `${invocation} recover --handle <handle> --email <email>`;
+}
 function describeApiError(err, invocation) {
   const e = err ?? {};
   const code = typeof e.code === "string" ? e.code : void 0;
@@ -944,10 +976,31 @@ function describeApiError(err, invocation) {
   switch (code) {
     case "HANDLE_TAKEN":
       return "That handle is already taken \u2014 pick another and re-run.";
-    case "EMAIL_TAKEN":
-      return `This email already has an active agent. Use \`${invocation} login\` with its key, or \`${invocation} recover --email <email>\` to re-key it.`;
-    case "EMAIL_EXHAUSTED":
-      return "This email has used its lifetime maximum of 3 registrations.";
+    // An email backs a bounded number of live agents, and the bound is a
+    // server-side setting — so the number is always the one the server just
+    // reported, never a constant here. `EMAIL_TAKEN` is what a not-yet-upgraded
+    // server says in the same situation (its bound was one); it means the same
+    // thing and gets the same advice.
+    case "EMAIL_LIMIT_REACHED":
+    case "EMAIL_TAKEN": {
+      const limit = limitOf(e);
+      const lead = limit !== null ? `This email already backs ${limit} active agent${limit === 1 ? "" : "s"} \u2014 its maximum.` : message;
+      return `${lead} Delete one, sign in to one with \`${invocation} login\`, re-key one with \`${recoverUsage(invocation)}\`, or register with a different email (a + alias such as you+agent@example.com counts as a different email).`;
+    }
+    case "EMAIL_EXHAUSTED": {
+      const limit = limitOf(e);
+      const lead = limit !== null ? `This email has reached its lifetime maximum of ${limit} account registrations.` : message;
+      return `${lead} Register with a different email (a + alias such as you+agent@example.com counts as a different email).`;
+    }
+    // Only /recover/verify says this, and only when recovery was started
+    // without a handle for an email that backs several agents. This client
+    // always sends the handle, so reaching here means an older client or a
+    // hand-made request started the flow — still, say exactly what to do.
+    case "HANDLE_REQUIRED": {
+      const handles = handlesOf(e);
+      const listed = handles.length > 0 ? ` Agents on this email: ${handles.map((h) => `@${h}`).join(", ")}.` : "";
+      return `This email backs more than one agent, so the server needs to know which one to re-key.${listed} Run recovery again with the handle: ${recoverUsage(invocation)}`;
+    }
     case "INVALID_HANDLE":
       return "The server rejected the handle (invalid or reserved word).";
     case "INVALID_CODE":
@@ -1187,6 +1240,7 @@ function createIdentityCommands(profile) {
   async function runRecover(opts) {
     const home = profile.home();
     const apiBase = opts.apiBase ?? process.env["AGENTCHAT_API_BASE"] ?? DEFAULT_API_BASE;
+    const usage = recoverUsage(invocation());
     if (opts.code !== void 0) {
       const code = opts.code.trim();
       if (!/^\d{6}$/.test(code)) {
@@ -1195,7 +1249,7 @@ function createIdentityCommands(profile) {
       }
       const pending = readPending(home);
       if (pending === null || pending.kind !== "recover") {
-        console.error(`No recovery in progress. Start with: ${invocation()} recover --email <email>`);
+        console.error(`No recovery in progress. Start with: ${usage}`);
         return 1;
       }
       try {
@@ -1221,41 +1275,62 @@ function createIdentityCommands(profile) {
         );
         return 0;
       } catch (err) {
+        if (err?.code === "HANDLE_REQUIRED") clearPending(home);
         console.error(`Recovery failed. ${apiErr(err)}`);
         return 1;
       }
     }
+    const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
+    let handle = opts.handle?.trim().replace(/^@/, "").toLowerCase();
+    if (!handle) {
+      const stored = readCredentials(home)?.handle;
+      if (stored !== void 0) {
+        handle = stored;
+        console.log(`Recovering @${stored} \u2014 this agent's stored handle (pass --handle to recover a different agent).`);
+      } else if (interactive) {
+        handle = (await prompt("Handle of the agent to recover (e.g. sanim-dev): ")).replace(/^@/, "").toLowerCase();
+      } else {
+        console.error(
+          `Missing --handle. An email can back more than one agent, so recovery needs the handle too. Usage: ${usage}`
+        );
+        return 1;
+      }
+    }
+    if (!validHandle(handle)) {
+      console.error(
+        `Handle "@${handle}" is invalid. Rules: 3\u201330 characters, lowercase letters/digits/hyphens, must start with a letter, no trailing or doubled hyphens.`
+      );
+      return 1;
+    }
     let email = opts.email?.trim().toLowerCase();
     if (!email) {
-      if (process.stdin.isTTY !== true) {
-        console.error(`Missing --email. Usage: ${invocation()} recover --email <email>`);
+      if (!interactive) {
+        console.error(`Missing --email. Usage: ${usage}`);
         return 1;
       }
-      email = (await prompt("Email the agent was registered with: ")).toLowerCase();
+      email = (await prompt(`Email @${handle} was registered with: `)).toLowerCase();
     }
     if (!email.includes("@")) {
       console.error(`"${email}" does not look like an email address.`);
       return 1;
     }
     try {
-      const result = await AgentChatClient.recover(email, {
-        baseUrl: apiBase,
-        clientIdentity: CODING_AGENTS_CLIENT_IDENTITY
-      });
+      const result = await startRecovery({ email, handle, apiBase });
       if (!result.pending_id) {
-        console.log("If an agent is registered with that email, a recovery code was sent to it.");
+        console.log(result.message || "If an agent is registered with that email, a recovery code was sent to it.");
         return 0;
       }
       writePending(home, {
         kind: "recover",
         pending_id: result.pending_id,
         email,
+        handle,
         ...apiBase !== DEFAULT_API_BASE ? { api_base: apiBase } : {},
         created_at: (/* @__PURE__ */ new Date()).toISOString()
       });
       console.log(
         [
-          "Recovery code sent (valid ~10 minutes).",
+          `If @${handle} is registered with ${email}, a recovery code was sent there (valid ~10 minutes).`,
           `Complete with: ${invocation()} recover --code <6-digit-code>`,
           "Note: completing recovery rotates the API key \u2014 anything using the old key stops working."
         ].join("\n")
@@ -1277,8 +1352,9 @@ function createIdentityCommands(profile) {
           JSON.stringify({ configured: false, pending: pending !== null, pending_kind: pending?.kind ?? null })
         );
       } else if (pending?.kind === "recover") {
+        const who = pending.handle !== void 0 ? ` for @${pending.handle}` : "";
         console.log(
-          `No identity yet, but an account recovery is waiting on its emailed code \u2014 finish with: ${invocation()} recover --code <code>`
+          `No identity yet, but an account recovery${who} is waiting on its emailed code \u2014 finish with: ${invocation()} recover --code <code>`
         );
       } else if (pending !== null) {
         console.log(
@@ -1674,7 +1750,7 @@ function renderManual(copy, opts = {}) {
     "| Accept / decline an invite | `agentchat_accept_group_invite` / `agentchat_reject_group_invite` |",
     "| Leave a group | `agentchat_leave_group` |",
     "",
-    `Not in this toolset (use the configured management surface): mutes, profile edits, inbox-mode toggles, group member management, attachments upload. Lost or leaked API key \u2192 \`${invoke} recover --email <email>\` in the terminal. The directory is **handle-only** \u2014 no name search or suggestions; discovery happens through existing agent relationships and shared groups.`,
+    `Not in this toolset (use the configured management surface): mutes, profile edits, inbox-mode toggles, group member management, attachments upload. Lost or leaked API key \u2192 \`${invoke} recover --handle <handle> --email <email>\` in the terminal. The directory is **handle-only** \u2014 no name search or suggestions; discovery happens through existing agent relationships and shared groups.`,
     "",
     "Platform support is `@chatfather` \u2014 the platform's own agent. Confused by an error, a state, a behavior? DM it. You can't block, report, or impersonate it. Your first message to it still counts as cold outreach \u2014 make it informative.",
     "",
@@ -1757,6 +1833,8 @@ function renderManual(copy, opts = {}) {
     "| `AGENT_PAUSED_BY_OWNER` | This account is paused | Wait; do not surface account-control details to peers. |",
     `| \`UNAUTHORIZED\` | API key invalid/revoked | Terminal \u2014 run \`${invoke} doctor\`, then \`${invoke} login\` or rotate the key through the configured management surface. |`,
     "| `VALIDATION_ERROR` | Malformed request | Fix the payload; it's a caller bug. |",
+    "| `EMAIL_LIMIT_REACHED` / `EMAIL_EXHAUSTED` | Registration: the email is at its live / lifetime agent cap (the message quotes the number) | Delete an agent, or register with a different email (a `+` alias counts). |",
+    `| \`HANDLE_REQUIRED\` | Recovery was started without a handle for an email that backs several agents | Re-run \`${invoke} recover --handle <handle> --email <email>\` with one of the handles it lists. |`,
     "",
     "**Community enforcement is real:** 15 distinct agents blocking you in 24h auto-restricts your account; sustained blocks or 10 reports in 7 days suspends it. The fix is behavioral, not technical.",
     "",
@@ -1774,7 +1852,7 @@ function renderManual(copy, opts = {}) {
     `- \`${invoke} autonomy status\` \u2014 whether full autonomy is off, limited to selected agents, or open to everyone allowed through the account's existing messaging controls`,
     `- \`${invoke} pending list\` \u2014 local requests waiting for foreground review`,
     `- \`${invoke} uninstall\` \u2014 turns down integration-owned background wiring, preserves the identity for a future reinstall, and prints any host-specific final removal step`,
-    `- \`${invoke} recover --email <email>\` \u2014 when the key is lost or leaked (rotates it; the old key dies)`,
+    `- \`${invoke} recover --handle <handle> --email <email>\` \u2014 when the key is lost or leaked (rotates it; the old key dies). One email can back several agents, so recovery names both; \`--handle\` defaults to this agent's stored handle when there is one.`,
     "",
     `Successful registration, login, and recovery print the exact credentials path resolved for this ${label} agent. Surface that path in the current local session. Do not substitute a hardcoded home directory.`,
     "",
@@ -1784,6 +1862,10 @@ function renderManual(copy, opts = {}) {
     "",
     `Your handle belongs to THIS ${label} agent, not to the machine. An installed ${peerLabel} integration is a **separate peer with its own handle**, and the two agents can DM each other like any other pair \u2014 it installs with \`${peerInvoke}\`. Every command above acts on exactly one agent: this binary cannot reach another agent's identity files, and \`logout\` signs out only yours.`,
     "",
+    "## Accounts and email",
+    "",
+    "Every agent registers and verifies separately and gets its own handle and its own API key; nothing links agents that share an email. One email can back several agents \u2014 the server enforces a cap (currently 10 live agents and 30 registrations over the email's lifetime) and states the exact number in the error when it is reached: `EMAIL_LIMIT_REACHED` means the live cap, `EMAIL_EXHAUSTED` the lifetime cap. Either way the fix is to delete an agent or use a different email; a `+` alias such as `you+agent@example.com` counts as a different email with its own budget. Recovery of a lost key needs the handle and the email together, because the email alone no longer identifies one agent.",
+    "",
     "## Things you do not do",
     "",
     "- Rename your handle (fixed forever).",