fix(tinyplace): wire handle transfer end-to-end (Closes #4929)

app/src/agentworld/components/TransferHandleModal.test.tsx

@@ -0,0 +1,95 @@
+/**
+ * Tests for TransferHandleModal (GH-4929) — the confirm + execute dialog for a
+ * Tiny Place handle transfer. A transfer is destructive/irreversible, so these
+ * assert the wiring to `apiClient.registry.transfer`, that confirm is gated on a
+ * recipient, and that the flow fails CLOSED (error keeps the dialog open and
+ * never reports success).
+ *
+ * All handles/recipients are generic placeholders, never real identities.
+ */
+import { screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { renderWithProviders } from '../../test/test-utils';
+import { apiClient } from '../AgentWorldShell';
+import TransferHandleModal from './TransferHandleModal';
+
+vi.mock('../AgentWorldShell', () => ({ apiClient: { registry: { transfer: vi.fn() } } }));
+
+const transfer = vi.mocked(apiClient.registry.transfer);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+function setup() {
+  const onClose = vi.fn();
+  const onTransferred = vi.fn();
+  renderWithProviders(
+    <TransferHandleModal handle="alpha" onClose={onClose} onTransferred={onTransferred} />
+  );
+  return { onClose, onTransferred };
+}
+
+describe('TransferHandleModal', () => {
+  test('shows the handle + irreversible warning and gates confirm on a recipient', () => {
+    setup();
+    expect(screen.getByTestId('transfer-handle-modal')).toBeInTheDocument();
+    expect(screen.getByText('@alpha')).toBeInTheDocument();
+    expect(screen.getByText(/permanent and cannot be undone/i)).toBeInTheDocument();
+    // Confirm is disabled until a recipient is entered.
+    expect(screen.getByTestId('transfer-handle-confirm')).toBeDisabled();
+  });
+
+  test('keeps confirm disabled until the exact handle is re-typed', async () => {
+    const user = userEvent.setup();
+    setup();
+    const confirmBtn = screen.getByTestId('transfer-handle-confirm');
+    // A recipient alone is not enough for a destructive action.
+    await user.type(screen.getByPlaceholderText(/Recipient @handle/i), 'bravo');
+    expect(confirmBtn).toBeDisabled();
+    // A wrong handle keeps it disabled.
+    await user.type(screen.getByTestId('transfer-handle-confirm-input'), 'wrong');
+    expect(confirmBtn).toBeDisabled();
+    // The exact handle (case- and @-insensitive) enables it.
+    await user.clear(screen.getByTestId('transfer-handle-confirm-input'));
+    await user.type(screen.getByTestId('transfer-handle-confirm-input'), '@ALPHA');
+    expect(confirmBtn).toBeEnabled();
+  });
+
+  test('confirming transfers to the resolved recipient, then closes on success', async () => {
+    const user = userEvent.setup();
+    transfer.mockResolvedValueOnce({ identity: { username: 'alpha' } as never });
+    const { onClose, onTransferred } = setup();
+
+    await user.type(screen.getByPlaceholderText(/Recipient @handle/i), '@bravo');
+    // The irreversible action is gated behind re-typing the handle.
+    await user.type(screen.getByTestId('transfer-handle-confirm-input'), '@alpha');
+    await user.click(screen.getByTestId('transfer-handle-confirm'));
+
+    // Leading @ is stripped before the RPC; handle passed through verbatim.
+    await waitFor(() => expect(transfer).toHaveBeenCalledWith('alpha', 'bravo'));
+    await waitFor(() => expect(onTransferred).toHaveBeenCalledTimes(1));
+    expect(onClose).toHaveBeenCalledTimes(1);
+    expect(screen.queryByTestId('transfer-handle-error')).not.toBeInTheDocument();
+  });
+
+  test('fails closed: on error it shows the message and does not report success', async () => {
+    const user = userEvent.setup();
+    transfer.mockRejectedValueOnce(new Error('recipient handle is not registered on tiny.place'));
+    const { onClose, onTransferred } = setup();
+
+    await user.type(screen.getByPlaceholderText(/Recipient @handle/i), 'bravo');
+    await user.type(screen.getByTestId('transfer-handle-confirm-input'), 'alpha');
+    await user.click(screen.getByTestId('transfer-handle-confirm'));
+
+    await waitFor(() =>
+      expect(screen.getByTestId('transfer-handle-error')).toHaveTextContent(/not registered/i)
+    );
+    // Fail closed: no success callbacks, dialog stays open.
+    expect(onTransferred).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+    expect(screen.getByTestId('transfer-handle-modal')).toBeInTheDocument();
+  });
+});

app/src/agentworld/components/TransferHandleModal.tsx

@@ -0,0 +1,155 @@
+/**
+ * TransferHandleModal — confirm + execute a Tiny Place handle transfer (GH-4929).
+ *
+ * A handle transfer is DESTRUCTIVE and irreversible for the sender: on success
+ * the recipient becomes the handle's sole owner. So this modal states that
+ * plainly, requires an explicit recipient, requires the user to re-type the
+ * handle to confirm intent, and takes an explicit confirm click — and it fails
+ * **closed**: on any error it keeps the dialog open with the message and never
+ * reports success. The core handler resolves the recipient @handle and
+ * read-back-confirms the new owner before this promise resolves, so a resolved
+ * transfer means the reassignment actually landed.
+ */
+import debugFactory from 'debug';
+import { useCallback, useState } from 'react';
+
+import Button from '../../components/ui/Button';
+import { ModalShell } from '../../components/ui/ModalShell';
+import { useT } from '../../lib/i18n/I18nContext';
+import { apiClient } from '../AgentWorldShell';
+
+// Namespaced already ('agentworld:identity'), so messages carry no prefix.
+const debug = debugFactory('agentworld:identity');
+
+export interface TransferHandleModalProps {
+  /** The handle being transferred away (without a leading @). */
+  handle: string;
+  onClose: () => void;
+  /** Called after a confirmed, read-back-verified transfer. */
+  onTransferred: () => void;
+}
+
+/** Normalize a handle for comparison: strip leading @, trim, lowercase. */
+function normalizeHandle(value: string): string {
+  return value.trim().replace(/^@+/, '').toLowerCase();
+}
+
+export default function TransferHandleModal({
+  handle,
+  onClose,
+  onTransferred,
+}: TransferHandleModalProps) {
+  const { t } = useT();
+  const [recipient, setRecipient] = useState('');
+  const [confirmText, setConfirmText] = useState('');
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleClean = handle.replace(/^@+/, '');
+  // Guard the irreversible action: the user must re-type the exact handle.
+  const confirmMatches = normalizeHandle(confirmText) === normalizeHandle(handleClean);
+
+  const submit = useCallback(async () => {
+    const target = recipient.trim().replace(/^@+/, '');
+    if (!target) {
+      setError(t('agentWorld.transferHandle.recipientRequired'));
+      return;
+    }
+    // Belt-and-suspenders: the button is disabled without a match, but never
+    // execute a destructive transfer unless the typed confirmation matches.
+    if (!confirmMatches) {
+      setError(t('agentWorld.transferHandle.confirmMismatch'));
+      return;
+    }
+    setSubmitting(true);
+    setError(null);
+    // Never log the handle or recipient — both identify a user.
+    debug('handle transfer requested');
+    try {
+      // Send the normalized handle (not the raw prop) so the invariant is local
+      // and doesn't rest on every caller pre-cleaning the value (#4998 review).
+      await apiClient.registry.transfer(handleClean, target);
+      debug('handle transfer confirmed');
+      onTransferred();
+      onClose();
+    } catch (err) {
+      // Fail closed: keep the dialog open, show why, report no success.
+      // Log only the status (no raw error — it can carry backend/SDK detail);
+      // the raw message still surfaces in the UI via setError.
+      debug('handle transfer failed');
+      setError(String(err));
+      setSubmitting(false);
+    }
+  }, [recipient, confirmMatches, handleClean, t, onTransferred, onClose]);
+
+  return (
+    <ModalShell
+      title={t('agentWorld.transferHandle.title')}
+      titleId="agentworld-transfer-handle-title"
+      maxWidthClassName="max-w-sm"
+      onClose={submitting ? () => undefined : onClose}>
+      <div className="space-y-4" data-testid="transfer-handle-modal">
+        <p className="text-sm text-content">@{handleClean}</p>
+        <p className="text-xs text-red-600 dark:text-red-400">
+          {t('agentWorld.transferHandle.warning')}
+        </p>
+
+        <input
+          type="text"
+          value={recipient}
+          onChange={e => {
+            setRecipient(e.target.value);
+            setError(null);
+          }}
+          disabled={submitting}
+          placeholder={t('agentWorld.transferHandle.recipientPlaceholder')}
+          aria-label={t('agentWorld.transferHandle.recipientPlaceholder')}
+          className="w-full rounded-md border border-line-strong bg-surface px-3 py-2 text-sm text-content placeholder-content-faint outline-none focus:border-primary-500"
+        />
+
+        {/* Type-to-confirm guard for the irreversible action. */}
+        <div className="space-y-1">
+          <p className="text-xs text-content-muted">
+            {t('agentWorld.transferHandle.confirmLabel')}
+          </p>
+          <input
+            type="text"
+            value={confirmText}
+            onChange={e => {
+              setConfirmText(e.target.value);
+              setError(null);
+            }}
+            disabled={submitting}
+            placeholder={`@${handleClean}`}
+            aria-label={t('agentWorld.transferHandle.confirmLabel')}
+            data-testid="transfer-handle-confirm-input"
+            className="w-full rounded-md border border-line-strong bg-surface px-3 py-2 text-sm text-content placeholder-content-faint outline-none focus:border-primary-500"
+          />
+        </div>
+
+        {error && (
+          <p className="text-xs text-red-600 dark:text-red-400" data-testid="transfer-handle-error">
+            {error}
+          </p>
+        )}
+
+        <div className="flex justify-end gap-2">
+          <Button variant="secondary" size="sm" onClick={onClose} disabled={submitting}>
+            {t('common.cancel')}
+          </Button>
+          <Button
+            variant="primary"
+            size="sm"
+            tone="danger"
+            onClick={() => void submit()}
+            disabled={submitting || !recipient.trim() || !confirmMatches}
+            data-testid="transfer-handle-confirm">
+            {submitting
+              ? t('agentWorld.transferHandle.submitting')
+              : t('agentWorld.transferHandle.confirm')}
+          </Button>
+        </div>
+      </div>
+    </ModalShell>
+  );
+}

app/src/agentworld/pages/ProfilesSection.test.tsx

@@ -19,7 +19,7 @@ vi.mock('../AgentWorldShell', () => ({
   apiClient: {
     directory: { reverse: vi.fn() },
     follows: { stats: vi.fn() },
-    registry: { export: vi.fn(), assignPrimary: vi.fn() },
+    registry: { export: vi.fn(), assignPrimary: vi.fn(), transfer: vi.fn() },
     graphql: { user: vi.fn() },
     users: { get: vi.fn(), updateProfile: vi.fn() },
   },
@@ -362,6 +362,74 @@ function makeProfile(overrides: Partial<GqlProfile> = {}): GqlProfile {
   };
 }
 
+// GH-4929: a non-primary owned handle offers an enabled Transfer action that
+// opens the destructive-confirm modal. #4998 M3: a primary (active) handle now
+// renders a DISABLED Transfer control with an explanation (make another handle
+// active first) instead of silently omitting it. A handle with no explicit
+// primary flag (unknown state) shows no Transfer control at all.
+describe('handle transfer action', () => {
+  test('opens the transfer confirm modal for a non-primary owned handle', async () => {
+    graphqlUser.mockResolvedValueOnce(
+      makeProfile({
+        displayName: 'Owner',
+        identities: [
+          { ...minimalIdentity, username: 'primaryhandle', cryptoId: SOLANA_ADDR, primary: true },
+          { ...minimalIdentity, username: 'giftme', cryptoId: SOLANA_ADDR, primary: false },
+        ],
+      })
+    );
+    render(<ProfilesSection />);
+
+    // Both handles render a Transfer control (#4998 M3): the non-primary one is
+    // enabled, the primary one disabled. Pick the enabled one — it opens the modal.
+    const transferButtons = await screen.findAllByRole('button', { name: 'Transfer' });
+    const enabled = transferButtons.find(b => !(b as HTMLButtonElement).disabled);
+    expect(enabled, 'the non-primary handle must expose an enabled Transfer control').toBeDefined();
+    fireEvent.click(enabled!);
+
+    // The destructive-confirm modal opens with its explicit confirm control.
+    expect(await screen.findByTestId('transfer-handle-modal')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Transfer handle' })).toBeInTheDocument();
+  });
+
+  test('shows a disabled Transfer control with an explanation for a primary handle (#4998 M3)', async () => {
+    graphqlUser.mockResolvedValueOnce(
+      makeProfile({
+        displayName: 'Owner',
+        identities: [
+          { ...minimalIdentity, username: 'onlyprimary', cryptoId: SOLANA_ADDR, primary: true },
+        ],
+      })
+    );
+    render(<ProfilesSection />);
+
+    // Rendered, but disabled and explained — not an invisible dead end.
+    const transferButton = await screen.findByRole('button', { name: 'Transfer' });
+    expect(transferButton).toBeDisabled();
+    expect(transferButton).toHaveAttribute(
+      'title',
+      'A primary handle cannot be transferred. Make another handle active first.'
+    );
+
+    // Clicking the locked control must NOT open the destructive modal.
+    fireEvent.click(transferButton);
+    expect(screen.queryByTestId('transfer-handle-modal')).not.toBeInTheDocument();
+  });
+
+  test('shows no Transfer control when the primary flag is absent (unknown state)', async () => {
+    graphqlUser.mockResolvedValueOnce(
+      makeProfile({
+        displayName: 'Owner',
+        identities: [{ ...minimalIdentity, username: 'unknownstate', cryptoId: SOLANA_ADDR }],
+      })
+    );
+    render(<ProfilesSection />);
+
+    expect(await screen.findByRole('button', { name: 'Make active' })).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Transfer' })).not.toBeInTheDocument();
+  });
+});
+
 describe('graphql-enriched profile card', () => {
   test('renders rich profile from graphql.user when available', async () => {
     graphqlUser.mockResolvedValueOnce(

app/src/agentworld/pages/ProfilesSection.tsx

@@ -22,6 +22,7 @@ import {
 import { useT } from '../../lib/i18n/I18nContext';
 import { fetchWalletStatus } from '../../services/walletApi';
 import { apiClient } from '../AgentWorldShell';
+import TransferHandleModal from '../components/TransferHandleModal';
 
 const log = debug('agentworld:profile');
 
@@ -348,6 +349,8 @@ function AgentProfileCard({ data, onSwitched }: { data: ProfileData; onSwitched?
   // Handle currently being promoted to primary (in-flight), and any error.
   const [switchingHandle, setSwitchingHandle] = useState<string | null>(null);
   const [switchError, setSwitchError] = useState<string | null>(null);
+  // The owned handle whose transfer modal is open (without @), or null.
+  const [transferHandle, setTransferHandle] = useState<string | null>(null);
 
   // ── Extract display fields from either data source ─────────────────────────
   const isGraphql = data.source === 'graphql';
@@ -568,6 +571,29 @@ function AgentProfileCard({ data, onSwitched }: { data: ProfileData; onSwitched?
                         : 'Make active'}
                     </Button>
                   )}
+                  {/* Transfer is destructive/irreversible — the modal confirms
+                      intent and fails closed. A primary (active) handle is
+                      locked from sale/transfer server-side, so it renders
+                      disabled with an explanation of the path out (make another
+                      handle active first) rather than silently vanishing (#4998
+                      M3). Only an explicit non-primary handle is transferable. */}
+                  {id.primary === false && (
+                    <Button
+                      variant="secondary"
+                      size="sm"
+                      onClick={() => setTransferHandle(id.username.replace(/^@+/, ''))}>
+                      {t('agentWorld.transferHandle.action')}
+                    </Button>
+                  )}
+                  {id.primary === true && (
+                    <Button
+                      variant="secondary"
+                      size="sm"
+                      disabled
+                      title={t('agentWorld.transferHandle.primaryLocked')}>
+                      {t('agentWorld.transferHandle.action')}
+                    </Button>
+                  )}
                   <span className="text-[10px] uppercase tracking-wide text-content-faint">
                     {id.status}
                   </span>
@@ -581,6 +607,14 @@ function AgentProfileCard({ data, onSwitched }: { data: ProfileData; onSwitched?
         </div>
       )}
 
+      {transferHandle && (
+        <TransferHandleModal
+          handle={transferHandle}
+          onClose={() => setTransferHandle(null)}
+          onTransferred={() => onSwitched?.()}
+        />
+      )}
+
       {followStats && (
         <div className="mt-4 border-t border-line pt-4">
           <div className="flex gap-6">