ethagent 3.3.4 → 4.0.0

package/src/identity/manager/shared/components/MenuScreen.tsx

@@ -0,0 +1,220 @@
+import React from 'react'
+import { Box, Text } from 'ink'
+import { theme } from '../../../../ui/theme.js'
+import { isDemoMode } from '../../../../cli/demo.js'
+import type { EthagentConfig, EthagentIdentity } from '../../../../storage/config.js'
+import { identityPerspective } from '../../custody/state.js'
+import { transferSnapshotView } from '../../transfer/state.js'
+import type { AgentReconciliation } from '../reconciliation/index.js'
+import { menuFlagsFromReconciliation } from './menuFlagsFromReconciliation.js'
+import { localChangeStatusView } from '../../continuity/state.js'
+import { LazyMenu, type LazyMenuRow } from './LazyMenu.js'
+
+import type { ContinuityWorkingTreeStatus } from '../../../continuity/storage.js'
+
+type MenuScreenProps = {
+  config?: EthagentConfig
+  identity?: EthagentIdentity
+  canRebackup: boolean
+  reconciliation?: AgentReconciliation
+  workingStatus?: ContinuityWorkingTreeStatus | null
+  onCreate: () => void
+  onLoad: () => void
+  onBackupNow: () => void
+  onRefetchLatest: () => void
+  onPublicProfile: () => void
+  onEnsName: () => void
+  onWalletSetup: () => void
+  onContinuity: () => void
+  onSkillsTree: () => void
+  onIdentityValues: () => void
+  onPrepareTransfer: () => void
+  onStorage: () => void
+  onCancel: () => void
+}
+
+type Action =
+  | 'public-profile'
+  | 'ens-name'
+  | 'wallet-setup'
+  | 'continuity'
+  | 'skills-tree'
+  | 'backup'
+  | 'refetch'
+  | 'identity-values'
+  | 'prepare-transfer'
+  | 'storage'
+  | 'create'
+  | 'load'
+  | 'cancel'
+
+function shortAddress(addr: string | undefined): string {
+  if (!addr) return ''
+  return addr.slice(0, 6) + '…' + addr.slice(-4)
+}
+
+function networkLabel(config?: EthagentConfig, identity?: EthagentIdentity): string | null {
+  const chainId = identity?.chainId ?? config?.erc8004?.chainId
+  if (chainId === 1) return 'mainnet'
+  if (chainId === 8453) return 'base'
+  return config?.selectedNetwork ?? null
+}
+
+export const MenuScreen: React.FC<MenuScreenProps> = ({
+  config,
+  identity,
+  reconciliation,
+  workingStatus,
+  canRebackup,
+  onCreate,
+  onLoad,
+  onBackupNow,
+  onRefetchLatest,
+  onPublicProfile,
+  onEnsName,
+  onWalletSetup,
+  onContinuity,
+  onSkillsTree,
+  onIdentityValues,
+  onPrepareTransfer,
+  onStorage,
+  onCancel,
+}) => {
+  const canRefetch = Boolean(canRebackup && identity?.backup?.cid)
+
+  const perspective = identityPerspective(identity)
+  const flags = reconciliation
+    ? menuFlagsFromReconciliation(reconciliation, perspective)
+    : (perspective === 'operator'
+      ? menuFlagsFromReconciliation({
+          token: 'unknown', custody: 'unknown', agentUri: 'unknown',
+          vault: 'unknown', workingTree: 'unknown', rpc: 'reachable', driftCount: 0, lastCheckedAt: '',
+        }, perspective)
+      : null)
+
+  const backupEnabled = canRebackup && !(flags?.saveSnapshotDisabled ?? false)
+  const localChangeStatus = localChangeStatusView(workingStatus)
+
+  const rows: Array<LazyMenuRow<Action>> = identity
+    ? [
+        { value: 'public-profile', label: 'Public Profile', shortcut: 'p' },
+        { value: 'continuity',     label: 'Soul & Memory',  shortcut: 'm' },
+        { value: 'skills-tree',    label: 'Skills',         shortcut: 's' },
+        { value: 'backup',         label: 'Save Snapshot',  shortcut: 'a', disabled: !canRebackup || (flags?.saveSnapshotDisabled ?? false), hint: flags?.saveSnapshotHint, ...(localChangeStatus.hasLocalChanges && backupEnabled ? { inlineNote: localChangeStatus.files.length > 0 ? localChangeStatus.files.join(', ') : 'unsaved changes', inlineNoteColor: theme.accentError } : {}) },
+        { value: 'refetch',        label: 'Refetch Latest', shortcut: 'r', disabled: !canRefetch || (flags?.refetchLatestDisabled ?? false), hint: flags?.refetchHint },
+        { value: 'ens-name',       label: 'ENS Name',       shortcut: 'e', disabled: flags?.ensNameDisabled ?? false, hint: flags?.ensNameHint },
+        { value: 'identity-values', label: 'Token Values',  shortcut: 'v', ...(flags?.tokenValuesUnlinkedNote ? { note: flags.tokenValuesUnlinkedNote } : {}) },
+        { value: 'wallet-setup',   label: 'Custody Mode',   shortcut: 'c', disabled: !identity.agentId || (flags?.custodyModeDisabled ?? false), hint: flags?.custodyModeHint ?? flags?.custodyHint },
+        ...(flags?.prepareTransferHidden ? [] : [{ value: 'prepare-transfer' as Action, label: 'Prepare Transfer', shortcut: 't', disabled: flags?.prepareTransferDisabled ?? false, hint: flags?.prepareTransferHint }]),
+        { value: 'load',           label: 'Switch Agent',   shortcut: 'w' },
+        { value: 'create',         label: 'New Agent',      shortcut: 'n' },
+        { value: 'storage',        label: 'IPFS Storage',   shortcut: 'i' },
+        { value: 'cancel',         label: 'Quit',           shortcut: 'q' },
+      ]
+    : [
+        { value: 'create', label: 'Create New Agent' },
+        { value: 'load',   label: 'Load Existing' },
+      ]
+
+  const reconciliationBanner = identity && reconciliation
+    ? renderReconciliationBanner(reconciliation, identity)
+    : null
+
+  const network = networkLabel(config, identity)
+  const statusBits: string[] = []
+  if (identity?.agentId) statusBits.push(`#${identity.agentId}`)
+  const displayAddress = perspective === 'operator' ? identity?.connectedWallet : identity?.ownerAddress
+  if (displayAddress) statusBits.push(shortAddress(displayAddress))
+  if (network) statusBits.push(network)
+  if (perspective === 'operator') statusBits.push('operator')
+
+  return (
+    <Box flexDirection="column" alignItems="center" paddingY={1}>
+      <Box flexDirection="column" alignItems="center">
+        {reconciliationBanner ? (
+          <Box marginBottom={1} flexDirection="column" alignItems="center">
+            {reconciliationBanner}
+          </Box>
+        ) : null}
+        {!identity ? (
+          <Box marginBottom={1}>
+            <Text color={theme.textSubtle}>Create or link an agent identity to get started.</Text>
+          </Box>
+        ) : null}
+        <LazyMenu<Action>
+          rows={rows}
+          onSubmit={choice => {
+            if (choice === 'cancel') return onCancel()
+            if (choice === 'public-profile') return onPublicProfile()
+            if (choice === 'ens-name') return onEnsName()
+            if (choice === 'wallet-setup') return onWalletSetup()
+            if (choice === 'continuity') return onContinuity()
+            if (choice === 'skills-tree') return onSkillsTree()
+            if (choice === 'backup') return onBackupNow()
+            if (choice === 'refetch') return onRefetchLatest()
+            if (choice === 'identity-values') return onIdentityValues()
+            if (choice === 'prepare-transfer') return onPrepareTransfer()
+            if (choice === 'storage') return onStorage()
+            if (choice === 'load') return onLoad()
+            if (choice === 'create') return onCreate()
+          }}
+          onCancel={onCancel}
+        />
+        {!identity ? (
+          <Box marginTop={1}>
+            <Text color={theme.dim}>esc to quit</Text>
+          </Box>
+        ) : null}
+      </Box>
+      {statusBits.length > 0 ? (
+        <Box marginTop={2}>
+          {isDemoMode() ? (
+            <Text>
+              <Text color={theme.accentHighlight}>demo </Text>
+              <Text color={theme.menuStatus}>· {statusBits.join(' · ')}</Text>
+            </Text>
+          ) : (
+            <Text color={theme.menuStatus}>{statusBits.join(' · ')}</Text>
+          )}
+        </Box>
+      ) : null}
+    </Box>
+  )
+}
+
+function renderReconciliationBanner(r: AgentReconciliation, identity: EthagentIdentity): React.ReactNode {
+  if (r.token === 'no-agent') return null
+  if (r.token === 'unlinked') {
+    const tokenLabel = r.tokenAgentId ? `Token #${r.tokenAgentId}` : 'Token'
+    const transferSnapshot = transferSnapshotView(identity)
+    if (transferSnapshot) {
+      return (
+        <>
+          <Text color={theme.accentError} bold>Agent Unlinked</Text>
+          <Text color={theme.textSubtle}>{tokenLabel} was transferred. Local SOUL.md, MEMORY.md, and skills remain.</Text>
+        </>
+      )
+    }
+    return (
+      <>
+        <Text color={theme.accentError} bold>Agent Unlinked</Text>
+        <Text color={theme.textSubtle}>{tokenLabel} left without Prepare Transfer.</Text>
+      </>
+    )
+  }
+  if (r.token === 'unknown') {
+    return <Text color={theme.dim}>Ownership check failed (RPC?)</Text>
+  }
+  const lines: string[] = []
+  if (r.custody === 'mid-flow-uri-pending') lines.push('Advanced setup pending')
+  if (r.custody !== 'mid-flow-uri-pending' && r.agentUri === 'local-newer') lines.push('Local newer than onchain')
+  if (r.custody !== 'mid-flow-uri-pending' && r.agentUri === 'chain-newer') lines.push('Onchain newer than local')
+  if (r.vault === 'missing') lines.push('Vault contract missing')
+  if (lines.length === 0) return null
+  return (
+    <>
+      <Text color={theme.accentPeriwinkle} bold>{lines.length} item{lines.length === 1 ? '' : 's'} need attention</Text>
+      {lines.map((line, i) => <Text key={i} color={theme.textSubtle}>· {line}</Text>)}
+    </>
+  )
+}

package/src/identity/manager/shared/components/OperationCompleteScreen.tsx

@@ -0,0 +1,28 @@
+import React from 'react'
+import { Box, Text } from 'ink'
+import { Surface } from '../../../../ui/Surface.js'
+import { Select } from '../../../../ui/Select.js'
+import { theme } from '../../../../ui/theme.js'
+
+type OperationCompleteScreenProps = {
+  message: string
+  onReturn: () => void
+}
+
+export const OperationCompleteScreen: React.FC<OperationCompleteScreenProps> = ({ message, onReturn }) => (
+  <Surface
+    title="Done"
+    footer={<Text color={theme.dim}>enter returns to menu</Text>}
+  >
+    <Box flexDirection="column">
+      <Text color={theme.text}>{message}</Text>
+      <Box marginTop={1}>
+        <Select<'menu'>
+          options={[{ value: 'menu', label: 'Return to Menu' }]}
+          onSubmit={onReturn}
+          onCancel={onReturn}
+        />
+      </Box>
+    </Box>
+  </Surface>
+)

package/src/identity/{hub → manager}/shared/components/UnlinkedIdentityScreen.tsx

@@ -27,13 +27,13 @@ export const UnlinkedIdentityScreen: React.FC<UnlinkedIdentityScreenProps> = ({
 }) => {
   const options: Array<{ value: Action; label: string; hint?: string; role?: 'section' | 'utility' }> = [
     { value: 'load-agent', role: 'section', label: 'Switch Agent' },
-    { value: 'load-agent', label: 'Switch Agent', hint: 'Reconnect this token by signing with the current owner wallet, or switch to a different one' },
-    { value: 'open-menu', role: 'section', label: 'Identity Hub' },
-    { value: 'open-menu', label: 'Open Identity Hub', hint: 'Browse local identity, continuity files, and settings without reconnecting' },
+    { value: 'load-agent', label: 'Switch Agent', hint: 'Reconnect or switch wallet' },
+    { value: 'open-menu', role: 'section', label: 'Identity' },
+    { value: 'open-menu', label: 'Open Identity', hint: 'Browse without reconnecting' },
   ]
   if (onRetry) {
     options.push({ value: 'retry', role: 'section', label: 'Recheck' })
-    options.push({ value: 'retry', label: 'Retry Ownership Check', hint: 'Re-query onchain to confirm the current owner', role: 'utility' })
+    options.push({ value: 'retry', label: 'Retry Ownership Check', hint: 'Recheck owner onchain', role: 'utility' })
   }
 
   const tokenLabel = agentId ? `Token #${agentId}` : 'Token'
@@ -47,15 +47,14 @@ export const UnlinkedIdentityScreen: React.FC<UnlinkedIdentityScreenProps> = ({
     >
       <Box flexDirection="column">
         {transferSnapshot ? (
-          <Text color={theme.textSubtle}>
-            {tokenLabel} was transferred. Local SOUL.md, MEMORY.md, and skills remain. Back them up before this directory is reused.
-          </Text>
+          <>
+            <Text color={theme.textSubtle}>{tokenLabel} was transferred.</Text>
+            <Text color={theme.textSubtle}>Local files remain. Back them up before reuse.</Text>
+          </>
         ) : (
           <>
             <Text color={theme.accentPeriwinkle}>{tokenLabel} left this wallet without Prepare Transfer, so the new holder has no continuity handoff.</Text>
-            <Text color={theme.textSubtle}>
-              Local SOUL.md, MEMORY.md, and skills remain. Back them up before this directory is reused.
-            </Text>
+            <Text color={theme.textSubtle}>Local files remain. Back them up before reuse.</Text>
           </>
         )}
       </Box>

package/src/identity/{hub → manager}/shared/components/WalletApprovalScreen.tsx

@@ -16,7 +16,6 @@ type WalletApprovalScreenProps = {
 }
 
 export const OPEN_BROWSER_HINT = 'Press enter to open in browser...'
-const PREPARING_WALLET_REQUEST_LABEL = 'preparing wallet request...'
 
 export const WalletApprovalScreen: React.FC<WalletApprovalScreenProps> = ({ title, subtitle, walletSession, label, onCancel }) => {
   useAppInput((_input, key) => {
@@ -37,7 +36,7 @@ export const WalletApprovalScreen: React.FC<WalletApprovalScreenProps> = ({ titl
           </Box>
         </Box>
       ) : (
-        <Spinner label={PREPARING_WALLET_REQUEST_LABEL} />
+        <Spinner label={label} />
       )}
     </Surface>
   )

package/src/identity/manager/shared/components/Wordmark.tsx

@@ -0,0 +1,54 @@
+import React from 'react'
+import { Box, Text } from 'ink'
+import { theme, gradientColor } from '../../../../ui/theme.js'
+
+export const LINES = [
+  '░░░░░░░╗░░░░░░░░╗░░╗  ░░╗ █████╗  ██████╗ ███████╗███╗   ██╗████████╗',
+  '░░╔════╝╚══░░╔══╝░░║  ░░║██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝',
+  '░░░░░╗     ░░║   ░░░░░░░║███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ',
+  '░░╔══╝     ░░║   ░░╔══░░║██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ',
+  '░░░░░░░╗   ░░║   ░░║  ░░║██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ',
+  '╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ',
+]
+
+export const SPLIT = 25
+
+export const LEFT_DECOR = [
+  '         ✦  ',
+  '   ⊹        ',
+  '            ',
+  '         .  ',
+  '            ',
+  ' ฅ^•ﻌ•マ    ',
+]
+
+export const RIGHT_DECOR = [
+  '  ˖    𐰁    ',
+  '            ',
+  '     𝗓      ',
+  '          ⊹ ',
+  '   ᶻ        ',
+  '            ',
+]
+
+export const Wordmark: React.FC = () => (
+  <Box flexDirection="row">
+    <Text color={theme.wordmarkEth}>{LEFT_DECOR.join('\n')}</Text>
+    <Box flexDirection="column">
+      {LINES.map((line, i) => {
+        const eth = line.slice(0, SPLIT)
+        const agent = line.slice(SPLIT)
+        const maxAgent = Math.max(1, agent.length - 1)
+        return (
+          <Text key={i}>
+            <Text color={theme.wordmarkEth}>{eth}</Text>
+            {[...agent].map((ch, j) => (
+              <Text key={j} color={gradientColor(j / maxAgent)}>{ch}</Text>
+            ))}
+          </Text>
+        )
+      })}
+    </Box>
+    <Text color={theme.wordmarkEth}>{RIGHT_DECOR.join('\n')}</Text>
+  </Box>
+)

package/src/identity/{hub → manager}/shared/components/menuFlagsFromReconciliation.ts

@@ -3,19 +3,22 @@ import type { IdentityPerspective } from '../../custody/state.js'
 
 type MenuFlags = {
   prepareTransferDisabled: boolean
-  prepareTransferReason?: string
+  prepareTransferHint?: string
+  prepareTransferHidden: boolean
   custodyModeDisabled: boolean
-  custodyModeReason?: string
+  custodyModeHint?: string
   ensNameDisabled: boolean
-  ensNameReason?: string
+  ensNameHint?: string
   saveSnapshotDisabled: boolean
   refetchLatestDisabled: boolean
+  refetchHint?: string
   tokenValuesUnlinkedNote?: string
 
   custodyAsterisk: boolean
   custodyHint?: string
   saveSnapshotAsterisk: boolean
   saveSnapshotHint?: string
+  workingTreeDirty: boolean
 }
 
 export function menuFlagsFromReconciliation(r: AgentReconciliation, perspective: IdentityPerspective = 'unknown'): MenuFlags {
@@ -23,11 +26,21 @@ export function menuFlagsFromReconciliation(r: AgentReconciliation, perspective:
   const inVault = r.custody === 'advanced' || r.custody === 'mid-flow-uri-pending'
   const isOperator = perspective === 'operator'
 
-  let prepareTransferReason: string | undefined
-  if (isOperator) {
-    prepareTransferReason = 'Owner-only action'
-  } else if (!unlinked && (r.custody === 'advanced' || r.custody === 'mid-flow-uri-pending')) {
-    prepareTransferReason = 'Withdraw from vault first'
+  let prepareTransferHint: string | undefined
+  if (unlinked) {
+    prepareTransferHint = 'Token unlinked'
+  } else if (inVault) {
+    prepareTransferHint = 'Token is in the Vault'
+  }
+
+  let custodyModeHint: string | undefined
+  if (unlinked) {
+    custodyModeHint = 'Token unlinked'
+  }
+
+  let ensNameHint: string | undefined
+  if (unlinked) {
+    ensNameHint = 'Token unlinked'
   }
 
   const custodyAsterisk = r.custody === 'mid-flow-uri-pending' || r.vault === 'missing'
@@ -40,23 +53,34 @@ export function menuFlagsFromReconciliation(r: AgentReconciliation, perspective:
     custodyHint = 'Vault missing, open to redeploy'
   }
 
-  const custodyModeReason = isOperator ? 'Owner-only action' : undefined
-  const ensNameReason = isOperator ? 'Owner-only action' : undefined
+  const agentUriLocalNewer = r.agentUri === 'local-newer' && r.custody !== 'mid-flow-uri-pending'
+
+  let saveSnapshotHint: string | undefined
+  if (unlinked) {
+    saveSnapshotHint = 'Token unlinked'
+  } else if (agentUriLocalNewer) {
+    saveSnapshotHint = 'Local newer than onchain'
+  }
+
+  const refetchHint: string | undefined = unlinked ? 'Token unlinked' : undefined
 
   return {
     prepareTransferDisabled: unlinked || inVault || isOperator,
-    ...(prepareTransferReason ? { prepareTransferReason } : {}),
+    ...(prepareTransferHint ? { prepareTransferHint } : {}),
+    prepareTransferHidden: inVault,
     custodyModeDisabled: unlinked || isOperator,
-    ...(custodyModeReason ? { custodyModeReason } : {}),
+    ...(custodyModeHint ? { custodyModeHint } : {}),
     ensNameDisabled: unlinked || isOperator,
-    ...(ensNameReason ? { ensNameReason } : {}),
+    ...(ensNameHint ? { ensNameHint } : {}),
     saveSnapshotDisabled: unlinked,
     refetchLatestDisabled: unlinked,
+    ...(refetchHint ? { refetchHint } : {}),
     ...(unlinked ? { tokenValuesUnlinkedNote: 'Unlinked, retained for reference' } : {}),
 
     custodyAsterisk: custodyAsterisk && !isOperator,
     ...(custodyHint ? { custodyHint } : {}),
-    saveSnapshotAsterisk: r.agentUri === 'local-newer',
-    ...(r.agentUri === 'local-newer' ? { saveSnapshotHint: 'Local newer than onchain' } : {}),
+    saveSnapshotAsterisk: agentUriLocalNewer || r.workingTree === 'dirty',
+    ...(saveSnapshotHint ? { saveSnapshotHint } : {}),
+    workingTreeDirty: r.workingTree === 'dirty',
   }
 }

package/src/identity/{hub → manager}/shared/effects/profilePrep.ts

@@ -3,7 +3,7 @@ import os from 'node:os'
 import path from 'node:path'
 import { getAddress, type Address } from 'viem'
 import type { EthagentIdentity } from '../../../../storage/config.js'
-import type { ProfileUpdates } from '../../identityHubReducer.js'
+import type { ProfileUpdates } from '../../reducer.js'
 import type { Erc8004RegistryConfig } from '../../../registry/erc8004.js'
 import { addFileToIpfs, DEFAULT_IPFS_API_URL, type IpfsAddResult } from '../../../storage/ipfs.js'
 import { agentIconContentType, isAgentIconUrl, validateAgentIconReference } from '../../../profile/agentIcon.js'

package/src/identity/manager/shared/effects/types.ts

@@ -0,0 +1,30 @@
+import type { Address } from 'viem'
+import type { EthagentIdentity } from '../../../../storage/config.js'
+import type { BrowserWalletReady } from '../../../wallet/browserWallet.js'
+import type { Step } from '../../reducer.js'
+
+export type IdentityCompletionSource = 'create' | 'restore' | 'update'
+
+export type EffectCallbacks = {
+  onStep: (step: Step) => void
+  onWalletReady: (session: BrowserWalletReady | null) => void
+  onIdentityComplete: (identity: EthagentIdentity, message: string, source?: IdentityCompletionSource) => Promise<void>
+  onRestoreProgress?: (progress: RestoreProgress | null) => void
+  onTokenTransferProgress?: (progress: TokenTransferProgress | null) => void
+}
+
+export type RestoreProgress = {
+  phase: 'decrypting' | 'writing' | 'finishing'
+  label: string
+}
+
+export type TokenTransferProgress = {
+  phase: 'sender-sign' | 'target-sign' | 'pinning' | 'sender-transaction' | 'confirming'
+  walletRole: 'sender' | 'receiver' | 'none'
+  title: string
+  detail: string
+  label: string
+  expectedAddress?: Address
+  walletAction?: string
+}
+

package/src/identity/{hub → manager}/shared/model/copy.ts

@@ -27,7 +27,3 @@ export function copyableIdentityFields(identity?: EthagentIdentity, config?: Eth
   if (activeOperator) fields.push({ label: 'Operator Wallet', value: activeOperator })
   return fields
 }
-
-export function identityValuesCopyHint(_identity?: EthagentIdentity): string {
-  return 'Copy token and pointers'
-}

package/src/identity/{hub → manager}/shared/model/errors.ts

@@ -10,16 +10,17 @@ import {
   formatVaultBytecodeMismatchDetail,
 } from '../../../registry/vault.js'
 import { BrowserWalletError } from '../../../wallet/browserWallet.js'
+import { PinataUploadError } from '../../../storage/ipfs.js'
 import { TxGuardBusyError } from '../txGuard.js'
 import { shortAddress } from './format.js'
 
-export type IdentityHubErrorView = {
+export type IdentityManagerErrorView = {
   title: string
   detail?: string
   hint?: string
 }
 
-export function identityHubErrorView(err: unknown): IdentityHubErrorView {
+export function identityManagerErrorView(err: unknown): IdentityManagerErrorView {
   if (err instanceof ZodError) {
     const issue = err.issues[0]
     const path = issue?.path.join('.') ?? ''
@@ -88,6 +89,34 @@ export function identityHubErrorView(err: unknown): IdentityHubErrorView {
       hint: 'Switch to the expected wallet, confirm you have funds, then retry. If the wallet keeps reporting an internal RPC error, change the RPC endpoint in your wallet settings.',
     }
   }
+  if (err instanceof PinataUploadError) {
+    if (err.status === 403) {
+      return {
+        title: 'Pinata Storage Limit Reached',
+        detail: 'Pinata refused the upload (403). Your account is likely at its file or storage limit; the free plan caps at 500 files.',
+        hint: 'Check your usage at https://app.pinata.cloud, remove old pins or upgrade your plan, then try again.',
+      }
+    }
+    if (err.status === 401) {
+      return {
+        title: 'Pinata Rejected the Credential',
+        detail: 'Pinata rejected the upload (401). Your Pinata JWT is invalid or expired.',
+        hint: 'Update your Pinata JWT in Storage settings, then try again.',
+      }
+    }
+    if (err.status === 429) {
+      return {
+        title: 'Pinata Rate Limited',
+        detail: 'Pinata is throttling uploads (429): too many requests in a short window.',
+        hint: 'Wait a moment, then try again.',
+      }
+    }
+    return {
+      title: 'Pinata Upload Failed',
+      detail: err.message,
+      hint: 'Check your Pinata account status at https://app.pinata.cloud, then try again.',
+    }
+  }
   const message = err instanceof Error ? err.message : String(err)
   if (/^owner wallet required:/i.test(message)) {
     return {
@@ -124,7 +153,7 @@ export function identityHubErrorView(err: unknown): IdentityHubErrorView {
 }
 
 export function pinataErrorText(err: unknown): string {
-  const view = identityHubErrorView(err)
+  const view = identityManagerErrorView(err)
   return view.detail ?? view.title
 }
 

package/src/identity/{hub → manager}/shared/model/network.ts

@@ -12,8 +12,8 @@ export function networkLabel(network: SelectableNetwork): string {
 }
 
 const NETWORK_SUBTITLES: Record<SelectableNetwork, string> = {
-  mainnet: 'Best for high-value identities and highest security',
-  base:    'Best for lower-cost setup and routine updates',
+  mainnet: 'Best for security',
+  base:    'Best for lower-cost use',
 }
 
 export function networkSubtitle(network: SelectableNetwork): string {

package/src/identity/{hub → manager}/shared/reconciliation/agentReconciliation/hook.ts

@@ -2,6 +2,7 @@ import { useEffect, useState } from 'react'
 import type { EthagentConfig } from '../../../../../storage/config.js'
 import { emptyReconciliation, runReconciliation } from './run.js'
 import type { AgentReconciliation } from './types.js'
+import { isDemoMode, synthDemoReconciliation } from '../../../../../cli/demo.js'
 
 export function useAgentReconciliation(
   config: EthagentConfig | null,
@@ -19,6 +20,10 @@ export function useAgentReconciliation(
   const [refreshKey, setRefreshKey] = useState(0)
 
   useEffect(() => {
+    if (isDemoMode()) {
+      setReconciliation(synthDemoReconciliation())
+      return
+    }
     if (!config?.identity || !config.identity.agentId || !config.identity.chainId || !config.identity.identityRegistryAddress) {
       setReconciliation(emptyReconciliation())
       return

package/src/identity/{hub → manager}/shared/reconciliation/agentReconciliation/run.ts

@@ -262,7 +262,7 @@ function computeDriftCount(r: AgentReconciliation): number {
   let n = 0
   if (r.token === 'unlinked') n++
   if (r.custody === 'mid-flow-uri-pending') n++
-  if (r.agentUri === 'local-newer' || r.agentUri === 'chain-newer') n++
+  if ((r.agentUri === 'local-newer' || r.agentUri === 'chain-newer') && r.custody !== 'mid-flow-uri-pending') n++
   if (r.vault === 'missing') n++
   if (r.workingTree === 'dirty') n++
   return n

package/src/identity/{hub/shared/reconciliation/useAgentReconciliation.ts → manager/shared/reconciliation/index.ts}

@@ -8,3 +8,9 @@ export type {
   OwnershipGuardResult,
   OwnershipRole,
 } from './agentReconciliation/ownership.js'
+export {
+  computeApprovalDiff,
+} from './walletSetup.js'
+export type {
+  ApprovalDiff,
+} from './walletSetup.js'